Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
3.7 KiB
3.7 KiB
UC-004 — Analyze a Source Code Repository
Metadata
- ID: UC-004
- Status: Baselined; multi-language coverage remains experimental
- Level: User goal
- Scope: Repository ingest, structural extraction, white-box analysis, evidence, and finding verification
- Primary actor: Security researcher
- Goal: Ingest an authorized repository and identify evidence-backed vulnerability candidates without overstating language or analysis maturity.
- Related story: US-07
- Quality drivers: NFR-03, NFR-08, NFR-09, NFR-11
Preconditions
- The researcher is authorized to analyze the repository.
- Input size and file types satisfy configured containment limits.
- Required parser grammars or safe fallback behavior are available.
Trigger
The researcher selects a repository or supported source input for white-box analysis.
Main Success Scenario
- The system enumerates eligible files under configured containment and size limits.
- Ingest identifies the language and selects the corresponding structural parser.
- The parser extracts bounded code blocks with source locations.
- Analysis processes the blocks and emits candidate observations with source evidence.
- Candidate findings are graded, refuted, or verified against the cited code.
- Results report language/parser maturity and verification status.
Alternate Flows
- A supported Tree-sitter grammar extracts structural blocks for the detected language.
- The Python-specific path uses its specialized parser where configured.
- A safe documented fallback may produce reduced-fidelity blocks while marking the limitation.
Exception Flows
- Unsupported input: fail safely with an explicit unsupported-language result.
- Oversized, recursive, binary, or escaping input: containment limits reject or bound processing.
- Parser failure: record the error and do not fabricate structural evidence.
- Unverified candidate: retain as a candidate or refuted result, never silently promote to verified.
Postconditions
- Each reported code observation can identify its source file and region.
- Parser limitations and experimental maturity remain visible.
- Repository content never grants authority to override analysis or safety instructions.
Acceptance Criteria
- Supported grammars extract source blocks with stable file and line context.
- Unsupported or malformed input fails explicitly and safely.
- Ingest limits prevent unbounded traversal or oversized processing.
- Findings preserve source evidence and verification state.
- Documentation does not generalize benchmark success beyond the evaluated corpus/language path.
Design and Test Traceability
| Concern | Implementation | Verification |
|---|---|---|
| Input containment | src/recon/code-ingest.ts, src/recon/whitebox.ts |
Ingest-limit and white-box-containment tests |
| Structural parsing | src/recon/ts-parse.ts, grammar registry |
Parser, grammar, fallback, and adversarial tests |
| Evidence-backed output | src/analysis/, finding verification scripts |
Verification and report-redaction tests |
References
- @.aiwg/architecture/software-architecture-doc.md — Reconnaissance and source-ingest component design.
- @.aiwg/architecture/vision-alignment.md — Maturity boundary for source analysis claims.
- @src/recon/code-ingest.ts — Repository ingest and limits.
- @src/recon/ts-parse.ts — Structural parser implementation.
- @src/recon/whitebox.ts — White-box analysis composition.
- @src/tests/ingest-limits.test.ts — Resource-containment evidence.
- @src/tests/ts-parse-adversarial.test.ts — Adversarial parser evidence.
- @src/tests/whitebox-containment.test.ts — Path and analysis containment evidence.
- @scripts/verify-finding.mjs — Finding-verification path.