[Phase 1] Stage 3: Reachability analysis (OpenGrep/CodeQL + ReachabilityAgent)

[varun-polpakkara]

Summary

Determines whether each finding's vulnerable code path is actually invoked in the project's source, using static analysis (OpenGrep by default, CodeQL optionally), and escalates ambiguous cases to an LLM agent.

Why this matters

A dependency may appear in the SBOM but never be imported, let alone have its vulnerable function called. REACHABLE vs NOT_REACHABLE vs UNCERTAIN dramatically changes risk priority.

How it works

1. Loads all Finding rows with reachability_status == NOT_ANALYZED.
2. Runs the static analysis tool once against the entire source tree.
3. Parses output into _ScanMatch records: purl, kind ("import" or "usage"), file path, line number.
4. Classifies each finding:
   • No import match -> NOT_REACHABLE
   • Import + usage match -> REACHABLE
   • Import but no usage -> UNCERTAIN -> escalated to ReachabilityAgent
5. Commits after every finding (not once at the end) — agent calls can take seconds; a timeout on finding [Phase 1] Stage 4: Exploit enrichment (KEV, Exploit-DB, GitHub, ExploitResearchAgent) #7 must not roll back findings Scaffold CyberGuard baseline with domain standards mapping and contextual risk scoring #1-6.
6. Sets SBOMSnapshot.status = "REACH_DONE".

ReachabilityAgent

• LangGraph ReAct agent with a single read_file tool (sandboxed to project dir, refuses path traversal).
• Receives CVE ID, description, CVSS details, and exact source file paths/line numbers of the import.
• Returns VERDICT: REACHABLE/NOT_REACHABLE + RATIONALE:. Falls back to UNCERTAIN on parse failure.
• Single agent failure is non-fatal — finding stays UNCERTAIN.

Tests (27 passing)

Reachable/not-reachable/uncertain classification, agent invocation, snapshot checkpoint, skipping already-classified findings, CodeQL language detection, agent failure graceful degradation, OpenGrep JSON and CodeQL SARIF parsers.