Skip to content

docs(adr): neutral network egress tiers (strict/balanced/open) for all backends - #299

Merged
wz-gsa merged 2 commits into
mainfrom
docs/adr-neutral-network-tiers
Aug 12, 2026
Merged

docs(adr): neutral network egress tiers (strict/balanced/open) for all backends#299
wz-gsa merged 2 commits into
mainfrom
docs/adr-neutral-network-tiers

Conversation

@wz-gsa

@wz-gsa wz-gsa commented Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Proposes ADR 0002 (isolation): a backend-agnostic network.tier vocabulary (strict | balanced | open) extending the neutral hybrid/v1 kit spec, so sbx, msb, and future backends share one consistent egress surface. Design approved 3/3 by consensus + tradeoff panel.

Why

caps.network.allow (per-kit host allowlist) is already consumed by both backends, but there's no neutral policy tier: sbx has manual CLI tiers, msb is default-deny = kit hosts only. No shared "useful-but-safe" baseline; the balanced convenience is sbx-only and manual.

Decision (proposed)

  • network.tier = strict (deny-by-default, kit allows only) | balanced (deny-by-default + a curated baseline ∪ kit allows) | open (testing only). All tiers keep deny-by-default.
  • balanced baseline = a curated, SHA-pinned, in-repo data file; maintainer-owned, community-extended via PR gated by CODEOWNERS + security-skill review.
  • No runtime threat-feed fetch (offline/deterministic); reputation feed is a CI-time check on proposed allowlist additions only.
  • Default: balanced (maintainer decision, 2026-08-07) — backend-consistent with the sbx baseline the project recommends AND quickstart ADR-0018 (feat/msb-balanced-egress), which already ships msb balanced-on by default. strict and open stay explicitly selectable; GFE / high-assurance SHOULD pin strict. The 3/3 consensus preferred a fail-safe strict default over the prompt-injection exfil risk; the maintainers reconsidered for backend consistency and mitigate the residual via the curated + CODEOWNERS-gated allowlist rather than defaulting closed.

Governance note

What belongs on the federally-shipped balanced allowlist is a human/CODEOWNERS + security-review decision — agents may propose entries (with the CI reputation signal) but never self-approve.

Status

Proposed — requires human review. No code yet; implementation tracked in a follow-up epic (schema vocab + curated baseline data + adapter mapping for both backends + CI reputation check + docs).

AI-assisted (OpenCode); consensus-reviewed (3/3). Requires human review.

@wz-gsa
wz-gsa requested a review from a team as a code owner August 7, 2026 20:56
This was referenced Aug 7, 2026
Closed
Closed
Closed
Open
@wz-gsa

wz-gsa commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator Author

Cross-reference: Bret's feat/msb-balanced-egress implements the msb half of this

Bret has pushed feat/msb-balanced-egress on agentic-coding-quickstart (5 commits, HEAD eb4ab19; no PR yet). It is a concrete, working implementation of the msb side of the tier this ADR proposes, and it explicitly names this ADR as its future migration target (ADR-0018 "Alternatives considered" → "Author a new neutral balanced-egress kit in agentic-coding-patterns… Deferred; the vendored file can migrate into such a kit later without changing the emitter.").

