docs(egress): contained-mode egress-jail doctrine + docs flip (PR 3/3)#156
Merged
Conversation
…3/3) Close the code<->doctrine desync left after slices 1+2 merged the egress-jail code: the doctrine still described contained mode as "Phase 1 — egress open". CLAUDE.md INV-9: replace the PHASE 1 NOTE with the egress-jail rule (internal:true bridge + per-session tinyproxy sidecar, deny-by-default CONNECT allowlist on 443, add-only baseline, zero new Linux caps); append the Phase 2 failure mode to Why; rewrite Honest framing to name all 7 residual gaps (a-g), including the shared internal-bridge gap (g); append the egress code paths to Where. Update the §4 threat-model boundary. §3 carried no egress-open claim, so no edit was needed. docs: security.md (egress rewrite + residual-gaps subsection a-g), README, architecture.md (dual-bridge + sidecar topology), troubleshooting.md (domain-not- reachable how-to + 403 + doctor EGRESS + drydock_net upgrade note), ROADMAP (Phase 2 -> Done), CHANGELOG (egress-jail entry). INV-8 intact: the sidecar runs cap_drop: ALL with zero cap_add; the agent cap_add is unchanged. dood mode untouched. The baseline is framed as provisional (finalized by the v0.4.0 release gate). scripts/test.sh 1137/1137 green.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Slice 3/3 of the Phase 2 egress jail (issue #149, v0.4.0). Slices 1+2 (#154, #155)
merged the egress-jail code to
dev; the doctrine still said"Phase 1 — contained mode does NOT filter egress". This PR closes that
code↔doctrine desync. Prose only — no behavior change.
Changes (7 files, +215 / -46)
PHASE 1 NOTEclause; the Rule now describesthe egress jail (
internal: truebridge + per-session tinyproxy sidecar,deny-by-default CONNECT allowlist on 443, add-only baseline, zero new Linux
caps). Appended the Phase 2 failure mode to Why; rewrote Honest framing
to name all 7 residual gaps (a)–(g), including the shared internal-bridge
gap (g) (concurrent sessions share one
internalbridge → a peer session'ssidecar is reachable; accepted-but-named, out of scope). Appended the egress
code paths to Where. Updated the §4 threat-model boundary.
residual-gaps subsection (a)–(g).
(dual-bridge
drydock_internal/drydock_egress+ per-session sidecar diagram).~/.config/drydock/egress-allowlist[-<project>]how-to +drydock doctorEGRESS section + a
drydock_netupgrade-cleanup note.egress-jail summary + allowlist pointer.
[Unreleased]egress-jail entry.Invariants
cap_drop: ALLwith zerocap_add; the agent'scap_addis unchanged from Phase 1. No new Linuxcapability is introduced anywhere. The doctrine states this explicitly.
Honest-framing acceptance (grep audit)
exfiltration-proof,egress-proof,sandboxed network,still threat model A,containment isn't sandboxing,not a security feature) — 0 occurrences.docs/security.md.
drydock_netappears in doc prose only in the troubleshootingupgrade-cleanup note; current topology is
drydock_internal/drydock_egress.release gate); the docs do not over-claim completeness.
Design deviation (documented)
Design §9a's draft closing sentence used the literal tokens
"egress-proof"/"exfiltration-proof"in a negation, which collides with the forbidden-phrasegrep (zero occurrences). Resolved in favor of the acceptance grep: the
"not a guarantee" disclaimer was reworded to keep the honest limitation without
the forbidden tokens.
Verification
scripts/test.sh— 1137/1137 green.docker-compose.contain.ymlandegress-baseline.conf): READY, 0 critical.sdd-verifyagainst REQ-7 / R7.1–R7.8 + scenarios R7-A..R7-E: PASS,0 critical / 0 warning.
Not in this PR
Release gates G1 (empirical baseline capture), G2 (runtime double-gate smoke),
G3 (v0.4.0 release) are maintainer-gated, bare-Linux, and tracked under #149 —
this PR does not close #149.
Refs #149.