Skip to content

architecture.md

Latest commit

 

History

History
142 lines (106 loc) · 7.14 KB

architecture.md

File metadata and controls

142 lines (106 loc) · 7.14 KB
Raw

Architecture

PhaseGraph (Data-Driven Pipeline Orchestration)

BACO uses a data-driven PhaseGraph (src/scanner/pipeline/orchestrator.rs) that defines phase execution order, dependencies, and metadata in a single source of truth. This eliminates duplication across the codebase and enables:

  • Centralized phase ordering - All phases defined in one place with execution metadata
  • Checkpoint/resume support - Stable phase indices for reliable restart
  • Extensibility - New phases can be added without modifying multiple files
  • Runtime validation - Phase consistency checked on startup

Pipeline Phases

Core Pipeline (23 phases total: 4 parallel + 19 sequential):

Note: Phase order is defined in PhaseGraph::new() (src/scanner/pipeline/orchestrator.rs:28-53). This table is manually maintained and should be updated when that code changes.

Phase # Name Config gate (default) Description
1 Indexing Always-on Index project files
2 Semgrep Always-on Run Semgrep static analysis
3 CPG Slice cpg.enabled=false Code Property Graph slicing (Joern)
4 LLM Static Analysis llm.phases.static_analysis (API key present) Analyze files with LLM
5 CWE Routing router.enabled=true Route findings to specialized models (opt-in)
6 Rule Synthesis rulesynth.enabled=false LLM-generated Semgrep rules (MoCQ)
7 LLM Discovery llm.phases.discovery (API key present) Enrich findings with AI context
8 LLM Verification llm.phases.verification (API key present) Verify findings with AI
9 Validate validate.enabled=false LLM-as-judge rationale check (CORRECT paper)
10 SecurityAgent Verification agent.enabled=false Tool-based verification
11 Ticket Cross-Reference tickets.systems non-empty Cross-reference with ticket systems
12 Git Analysis Target is a git repository Analyze Git history
13 Cross-File Analysis Always-on Analyze cross-file dependencies
14 Confidence Scoring scanner.performance.enable_confidence_refinement=false Refine confidence scores
15 AI Aggregation llm.phases.aggregation (API key present) Aggregate findings with AI
16 Threat Modeling scanner.performance.enable_threat_modeling=false Generate threat model (STRIDE)
17 Root Cause Deduplication scanner.performance.enable_root_cause_dedup=true Deduplicate by root cause
18 Auto-Patching scanner.performance.enable_auto_patching=false Generate patches automatically
19 CVE Bootstrap scanner.performance.enable_cve_bootstrap=true Enrich with CVE data
20 PoC Compilation scanner.performance.enable_poc_compilation=false Compile and validate PoCs
21 Exploit Synthesis exploit.enabled=false Sandbox-verified exploit generation
22 Variant Search scanner.performance.enable_variant_search=true Search for code variants
23 Reporting Always-on Generate reports (JSON/HTML/SARIF)

Data Flow

flowchart LR
    subgraph Parallel["Parallel Detection (1-4)"]
        direction TB
        A1[Indexing] --> A2[Semgrep] --> A3[CPG Slice] --> A4[LLM Static]
    end

    subgraph Discovery["Sequential Discovery (5-8)"]
        direction TB
        B1[CWE Routing] --> B2[Rule Synthesis] --> B3[LLM Discovery] --> B4[LLM Verification]
    end

    subgraph Triage["Triage (9-13)"]
        direction TB
        C1[Validate] --> C2[SecurityAgent Verify] --> C3[Ticket Cross-Ref] --> C4[Git Analysis] --> C5[Cross-File]
    end

    subgraph Aggregation["Aggregation (14-16)"]
        direction TB
        D1[Confidence] --> D2[AI Aggregation] --> D3[Threat Modeling]
    end

    subgraph PostProcessing["Post-Processing (17-22)"]
        direction TB
        E1[Root Cause Dedup] --> E2[Auto-Patch] --> E3[CVE Bootstrap] --> E4[PoC Compiler] --> E5[Exploit Synth] --> E6[Variant Search]
    end

    subgraph Output["Output (23)"]
        direction TB
        F1[Reporting]
    end

    A4 --> B1
    B4 --> C1
    C5 --> D1
    D3 --> E1
    E6 --> F1

    classDef parallel fill:#e1f5fe
    classDef discovery fill:#fff3e0
    classDef triage fill:#f3e5f5
    classDef aggregation fill:#e8f5e9
    classDef postproc fill:#fce4ec
    classDef output fill:#eceff1
    class Parallel parallel
    class Discovery discovery
    class Triage triage
    class Aggregation aggregation
    class PostProcessing postproc
    class Output output
Loading

Checkpoint markers: Checkpoints are saved after each major phase, enabling resume from any point in the pipeline.

Verification & Calibration Layer

The pipeline includes several verification gates and calibration layers that augment the core phases:

Citation Verification Gate (Reporting Phase)

Before rendering the final report, deterministic checks verify that all citations (file paths + line ranges) match the scanned source tree. Findings failing this check have their confidence score halved and a note added explaining the discrepancy.

Configured via [citation_verification] enabled = true (enabled by default).

Prior-Runs Store (Discovery Phase)

Cross-run findings history: Confirmed and FalsePositive findings from prior scans (saved under {output_dir}/runs/) are injected as skip-lists into discovery prompts. This reduces redundant analysis on subsequent scans of the same codebase.

Configured via [prior_runs] enabled = true with max_runs controlling how many recent runs to load.

Org-Context Profile (Discovery + Verification Phases)

Organizational policy profile injected into prompts for calibration. Fields include:

  • stack: Technology stack (e.g., ["php", "javascript"])
  • infra: Infrastructure (e.g., ["aws", "docker"])
  • data_sensitivity: Data classification (e.g., "pii")
  • secret_storage: Secret management location (e.g., "vault" prevents ${VAULT_TOKEN} false positives)
  • risk_tolerance: Risk posture
  • severity_rules: Per-rule severity overrides

The org-context profile is injected into discovery and verification prompts to reduce false positives tied to the organization's stack, infrastructure, and secret management.

Domain-Routed Hunt Prompts (Discovery Phase)

Per-attack-class prompt modules from prompts/hunt/ (injection, auth, authz_absence, xss, path_traversal, crypto, resource, deserialization, memory_safety) selected by target languages and appended to discovery prompts. Each module includes scope/lane discipline sections; the verification prompt has a skeptical self-refutation gate + untrusted-content framing. Hunt prompts are enabled by default (enable_hunt_prompts = true).

Configured via [scanner.performance] enable_hunt_prompts = true.

Exploit Synthesis Marker (Exploit Synthesis Phase)

When the Docker sandbox is unavailable, unverifiable findings are marked with requires_deployment_testing to indicate they need deployment-level verification.

Eval Harness (External)

Known-answer oracle scoring under eval/ with labeled vulnerable/secure fixture pairs and oracle files. Recall/precision scoring via src/eval.rs; end-to-end runs use BACO_EVAL_FLOOR env var. See eval/README.md.