What it does (quickstart docs/adr/0018-msb-balanced-egress-baseline.md):

  • Vendors acq.backends/msb-balanced-hosts.txt — a verbatim mirror of sbx policy inspect local-policy's network allow rows (auditable, diffable, re-synced by copy-paste).
  • The msb adapter (_acq_msb_balanced_rules_into) translates each entry into an msb --net-rule, emits --net-default deny + the allow@… rules → genuine deny-by-default + allowlist parity with sbx balanced (not "allow-all with extras").
  • **./*. → msb domain-suffix *.host; :PORT → :tcp:<port> (dual-port preserved); crl*.digicert.com broadened to *.digicert.com (logged — the one place msb is intentionally wider than sbx); a leading allow@dns rule (deny-default disables the high-level DNS auto-grant).
  • SI-10 hardening on the semi-trusted list (charset + port validation, single-label *.com rejection, leading-zero-port rejection, malformed lines dropped with warning).
  • Toggle ACQ_MSB_BALANCED_EGRESS, default ON.

How this maps onto this ADR:

One reconciliation to settle: the default posture. ADR-0018 defaults balanced ON (sbx parity, best DX). This ADR (as originally drafted) proposed fail-safe strict because the 3/3 consensus flagged the prompt-injection exfiltration risk of an implicit balanced default. Decision (human, this session): balanced-on wins — align the neutral tier with ADR-0018's default so the two backends behave consistently and users get the parity Bret's work delivers. I am updating this ADR's Decision section to make balanced the shipped default (still deny-by-default + allowlist; strict and open remain selectable; the exfil risk is documented as a residual mitigated by the curated+CODEOWNERS-gated allowlist rather than by defaulting closed).

Net: no duplication/conflict of effort — ADR-0018 is the msb worked example that this neutral ADR generalizes. The follow-up epic (#303) should adopt Bret's emitter + host-list under the neutral network.tier contract rather than re-implement, and decide where the canonical baseline lives (his note already anticipates migrating the vendored file into a patterns kit).

/cc @mogul — heads-up that this ADR and your feat/msb-balanced-egress intersect; flagging so we converge on one neutral tier contract (and the shared baseline location) rather than two parallel designs. No code changes from me pending your PR.

AI-assisted (OpenCode); human-reviewed.

@mogul

mogul commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

It is a concrete, working implementation of the msb side of the tier this ADR proposes, and it explicitly names this ADR as its future migration target (ADR-0018 "Alternatives considered" → "Author a new neutral balanced-egress kit in agentic-coding-patterns… Deferred; the vendored file can migrate into such a kit later without changing the emitter.").

Note, NOT working yet... Still fixing bugs.

@mogul

mogul commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Note, NOT working yet... Still fixing bugs.

It's ALIVE!

@mogul mogul mentioned this pull request Aug 7, 2026
Merged
@mogul

mogul commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

feat/msb-balanced-egress is now merged in -quickstart. Upstream, an msb maintainer made a reasonable proposal for a way to specify just the network policy, and they've got an PR that adds that feature in flight.

@wz-gsa wz-gsa mentioned this pull request Aug 11, 2026
Merged
@wz-gsa
wz-gsa force-pushed the docs/adr-neutral-network-tiers branch from 71e7011 to 045c70a Compare August 12, 2026 12:43
mogul
mogul approved these changes Aug 12, 2026
View reviewed changes
Comment thread integrations/isolation/docs/decisions/0002-neutral-network-egress-tiers.md
Comment on lines +112 to +113
- **msb** — `--net-rule allow@<host>` for each host in the merged allowlist
(deny-by-default is already msb's behavior when net-rules are present).

@mogul mogul Aug 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably worth leaving a pointer to msb's scoped configuration feature, since it looks like it will ship in the next version.

Comment thread integrations/isolation/docs/decisions/0002-neutral-network-egress-tiers.md
something we vouch is safe for a prompt-injectable agent to reach. Even curated,
each entry (a registry, a model API, a source host) is a potential exfiltration
channel — `balanced` widens blast radius vs `strict`. Mitigated by: CODEOWNERS +
security-skill review on additions, the CI reputation check, keeping the list

@mogul mogul Aug 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the reputation check was removed, wasn't it?

wz-gsa added a commit that referenced this pull request Aug 12, 2026
@wz-gsa
feat(kits): add neutral network.tier vocab (strict/balanced/open) to …
3f51984 
…hybrid/v1 (#300) (#313)

First implementation of the neutral-network-tiers epic (#303; design in ADR
0002 / PR #299). Adds a `tier` sibling to the existing `caps.network` block in
schemas/kit-hybrid-v1.schema.json (draft-2020-12 enum): strict | balanced |
open, schema default `balanced`.

- ALL tiers are deny-by-default; the tier only sizes the baseline allowlist.
  strict = kit `allow` only; balanced = curated shared baseline ∪ kit `allow`
  (the default when unspecified, per the 2026-08-07 maintainer decision — backend-
  consistent with the sbx baseline + quickstart msb-balanced-egress default);
  open = unrestricted (testing only, never GFE). Effective allowlist = tier
  baseline ∪ kit allow ∪ per-sandbox additions.
- Coexists with the existing `caps.network.allow` (unchanged).
- validate-kits.py: schema enum already rejects bad values; added a kit-scoped
  field-level message for a clearer error. Default is DOCUMENTED, not mutated —
  consistent with the validator's existing non-mutating, validation-only posture.
- INDEX/CATALOG generators don't read the network block, so nothing to update there.

Tests: schema (absent-valid, all 3 tiers, coexists-with-allow, bad-value +
wrong-type + typo-key rejected) + validator (valid/absent pass, bad-tier
message). 322 tests pass; make validate green; ruff clean.

Unblocks #301 (balanced baseline data file) + quickstart #294 (adapter mapping).
Closes #300.

AI-assisted (OpenCode); consensus-reviewed (3/3 on the tier design). Requires human review.
@wz-gsa
wz-gsa force-pushed the docs/adr-neutral-network-tiers branch from 045c70a to f87208e Compare August 12, 2026 19:22
wz-gsa added 2 commits August 12, 2026 15:24
@wz-gsa
docs(adr): neutral network egress tiers (strict/balanced/open) for al…
5a3258c 
…l backends

Propose ADR 0002 (isolation): a backend-agnostic `network.tier` vocabulary
(strict|balanced|open) extending the neutral hybrid/v1 kit spec, so sbx, msb, and
future backends share ONE consistent egress surface.

- Today: `caps.network.allow` (per-kit host allowlist) is already consumed by
  both backends, but there is no neutral policy *tier* — sbx has manual CLI tiers
  (deny-all/balanced/allow-all), msb is default-deny = kit hosts only. No shared
  "useful-but-safe" baseline.
- Decision: add `network.tier`; all tiers preserve deny-by-default. `balanced` =
  deny-by-default + a curated, SHA-pinned, IN-REPO baseline allowlist (registries,
  AI APIs, common source hosts) unioned with per-kit allows; maintainer-owned,
  community-extended via PR gated by CODEOWNERS + security-skill review.
- NO runtime threat-feed fetch (offline/deterministic); a reputation feed is a
  CI-time check on PROPOSED allowlist additions only.
- Default: fail-safe `strict` when unspecified; shipped config explicitly sets
  `balanced` (users get the baseline, but as an explicit/auditable choice, and
  omission fails closed). Reconciles a 3/3 consensus that flagged the
  prompt-injection exfiltration risk of an implicit balanced default.

Status: proposed (human review required). Implementation tracked in a follow-up
epic. SC-7/SC-7(5)/AC-4/CM-7.

AI-assisted (OpenCode); consensus-reviewed. Requires human review.

Co-authored-by: OpenCode [claude_4_8_opus] <william.zujkowski@gsa.gov>
@wz-gsa
docs(adr): set balanced as default tier for sbx/msb consistency
11176b1 
Reconcile ADR 0002's default posture with quickstart ADR-0018
(feat/msb-balanced-egress), which already ships msb balanced-egress
default-on for sbx parity. A strict-by-omission neutral default would
make the two backends inconsistent and remove the parity UX ADR-0018
delivers, so the maintainers set the default to balanced (deny-by-default
+ curated allowlist, not allow-all). strict and open stay explicitly
selectable; GFE / high-assurance SHOULD pin strict. The 3/3 consensus
preferred fail-safe strict over the prompt-injection exfil risk; that
residual is now mitigated by the curated + CODEOWNERS-gated allowlist
rather than by defaulting closed. Cross-reference ADR-0018 as the msb
worked example this neutral tier generalizes.

Co-authored-by: OpenCode Agent <william.zujkowski@gsa.gov>
@wz-gsa
wz-gsa force-pushed the docs/adr-neutral-network-tiers branch from f87208e to 11176b1 Compare August 12, 2026 19:24
@wz-gsa
wz-gsa merged commit 6ea3bba into main Aug 12, 2026
7 checks passed
@wz-gsa
wz-gsa deleted the docs/adr-neutral-network-tiers branch August 12, 2026 19:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mogul mogul mogul approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@wz-gsa @mogul