BACO — Bug Analysis & Cross-reference Orchestrator

A research-backed SAST scanner that augments static analysis with LLM-powered discovery across a 23-phase pipeline: semgrep → CWE-aware MoE routing (opt-in) → LLM verification → exploit synthesis (experimental) → ticket cross-referencing → auto-patching (opt-in). Grounded in 36 surveyed papers (16 integrated) from Awesome-LLMs-for-Vulnerability-Detection.

---

Prerequisites

• Rust 1.85+ (rustup)
• An LLM API key (Mistral, OpenAI, or any OpenAI-compatible endpoint)
• Semgrep installed on PATH (pip install semgrep or see install options)

Quick Start

Five steps from clone to first scan:

# 1. Install baco (build from source)
git clone https://github.com/CodeAtCode/baco-scanner.git
cd baco-scanner
cargo build --release

# 2. Install semgrep (required for static analysis)
pip install semgrep

# 3. Set your LLM API key (per-phase or generic fallback)
export LLM_DISCOVERY_KEY="your-key-here"  # or LLM_API_KEY for generic fallback

# 4. Initialize config and run pre-flight checks
./target/release/baco init /path/to/project
./target/release/baco doctor

# 5. Scan
./target/release/baco scan --config /path/to/project/baco.toml

Additional subcommands

# Pre-flight checks (config parse, preset resolve, LLM phases, semgrep, python3, Joern-if-CPG, output dir, disk space)
./target/release/baco doctor --json

# Evaluate precision/recall/F1 vs ground truth
./target/release/baco eval --target /path/to/fixtures --ground-truth eval/oracles/target.json

# Generate report
# Use --config only when the evidence gate must apply to a standalone report
./target/release/baco report --input findings.json --format html --config config.toml

# Verify findings
./target/release/baco verify --input findings.json

# Scaffold a starter config (detects languages, suggests a preset)
./target/release/baco init /path/to/project

# List built-in presets
./target/release/baco preset list

# Resume an interrupted scan from its checkpoint
./target/release/baco resume --checkpoint baco-output/checkpoint.json

# Scan options
./target/release/baco scan --config my.toml --dry-run   # Print estimate and exit
./target/release/baco scan --config my.toml --target /path  # Override target path
./target/release/baco scan --config my.toml --force     # Force full rescan
./target/release/baco scan --config my.toml --diff main...HEAD  # Limit report to files changed in git revspec
./target/release/baco scan --config my.toml -q          # Suppress non-essential output (global flag)

• Phases: 4 parallel (Indexing, Semgrep, CpgSlice, LlmStaticAnalysis) + 19 sequential phases — some disabled by default (see Configuration)

Features

• Pipeline profiles: core (default) runs essential phases; all enables experimental phases (still individually flag-gated) — set with scanner.profile = "core" | "all"
• Pipeline phases: Indexing → Semgrep → CpgSlice ([cpg] section, requires Joern) → LlmStaticAnalysis → CweRouting (router.enabled) → RuleSynthesis (experimental) → LlmDiscovery → LlmVerification → Validate (opt-in) → SecurityAgentVerification (opt-in) → TicketCrossRef → GitAnalysis → CrossFileAnalysis → ConfidenceScoring → AiAggregation → ThreatModeling (enable_threat_modeling) → RootCauseDedup → AutoPatching (enable_auto_patching, opt-in) → CveBootstrap → PocCompiler (enable_poc_compilation, opt-in) → ExploitSynth ([exploit] section, experimental) → VariantSearch → Reporting
• Parallel execution: Indexing, Semgrep, CpgSlice, and LlmStaticAnalysis run concurrently; 19 sequential phases follow
• CWE-aware MoE (opt-in): BM25 RAG retrieval from CWE knowledge base, routes to specialized analysis paths — enable with router.enabled = true
• Research-backed: 16 academic papers integrated (VulTriage, VulIn, MoCQ, MoEVD, AgentFlow) — see Research Integration
• Checkpoint/resume: Crash recovery after each phase
• Pre-flight checks: baco doctor validates config, presets, LLM phases, semgrep, python3, Joern (if CPG enabled), output dir, and disk space
• Multiple outputs: JSON, HTML, SARIF, Markdown
• Config-driven: TOML config with env var overrides
• Ticket systems: Configurable via [[tickets.systems]] TOML blocks (supports any system type via system_type field) — see Configuration for setup

Phase reference table

