agentleFS
schmitthubschmitthub/clawker/.agents/skills/firewall-uat/SKILL.md

firewall-uat

Skill59 starsChanged 12 days agoMITView on GitHub

Live egress probes that prove firewall enforcement from inside a clawker container. Use after any change to controlplane/firewall generator or rule code, before you declare that work complete, and for an authorized firewall UAT task. Golden files and envoy validate do not cover this.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Ask them to add/remove rules.

    line 21
  2. Very specific:

    No tool here drives an h2/h3 Extended CONNECT WebSocket (websocat = h1.1 only.

    line 38
  3. Very specific:

    If the harness runs shell commands in a network sandbox, the probe cannot reach the firewall.

    line 44

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Firewall Runtime UAT

Golden files + envoy --mode validate prove the generated config is valid. They do NOT prove behavior. Behavior is verified live, and you are the vehicle: when $CLAWKER_AGENT is set, this agent session runs inside a clawker agent container whose egress is routed through the live firewall stack (eBPF redirect → Envoy → CoreDNS). Exercising egress from this shell IS the behavioral test.

Roles

  • You (in-container): exercise egress with the probe tools below. You CANNOT run host clawker; the CLI runs on the host only.
  • User (host operator): mutates rules host-side — clawker firewall add <host> [--proto https|http|ssh|tcp|wss|...] [--port N|lo-hi] [--path /p --action allow|deny]. Ask them to add/remove rules; then you re-probe. To live-apply a clawker.yaml egress edit (security.firewall.add_domains / security.firewall.rules) without a restart, have them run clawker firewall refresh (global, no --agent; add/update only — deletes still go through clawker firewall remove).

clawker firewall add flags: --proto (default https), --port (default proto-specific; single port 443 or inclusive range 9000-9100), --path + --action (path-scoped rule, required together).

Probe tools available in-container

curl, ssh (+ forwarded host agent), nghttp + h2load (HTTP/2 + h2 WS; h2load also does h3 — useful for the QUIC/alt-svc sibling), websocat, wscat, python3, openssl, gh, git. nc is absent. The SSH agent is the host's, live-mirrored through the socketbridge (fresh net.Dial per connection — no cache; ssh-add -l reflects host agent state at that instant).

No tool here drives an h2/h3 Extended CONNECT WebSocket (websocat = h1.1 only; nghttp -u = h2c upgrade, not WS). So WS-over-h1.1 is runtime-testable (websocat wss://…/ws/echo → C2 echoes the frame back through the MITM), but the h2 (allow_connect) / h3 (allow_extended_connect) WS paths are only config-confirmable (grep -c allow_connect), not live-drivable in-container.

If the harness runs shell commands in a network sandbox, the probe cannot reach the firewall. Disable the sandbox for probe commands (Claude Code: dangerouslyDisableSandbox: true on the Bash tool).

Behavioral discriminators (HARD-won — memorize)

observationmeaning
NXDOMAIN / "could not resolve host"host not in allowlist — blocked at CoreDNS (layer 2)
HTTP 403, body Forbidden\nclawker host/path deny (firewallBlockedBody) — Envoy path/vhost gate
HTTP 403, EMPTY body, server: envoyEnvoy upgrade refused (WS upgrade on a non-wss route — no upgrade_configs) — NOT a clawker deny
server: envoy + x-envoy-upstream-service-time + upstream's own code (e.g. 404)request reached the real upstream = allowed
ssh -Tv → Authenticated to <host> ([<EnvoyIP>]:<port>)shows the Envoy hop + the dedicated-listener port (TCPPortBase+idx, one per opaque host)
access log response_code:0 + response_flags:DC + response_code_details:downstream_remote_disconnectclient disconnected before the response — NOT a block (action:allowed). Normal uv/pip/npm h2 stream-cancel churn.

clawker-net is an allowlist, not an egress-test surface. The eBPF programs deny every in-subnet destination in the kernel (EPERM on connect() / sendto()) except Envoy (any port), CoreDNS on 53, and the CP on its agent (7444) and Hydra (4444) ports. Another agent's clawker-net IP is therefore unreachable. The C2 is not on clawker-net: it runs on clawker-adversarial and listens only on host ports (test/adversarial/AGENTS.md). An egress-attack test needs a PUBLIC dst (through Envoy), e.g. the C2's ngrok edge. Confused-deputy's structural defense is config-verifiable: FQDN flows are all LOGICAL_DNS/DFP, ZERO ORIGINAL_DST/use_original_dst (those appear only for IP/CIDR rules, the range-validated carve-out).

Intra-subnet probes (nc is absent; bash's /dev/tcp and /dev/udp do a real connect(), so a denial is the kernel's Permission denied, never a missing listener). Get the IPs from the host with docker inspect -f '{{(index .NetworkSettings.Networks "clawker-net").IPAddress}}' <container>:

probeexpect
timeout 3 bash -c 'exec 3<>/dev/tcp/<other-agent-ip>/22'Permission denied
timeout 3 bash -c 'echo x > /dev/udp/<other-agent-ip>/9'Permission denied
timeout 3 bash -c 'exec 3<>/dev/tcp/<cp-ip>/7444'exit 0 (connects)
timeout 3 bash -c 'exec 3<>/dev/tcp/<cp-ip>/4444'exit 0 (connects)
timeout 3 bash -c 'exec 3<>/dev/tcp/<cp-ip>/7080'Permission denied
getent hosts host.docker.internalfails with no rule; resolves after firewall add host.docker.internal (exact name only)
curl -s -o /dev/null -w '%{http_code}' -X POST http://127.0.0.1:18374/open/url -d '{"url":"https://denied.invalid/"}'403 from the CP (host actions go clawkerd relay -> CP -> host proxy; a denied URL never opens a browser). The relay listens on 127.0.0.1:18374 (consts.AgentHostRelayAddr). CLAWKER_HOST_PROXY is set only when the container has the host proxy grant.
dig +tcp @127.0.0.11 -p <port of the 0B00007F listener in /proc/net/tcp> example.comno servers could be reached (Docker resolver denied; NOERROR = DNS bypass)
python3 -c 'import socket; socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_ICMP)'PermissionError (ping socket denied at create; success = ICMP tunnel)
python3 -c 'import socket; socket.socket(socket.AF_INET, socket.SOCK_STREAM, 132)'PermissionError (SCTP denied at create; success = egress outside the connect hooks)
python3 -c 'import socket; socket.socket(socket.AF_INET, socket.SOCK_DGRAM, 136)'PermissionError (UDP-Lite denied at create; success = egress outside the sendmsg hook)
getent hosts clawker-controlplaneresolves to the CP static IP (A record only; a non-A query gets an empty answer)
(operator, host) clawker exec -u root --agent X -- getent hosts <domain not on the allow list>no answer (an answer = the uid-0 exemption is back).

Host-side e2e counterparts (test/e2e/firewall_test.go): TestFirewall_IntraSubnetAllowlist, TestFirewall_HostActionsBehindCP, TestFirewall_DockerInternalDNS, TestFirewall_DockerDNSDirectPortDenied, TestFirewall_ICMPBlocked, TestFirewall_SocketTypeAllowlist, TestFirewall_RootEnforced, TestFirewall_CPNameResolves.

SSH routing is special — banner is the only proof. Any real SSH server completes a valid handshake, so a misroute ("everything funneled to host X") still returns a valid ssh -T response. The TRUE upstream is discriminated by the banner / remote software version (GitHub: …version 6279353 + "does not provide shell access"; GitLab: GitLab-SSHD + "Welcome to GitLab"). For opaque-host fan-out (n≥2), also confirm each host lands on a distinct [<EnvoyIP>]:<port> — same port = collision/misroute.

Permission denied (publickey) on an opaque-ssh probe is a routing PASS (real daemon negotiated auth then rejected the key) — auth ≠ routing.

Spot-checking the live generated config

Dev config (when .clawkerlocal/ XDG overrides are active): .clawkerlocal/.local/share/clawker/firewall/envoy.yaml — ~31k lines, grep/ sed only, never full-read. Corefile / rules / certs are siblings. Use it to ground a runtime result in the artifact (e.g. grep -c upgrade_configs to confirm 0 when no wss rule exists). The .clawkerlocal/ override layout is in the Serena project-guide memory.

Adversarial C2 harness

test/adversarial/ — Go C2 + SQLite, exposed via ngrok at ajschmitt.ngrok.app (stable host). For exfil-block tests: try to reach a non-allowlisted host/path/ proto and confirm the block. Allowlisted subset is operator-controlled per run (e.g. https /ws/ + /allowed/ only). See test/adversarial/AGENTS.md.

What golden/validate cannot catch (only live UAT can)

CP↔generator contract gaps. A past regression dropped the Envoy health listener: golden files and validate passed, and CP bringup hung on the readiness probe. Run live UAT before declaring the generator branch done.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.