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.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- clawkerd/AGENTS.mdAGENTS.md
- controlplane/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- test/AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- agent-filesSkill
- audit-memorySkill
- cli-outputSkill
- dev-checksSkill
- initiativeSkill
- monitoring-checksSkill
- store-editorSkill
- test-hunterSkill
- wizard-commandsSkill
- writing-testsSkill
- code-reviewSkill
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
- Very specific: line 21
Ask them to add/remove rules.
- Very specific: line 38
No tool here drives an h2/h3 Extended CONNECT WebSocket (websocat = h1.1 only.
- Very specific: line 44
If the harness runs shell commands in a network sandbox, the probe cannot reach the firewall.
≈ “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.
Files
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 aclawker.yamlegress edit (security.firewall.add_domains/security.firewall.rules) without a restart, have them runclawker firewall refresh(global, no--agent; add/update only — deletes still go throughclawker 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)
| observation | meaning |
NXDOMAIN / "could not resolve host" | host not in allowlist — blocked at CoreDNS (layer 2) |
HTTP 403, body Forbidden\n | clawker host/path deny (firewallBlockedBody) — Envoy path/vhost gate |
HTTP 403, EMPTY body, server: envoy | Envoy 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_disconnect | client 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>:
| probe | expect |
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.internal | fails 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.com | no 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-controlplane | resolves 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.
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
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.