Phase	Profile	Enabling flag / condition
Indexing	Core	Always runs
Semgrep	Core	Always runs
CpgSlice	Experimental	scanner.profile = "all" + [cpg] section
LlmStaticAnalysis	Core	Always runs
CweRouting	Core	router.enabled = true
RuleSynthesis	Experimental	scanner.profile = "all"
LlmDiscovery	Core	Always runs
LlmVerification	Core	Always runs
Validate	Experimental	scanner.profile = "all" + [validate] section
SecurityAgentVerification	Experimental	scanner.profile = "all" + [agent] section
TicketCrossRef	Core	Always runs
GitAnalysis	Core	Always runs
CrossFileAnalysis	Core	Always runs
ConfidenceScoring	Core	Always runs
AiAggregation	Core	Always runs
ThreatModeling	Experimental	scanner.profile = "all" + enable_threat_modeling = true
RootCauseDedup	Core	Always runs
AutoPatching	Experimental	scanner.profile = "all" + enable_auto_patching = true
CveBootstrap	Core	Always runs
PocCompiler	Experimental	scanner.profile = "all" + enable_poc_compilation = true
ExploitSynth	Experimental	scanner.profile = "all" + [exploit] section
VariantSearch	Experimental	scanner.profile = "all" + enable_variant_search = true
Reporting	Core	Always runs

Evidence & Verification Techniques

• Citation verification: Deterministic file existence + line range checks in Reporting phase; failures halve confidence + add note — see docs/argus-analysis.md
• Cross-run prior-findings skip lists (opt-in): Confirmed/FalsePositive findings from prior scans injected into discovery prompts to reduce redundancy — enable with [prior runs] section
• Domain-routed hunt prompts: Per-attack-class modules (prompts/hunt/) selected by target languages; verification prompt includes skeptical self-refutation gate + untrusted-content framing
• Rejected-findings persistence: include_rejected = true persists "rejected" array in JSON + "Investigated & Dismissed" appendix in HTML
• Requires-deployment-testing marker (experimental): Exploit synthesis marks unverifiable findings when Docker sandbox unavailable — enable with [exploit] section
• Org-context calibration (opt-in): Organizational policy profile (stack, infra, secret_storage, data_sensitivity, severity_rules) injected into prompts to reduce false positives — enable with [org_context] section
• Eval oracles: Known-answer harness under eval/ with labeled vulnerable/secure fixtures; precision/recall/F1 scoring via baco eval --target <path> --ground-truth <oracle.json> — see eval/README.md

Supported Languages

Language	Static analysis	LLM analysis
C / C++	tree-sitter + semgrep	✅
Rust	tree-sitter + semgrep	✅
Python	tree-sitter + semgrep	✅
JavaScript	tree-sitter + semgrep	✅
TypeScript	tree-sitter + semgrep	✅
PHP	tree-sitter + semgrep	✅
Go	tree-sitter + semgrep	✅
Java	tree-sitter + semgrep	✅
C#	tree-sitter + semgrep	✅
Ruby	tree-sitter + semgrep	✅

Outputs

• findings.json — complete vulnerability data (all fields, machine-readable)
• report.html — interactive report with severity filtering, code highlighting, confidence/CWE badges
• report.sarif — SARIF 2.1 for CI/CD integration (GitHub Code Scanning, Azure DevOps)
• findings.md — Markdown summary of findings (written alongside JSON)

Architecture

See Architecture for the PhaseGraph pipeline diagram, full phase list, and data flow.

Research Foundation

BACO integrates 16 academic papers from the Awesome-LLMs-for-Vulnerability-Detection survey. Integrations span agentic workflows, context enhancement, rule synthesis, MoE routing, and confidence calibration.

See Research Integration for per-paper details (techniques, results, config flags) and Paper Survey for the full 36-paper survey.

Documentation

• Architecture — PhaseGraph pipeline, all 23 phases, data flow
• Configuration — Config options, LLM setup, phase flags, prompt overrides
• Research Integration — 16 integrated papers with techniques and results
• Paper Survey — Full 36-paper survey
• Operator Tuning — Performance flags and scenario-based tuning
• Output Interpretation — Reading findings, confidence, triage verdicts
• Troubleshooting — Common errors and fixes
• Argus Analysis — Evidence verification techniques
• CI Integration — Continuous integration setup

Reading Order

Recommended for new users:

1. README.md (this page) — overview, quick start
2. docs/architecture.md — pipeline architecture
3. docs/configuration.md — configuration reference
4. docs/research-integration.md — research integrations
5. docs/llm-vuln-detection-papers-survey.md — paper survey
6. docs/operator-tuning.md — performance tuning
7. docs/output-interpretation.md — reading results
8. docs/troubleshooting.md — error fixes

Acknowledgements

Sponsored and tested with Regolo.AI — LLM API services.