Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
124 lines
6.3 KiB
Markdown
124 lines
6.3 KiB
Markdown
# UC-001 — Conduct a Scoped Security Mission
|
|
|
|
## Metadata
|
|
|
|
- **ID:** UC-001
|
|
- **Status:** Baselined (brownfield)
|
|
- **Level:** User goal
|
|
- **Scope:** Mission, target, orchestration, arsenal, evidence, and reporting subsystems
|
|
- **Primary actor:** Authorized operator
|
|
- **Goal:** Execute a reconnaissance-to-report mission against an explicitly authorized target without exceeding the rules of engagement.
|
|
- **Related stories:** US-01, US-02, US-04, US-05
|
|
- **Quality drivers:** NFR-01, NFR-02, NFR-03, NFR-05, NFR-08
|
|
|
|
## Preconditions
|
|
|
|
- The operator has written authorization and has identified the target and allowed activity.
|
|
- Required tools and model or connected-agent configuration are available.
|
|
- The operator can review high-impact actions and retain evidence securely.
|
|
|
|
## Trigger
|
|
|
|
The operator starts a mission with a target definition and rules of engagement through a supported entry surface.
|
|
|
|
## Main Success Scenario
|
|
|
|
1. The operator supplies the target, allowed scope, objectives, and execution constraints.
|
|
2. The system normalizes and validates the target and creates an authorized mission context.
|
|
3. The Admiral produces a task plan and assigns work to operator roles.
|
|
4. Each operator proposes tool activity against the authorized mission context.
|
|
5. The runtime validates scope, arguments, approval class, and timeout before dispatch.
|
|
6. Approved arsenal adapters execute and return structured observations.
|
|
7. The system records raw evidence separately from candidate findings.
|
|
8. Candidate findings are adjudicated or independently verified against retained evidence.
|
|
9. The reporting path emits a result that identifies evidence and verification state.
|
|
10. The operator reviews the result and controls any disclosure or external delivery.
|
|
|
|
## Alternate Flows
|
|
|
|
### A1 — Planning without a cloud API key
|
|
|
|
At step 3, the operator selects a connected local coding agent or local OpenAI-compatible provider. The shared mission and safety behavior remains unchanged; UC-002 supplies the provider flow.
|
|
|
|
### A2 — Read-only or non-dangerous operation
|
|
|
|
At step 5, the requested tool is classified as non-dangerous. The system may dispatch without an interactive approval while still enforcing target scope and argument validation.
|
|
|
|
### A3 — Candidate finding is refuted
|
|
|
|
At step 8, verification cannot reproduce or substantiate the candidate. The system retains the evidence and refutation outcome but does not promote the candidate to a verified finding.
|
|
|
|
## Exception Flows
|
|
|
|
### E1 — Target is outside scope
|
|
|
|
1. Scope validation rejects the target or derived destination.
|
|
2. No network tool is dispatched and no target credential is attached.
|
|
3. The system records a refusal suitable for operator diagnosis.
|
|
|
|
### E2 — Dangerous action is not approved
|
|
|
|
1. The runtime presents the action and relevant risk information for approval.
|
|
2. The operator rejects or does not approve the action.
|
|
3. Execution stops at the gate; the mission may continue with safer alternatives.
|
|
|
|
### E3 — Tool, provider, or task times out
|
|
|
|
1. The configured timeout terminates or abandons the bounded operation.
|
|
2. The system records failure context without converting it into a successful observation.
|
|
3. The planner may retry only through declared fallback behavior.
|
|
|
|
## Postconditions
|
|
|
|
### Success
|
|
|
|
- Mission state records the completed activity and disposition.
|
|
- Reported findings retain a path to evidence and verification state.
|
|
- No tool execution or credential forwarding occurred outside authorized scope.
|
|
|
|
### Failure
|
|
|
|
- The system fails closed for authorization, scope, approval, and credential-routing failures.
|
|
- Partial observations remain distinguishable from verified findings.
|
|
|
|
## Special Requirements
|
|
|
|
- **Safety:** Out-of-scope public network access is denied by deterministic controls, not model judgment alone.
|
|
- **Authorization:** Real operations require an explicit authorized target context.
|
|
- **Secret isolation:** Target headers are sent only to their configured exact origin.
|
|
- **Evidence:** Finding claims identify retained evidence or a reproducible receipt.
|
|
- **Testability:** CI exercises deterministic negative paths without live targets or paid models.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Given an authorized target, when a mission starts, then every dispatched network action carries the validated target context.
|
|
- [ ] Given an unrelated public host, when a tool attempts access, then the action is rejected before dispatch.
|
|
- [ ] Given a dangerous action, when approval is absent or rejected, then no corresponding tool process starts.
|
|
- [ ] Given target-specific credentials, when a redirect or different origin is requested, then credentials are not forwarded.
|
|
- [ ] Given a candidate finding, when it is reported as verified, then evidence and verification state are present.
|
|
- [ ] Given a tool or reasoning timeout, when the deadline expires, then the mission records an explicit failure or declared fallback rather than a false success.
|
|
|
|
## Design and Test Traceability
|
|
|
|
| Concern | Design / implementation | Verification |
|
|
| --- | --- | --- |
|
|
| Mission lifecycle | `src/mission/`, `src/admiral/`, `src/orchestration/`, `src/operators/` | Mission, adjudication, agent-feedback, and parallel-agent tests |
|
|
| Scope and authorization | `src/target/`, `src/opsec/`, `src/arsenal/approval.ts` | Scope-gate, approval-gate, validation, and target-header tests |
|
|
| Evidence and findings | `src/evidence/`, `src/analysis/`, verification scripts | Evidence-integrity, report-redaction, and finding-verifier tests |
|
|
|
|
## Open Issues
|
|
|
|
- Quantified workload and concurrent mission baselines remain a planned measurement item (NFR-11).
|
|
- Reliable swarm advantage over solo baselines is not an acceptance assumption for this use case.
|
|
|
|
## References
|
|
|
|
- @.aiwg/requirements/nfr-register.md — Safety, authorization, provenance, secret-isolation, and testability requirements.
|
|
- @.aiwg/architecture/software-architecture-doc.md — Components and trust boundaries satisfying this flow.
|
|
- @src/mission/index.ts — Mission state and lifecycle implementation.
|
|
- @src/target/index.ts — Authorized-target representation and validation boundary.
|
|
- @src/arsenal/approval.ts — Dangerous-tool approval policy.
|
|
- @src/__tests__/arsenal-scope-gate.test.ts — Negative scope-containment evidence.
|
|
- @src/__tests__/arsenal-approval-gate.test.ts — Approval enforcement evidence.
|
|
- @src/__tests__/target-headers-static.test.ts — Exact-origin credential-routing evidence.
|