docs(secure-agent-setup): split technical details into secure-agent-internals.md - #21
Merged
Merged
Conversation
…nternals.md Splits the previous Part 1 / Part 2 single-file structure into two documents along the same line: - `secure-agent-setup.md` (kept) — context, installation, demonstration. The full install path, three new agent-guided prompts (first-time setup / verify / keep-updated), and the five session screenshots demonstrating each visible state stay here. An adopter who only wants the secure setup running reads this file end-to-end and stops. - `secure-agent-internals.md` (new) — the mental-model deep dive. How `sandbox.enabled` actually directs the Bash tool, how bubblewrap (Linux) and Seatbelt (macOS) enforce at the OS layer, the SNI / DoH blind spot motivating `Bash(curl *)` deny-listing, and the feedback-mechanism layering table. No screenshots — those remain in the setup doc, demonstrating the mechanisms this doc describes. Cross-references in both directions: setup → internals via the intro paragraph and a See-also bullet; internals → setup via the intro paragraph, the feedback-table cells, and a See-also section pointing at the screenshots and the install pages for each surfacing piece. Heading levels rebalanced for the split: setup's H3 sections become H2 (Part-wrapper dropped), H4 sub-sections become H3. Internals' H3-section title becomes the file H1, and its H4 sub-sections become H2. Generated-by: Claude Code (Opus 4.7)
4 tasks
potiuk
added a commit
that referenced
this pull request
May 1, 2026
…+ defence + residual risks to internals (#22) The previous split (PR #21) left context (threat model, three-layer defence) and residual-risks discussion in the adopter-facing secure-agent-setup.md, with only the mechanism deep dive in secure-agent-internals.md. Adopters had to read two pages of theory before the first install command. Re-cuts the line so: - secure-agent-setup.md is adopter-only — a focused install path (required tools → framework settings.json → clean-env wrapper → bypass hook → status line → multi-host sync → adopter recipe → verify → keep-updated → what a session looks like). New intro explicitly names the audience as adopters and points design / rationale readers to the internals doc. - secure-agent-internals.md is the design + how-it-works companion — threat model, three-layer defence, the existing mechanism deep dive (sandbox.enabled / bubblewrap / Seatbelt / SNI-DoH blind spot / feedback layering), and residual risks. New intro names the audience as anyone modifying the setup or debugging an unexpected denial / allow. Cross-references updated: internals' three-layer-defence "Adopter setup" reference now goes cross-doc to setup#adopter-setup; see-also blocks rewritten on both files; internals title broadened from "How sandbox isolation works" to "Secure agent setup — how it works" since the file now covers context on top of mechanism. Generated-by: Claude Code (Opus 4.7)
andreahlert
added
the
mode:platform
21 tasks
potiuk
pushed a commit
to justinmclean/airflow-steward
that referenced
this pull request
Jul 8, 2026
Add check apache#21 (SOFT advisory) to skill-and-tool-validator that flags network-calling imports (requests, httpx, aiohttp, urllib.request, http.client, socket) in substrate:* tool source files under tools/*/src/. Only contract:* adapter tools and the egress-gateway proxy are declared egress surfaces; all other substrate tools must stay network-free to uphold PRINCIPLE 10's guarantee of zero default outbound calls. Also add a Declared egress surfaces section to tools/egress-gateway/tool.md that states the default-zero guarantee, lists the declared egress surfaces, and cross-references the new validator check. Generated-by: Claude (claude-sonnet-4-6)
potiuk
pushed a commit
that referenced
this pull request
Jul 8, 2026
…e) (#763) Add check #21 (SOFT advisory) to skill-and-tool-validator that flags network-calling imports (requests, httpx, aiohttp, urllib.request, http.client, socket) in substrate:* tool source files under tools/*/src/. Only contract:* adapter tools and the egress-gateway proxy are declared egress surfaces; all other substrate tools must stay network-free to uphold PRINCIPLE 10's guarantee of zero default outbound calls. Also add a Declared egress surfaces section to tools/egress-gateway/tool.md that states the default-zero guarantee, lists the declared egress surfaces, and cross-references the new validator check. Generated-by: Claude (claude-sonnet-4-6)
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
2 participants
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.
Summary
Splits
secure-agent-setup.mdalong its existing Part 1 / Part 2 line into two files:secure-agent-setup.md(kept) — context, installation, demonstration. Five session screenshots stay here. Sufficient on its own to install + verify + keep-updated.secure-agent-internals.md(new) — mental-model deep dive: bubblewrap/Seatbelt enforcement, SNI/DoH blind spot, feedback-mechanism layering. Optional reading.Heading levels rebalanced: setup's H3→H2, H4→H3 (Part wrappers dropped). Internals' new H1 is the file title; sub-sections become H2.
Cross-refs both ways via intro paragraphs and See-also blocks.
Test plan
prek run --files secure-agent-setup.md secure-agent-internals.mdclean (markdownlint MD051 anchor checks pass for both files including cross-doc links).secure-agent-setup.mdstill resolve fromimages/.