Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
125 lines
6.5 KiB
Markdown
125 lines
6.5 KiB
Markdown
# ADR-003 — Enforce Scope and Approval Below Model Reasoning
|
|
|
|
## Metadata
|
|
|
|
- **ADR ID:** ADR-003
|
|
- **Status:** Accepted (retrospective baseline)
|
|
- **Decision date:** 2026-07-20
|
|
- **Authors:** Architecture baseline process
|
|
- **Reviewers:** Maintainer and safety-review roles; named human approval is not recorded
|
|
- **Supersedes:** None
|
|
- **Current level:** L4 — Implemented; verification is continuous in CI
|
|
|
|
## Context
|
|
|
|
### Problem
|
|
|
|
Models, imported repositories, and target responses are nondeterministic untrusted inputs. They can suggest off-scope hosts, dangerous operations, credential forwarding, or malformed arguments. The arsenal performs real security operations, so prompt-only rules cannot be the authorization boundary.
|
|
|
|
### Constraints
|
|
|
|
- Written authorization and target scope are operator responsibilities but must be represented at runtime.
|
|
- Built-in network-capable adapters have different argument and destination shapes.
|
|
- Some operations are materially dangerous even when in scope.
|
|
- Target-specific credentials must not follow redirects or unrelated origins.
|
|
- Safety failures must fail closed and remain testable without live targets.
|
|
|
|
### Stakeholders
|
|
|
|
- Target/system owners require activity to remain authorized.
|
|
- Operators need explicit control over dangerous actions.
|
|
- Safety reviewers need deterministic, auditable enforcement.
|
|
- Tool-adapter contributors need a clear integration contract.
|
|
|
|
## Source Verification and Claim Tracking
|
|
|
|
| Claim | Source | Verification |
|
|
| --- | --- | --- |
|
|
| Scope is enforced in target/arsenal paths | Target and arsenal modules | Scope-gate negative tests |
|
|
| Dangerous tools require approval | Arsenal approval module/catalog | Approval and approval-gate tests |
|
|
| Target credentials are origin-bound | Target/server request paths | Target-header static tests |
|
|
| Prompt/model output is not sufficient authority | Architecture and implementation boundary | Tool proposals still traverse deterministic gates |
|
|
|
|
## Decision
|
|
|
|
Enforce target authorization, egress containment, exact-origin credential routing, dangerous-tool approval, argument construction, and relevant timeouts in deterministic target/arsenal/runtime code below model reasoning. Prompts may explain policy, but they do not grant execution authority.
|
|
|
|
Every new network-capable or privileged adapter must declare its destination derivation, risk class, approval behavior, credential behavior, timeout, and negative tests. A bypass in these controls is a release-blocking defect.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Prompt-only safety policy
|
|
|
|
- **Pros:** Easy to change; uniform natural-language guidance.
|
|
- **Cons:** Nondeterministic, vulnerable to prompt injection, and cannot guarantee tool dispatch behavior.
|
|
- **Why not chosen:** It does not form an enforceable authorization boundary.
|
|
|
|
### Rely solely on operator review of every action
|
|
|
|
- **Pros:** Human judgment for all behavior.
|
|
- **Cons:** High fatigue, inconsistent review, and still vulnerable to hidden destination/argument transformations.
|
|
- **Why not chosen:** Human approval complements but cannot replace deterministic scope and secret controls.
|
|
|
|
### Isolate everything in containers and allow arbitrary execution
|
|
|
|
- **Pros:** Limits some host impact.
|
|
- **Cons:** Containers do not establish target authorization, prevent credential leakage, or guarantee egress scope.
|
|
- **Why not chosen:** Isolation is defense-in-depth, not an authorization model.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- Prompt compromise does not automatically authorize real execution.
|
|
- Safety behavior can be tested deterministically and reviewed per adapter.
|
|
- Operator approval is attached to the actual classified action.
|
|
|
|
### Negative
|
|
|
|
- Adapter development requires more metadata, validation, and negative tests.
|
|
- Novel protocols and redirect behavior need careful destination modeling.
|
|
- False refusals are possible when scope cannot be derived safely.
|
|
|
|
## Risks and Mitigations
|
|
|
|
| Risk | Likelihood / impact | Mitigation |
|
|
| --- | --- | --- |
|
|
| Adapter bypasses central gate | Medium / Critical | Inventory every network-capable adapter; mandatory scope/approval tests |
|
|
| Argument or shell injection | Medium / Critical | Structured argument construction, validation, no generic arbitrary execution |
|
|
| Credential follows redirect/origin change | Low / Critical | Exact-origin binding and negative tests |
|
|
| Approval UI obscures actual impact | Medium / High | Present classified tool/action/target; approval never bypasses scope |
|
|
|
|
## Implementation and Verification
|
|
|
|
- **Authorization/scope:** `src/target/index.ts`, `src/opsec/`, and arsenal validation/gates.
|
|
- **Approval:** `src/arsenal/approval.ts` plus catalog risk metadata.
|
|
- **Secret boundary:** Exact-origin target-header behavior and redaction paths.
|
|
- **Concurrency/state:** Approval applies to the concrete pending action; async/parallel task scheduling must not reuse approval for a materially different target/action.
|
|
- **Testing:** Arsenal scope/approval/validation, target-header, parameter splitting/types, tool error, proxy bypass, and redaction suites.
|
|
- **Regression guard:** Security-control failures block release and cannot be waived by model quality or benchmark success.
|
|
|
|
## Definition of Done
|
|
|
|
- [x] Deterministic enforcement boundary documented and implemented.
|
|
- [x] Scope, approval, secret, and argument risks mapped to tests.
|
|
- [x] UC-001 and NFR-01/02/05 trace to the decision.
|
|
- [ ] Complete machine-maintained inventory maps every network-capable adapter to its scope and approval test.
|
|
- [ ] Named safety-review approval is recorded.
|
|
|
|
## References
|
|
|
|
- @.aiwg/requirements/UC-001.md — Scoped mission and failure behavior.
|
|
- @.aiwg/requirements/nfr-register.md — NFR-01, NFR-02, and NFR-05.
|
|
- @.aiwg/intake/risk-screening.md — Scope, secret, and external-tool risks.
|
|
- @src/target/index.ts — Authorized-target representation.
|
|
- @src/arsenal/approval.ts — Dangerous-action approval policy.
|
|
- @src/arsenal/catalog.ts — Tool metadata and classifications.
|
|
- @src/__tests__/arsenal-scope-gate.test.ts — Off-scope refusal evidence.
|
|
- @src/__tests__/arsenal-approval-gate.test.ts — Approval enforcement evidence.
|
|
- @src/__tests__/target-headers-static.test.ts — Exact-origin credential evidence.
|
|
- @src/__tests__/param-split.test.ts — Argument construction evidence.
|
|
|
|
## Review and Approval
|
|
|
|
This retrospective ADR documents a current release-blocking safety invariant. Named historical sign-off is not available. Any amendment weakening default containment, authorization, approval, or exact-origin controls requires explicit maintainer and safety-review approval plus replacement tests.
|