feat(update): working on next release

Author: Mte90

docs/ci-integration.md

@@ -64,6 +64,21 @@ After the workflow runs:
 - **Code Scanning alerts**: Navigate to **GitHub → Security → Code Scanning alerts**
 - **PR annotations**: Findings automatically appear as inline annotations on changed lines in pull requests
 
+## PR-Scoped Scans with `--diff`
+
+For pull request reviews, limit the scan to only files changed in the PR using `--diff`:
+
+```bash
+baco scan --config baco.toml --diff origin/main...HEAD
+```
+
+The `--diff <revspec>` flag filters findings to include only those in files modified in the specified git revision range. Use this for:
+- PR reviews: scan only changed files (`origin/main...HEAD`)
+- Incremental checks: compare against a specific commit (`main..feature-branch`)
+- Reducing noise: focus on recent changes rather than the entire codebase
+
+The revspec follows standard git syntax (e.g., `A...B` for changes in B not in A, `A..B` for changes reachable from B but not A).
+
 ## Other CI Systems
 
 ### Azure DevOps

docs/configuration.md

@@ -182,6 +182,30 @@ timeout_secs = 120      # Per-phase timeout override
 temperature = 0.3       # Per-phase temperature override
 ```
 
+### LLM Timeout Semantics
+
+Timeout configuration operates at two levels:
+
+| Level | Config Path | Type | Default | Behavior |
+|-------|-------------|------|---------|----------|
+| Global | `[llm] timeout_secs` | `u64` | `60` (in `config.example.toml`) | Applied to all phases without a per-phase override |
+| Per-phase | `[llm.phases.<phase>] timeout_secs` | `Option<u64>` | `None` | When set, overrides the global timeout for that phase |
+
+**Runtime behavior:**
+- HTTP request timeout: `Duration::from_secs(timeout_secs)` (source: `src/llm/mod.rs:236`)
+- Connection timeout: Fixed at 10 seconds (source: `src/llm/mod.rs:192`)
+- Default runtime timeout (if no config provided): 30 seconds (source: `src/llm/mod.rs:170`)
+
+**What value `0` means:** Setting `timeout_secs = 0` results in `Duration::from_secs(0)`, which causes an immediate timeout on every request. Use only for testing.
+
+**Retry behavior:** Failed requests (429, 5xx, network errors) are retried with exponential backoff:
+- Base delay: Configured via `[llm] retry_backoff_ms` (default: 2000ms)
+- Formula: `base_ms * 2^attempt`, capped at 30 seconds
+- Max retries: Configured via `[llm] max_retries` (default: 3)
+- Source: `src/llm/mod.rs:254-269`
+
+Retries are bounded; after exhausting retries on one model, the client fails over to the next configured model (if multiple models are specified).
+
 **Single model:**
 ```toml
 [llm.phases.discovery]
@@ -353,6 +377,8 @@ include_rejected = false
 | `LLM_STATIC_ANALYSIS_KEY` | Overrides `llm.phases.static_analysis.api_key` |
 | `LLM_SECURITY_AGENT_VERIFICATION_KEY` | Overrides `llm.phases.security_agent_verification.api_key` |
 | `LLM_THREAT_MODELING_KEY` | Overrides `llm.phases.threat_modeling.api_key` |
+| `LLM_CONFIG_PATH` | Overrides config path for `baco verify` (source: `src/cli/verify.rs:24`) |
+| `NO_COLOR` | Disables colored output (source: `src/ui.rs:46`) |
 | `TICKET_GITHUB_KEY` | Overrides `[[tickets.systems]]` api_key for GitHub |
 | `TICKET_GITLAB_KEY` | Overrides `[[tickets.systems]]` api_key for GitLab |
 
@@ -362,6 +388,57 @@ include_rejected = false
 - **report.html**: Visual report with severity colors, code snippets, AI summary
 - **report.sarif**: SARIF format for CI/CD integration
 
+## Scan Options
+
+### `--dry-run`
+
+The `--dry-run` flag performs indexing and prioritization without executing any LLM or semgrep phases. It prints an estimate of the resources a full scan would consume, then exits.
+
+**What it does:**
+1. Indexes the project (counts files, calculates total size, estimates tokens)
+2. Computes priority scores for each file
+3. Estimates LLM calls based on budget and triage configuration
+4. Prints the summary and exits
+
+**What it does NOT do:**
+- No LLM API calls
+- No semgrep scanning
+- No findings produced
+- No report generation
+
+**Example usage:**
+```bash
+baco scan --config baco.toml --dry-run
+```
+
+**Output example:**
+```
+[Dry Run] Project Estimate
+═══════════════════════════════════════
+Target: ./my-project
+
+Files by language:
+  python: 42 files
+  javascript: 18 files
+
+Total files: 60
+Total size: 1234567 bytes
+Estimated tokens (~4 chars/token): 308641
+
+Planned LLM calls: 45
+  (budget max: 100, normal cap: 75, high-risk: 25)
+
+Average priority score: 0.67
+```
+
+Use `--dry-run` before a full scan to:
+- Estimate costs (LLM call count, token usage)
+- Verify your configuration is correct
+- Check which files will be analyzed
+- Decide if you need to adjust budget/triage settings
+
+Source: `src/cli/scan.rs:346-478` (`run_dry_run` function).
+
 ## Aggregation Configuration
 
 The `[aggregation]` section configures the AI Aggregation phase settings.

presets/cpp.toml

@@ -71,12 +71,6 @@ rules:
       - pattern-not: printf('...')
 ''']
 
-[scanner.performance]
-enable_caching = true
-max_workers = 4
-parallel_threshold_kb = 100
-skip_large_files_mb = 5
-
 [llm]
 temperature = 0.2
 max_concurrent = 4

src/agent/sandbox.rs

@@ -16,6 +16,72 @@ pub enum SandboxError {
     Timeout(u64),
 }
 
+/// Validate that a resolved path is contained within the sandbox root.
+///
+/// Checks:
+/// - Path is not absolute
+/// - No `..` components in the path
+/// - Final resolved path starts with canonicalized sandbox root
+/// - Parent directory exists (does not create directories)
+fn validate_path_containment(sandbox_root: &Path, user_path: &str) -> Result<PathBuf, String> {
+    let path = Path::new(user_path);
+
+    // Reject absolute paths
+    if path.is_absolute() {
+        return Err(format!("Absolute path not allowed: {}", user_path));
+    }
+
+    // Reject dot sequences before component analysis: encoded, spaced, and
+    // separator-mixed variants are never legitimate sandbox paths.
+    if user_path.contains("..") {
+        return Err(format!("Path traversal: {}", user_path));
+    }
+
+    // Reject any path with `..` components
+    if path
+        .components()
+        .any(|c| c == std::path::Component::ParentDir)
+    {
+        return Err(format!("Path traversal not allowed: {}", user_path));
+    }
+
+    // Join with sandbox root
+    let full = sandbox_root.join(path);
+
+    // Canonicalize the sandbox root for comparison
+    let canonical_root = sandbox_root
+        .canonicalize()
+        .map_err(|e| format!("Cannot canonicalize sandbox root {:?}: {}", sandbox_root, e))?;
+
+    // Check containment by canonicalizing the target if it exists,
+    // or verifying the parent path structure is within bounds
+    let final_check = if full.exists() {
+        full.canonicalize()
+            .map_err(|e| format!("Cannot canonicalize target {:?}: {}", full, e))?
+    } else {
+        // If the file doesn't exist, verify parent is within bounds
+        if let Some(parent) = full.parent() {
+            if parent.exists() {
+                parent
+                    .canonicalize()
+                    .map_err(|e| format!("Cannot canonicalize parent {:?}: {}", parent, e))?
+            } else {
+                // Parent doesn't exist - check path components are safe
+                // We already rejected .. and absolute, so join is safe
+                canonical_root.join(parent.strip_prefix(&canonical_root).unwrap_or(parent))
+            }
+        } else {
+            canonical_root.clone()
+        }
+    };
+
+    if !final_check.starts_with(&canonical_root) {
+        return Err(format!("Path escapes sandbox: {}", user_path));
+    }
+
+    Ok(full)
+}
+
 pub struct ToolSandbox {
     pub(super) temp_dir: PathBuf,
     pub(super) timeout_secs: u64,
@@ -26,11 +92,7 @@ impl SandboxLike for ToolSandbox {
         &self.temp_dir
     }
     fn resolve_safe_path(&self, path: &str) -> Result<PathBuf, String> {
-        // Check for path traversal before joining
-        if path.contains("..") {
-            return Err(format!("Path traversal: {}", path));
-        }
-        let full = self.temp_dir.join(path);
+        let full = validate_path_containment(&self.temp_dir, path)?;
         if !full.exists() {
             return Err(format!("Path does not exist: {}", path));
         }
@@ -87,14 +149,29 @@ impl SandboxLike for ToolSandbox {
     fn create_temp_file(&self, path: &str, content: &str) -> Result<PathBuf, String> {
         self.validate_test_source(content)
             .map_err(|e| format!("Validation failed: {}", e))?;
-        // Check path traversal by looking for ".." in the input path
-        if path.contains("..") {
-            return Err(format!("Path traversal: {}", path));
-        }
-        let full = self.temp_dir.join(path);
+
+        // Pre-condition: validate path containment before write
+        let full = validate_path_containment(&self.temp_dir, path)?;
+
+        // Write the file
         std::fs::File::create(&full)
             .and_then(|mut f| f.write_all(content.as_bytes()))
             .map_err(|e| format!("Write failed: {}", e))?;
+
+        // Post-condition: verify containment after write (catches symlink swaps)
+        let canonical_after = full
+            .canonicalize()
+            .map_err(|e| format!("Cannot canonicalize after write {:?}: {}", full, e))?;
+        let canonical_root = self
+            .temp_dir
+            .canonicalize()
+            .map_err(|e| format!("Cannot canonicalize sandbox root: {}", e))?;
+        if !canonical_after.starts_with(&canonical_root) {
+            // File was created via symlink outside sandbox - delete and error
+            let _ = std::fs::remove_file(&full);
+            return Err(format!("Path escapes sandbox after write: {}", path));
+        }
+
         Ok(full)
     }
     fn is_path_allowed(&self, path: &Path) -> bool {
@@ -151,11 +228,7 @@ impl ToolSandbox {
     }
 
     pub fn resolve_safe_path(&self, path: &str) -> Result<PathBuf, String> {
-        // Check for path traversal before joining
-        if path.contains("..") {
-            return Err(format!("Path traversal: {}", path));
-        }
-        let full = self.temp_dir.join(path);
+        let full = validate_path_containment(&self.temp_dir, path)?;
         if !full.exists() {
             return Err(format!("Path does not exist: {}", path));
         }
@@ -215,14 +288,29 @@ impl ToolSandbox {
     pub fn create_temp_file(&self, path: &str, content: &str) -> Result<PathBuf, String> {
         self.validate_test_source(content)
             .map_err(|e| format!("Validation failed: {}", e))?;
-        // Check path traversal by looking for ".." in the input path
-        if path.contains("..") {
-            return Err(format!("Path traversal: {}", path));
-        }
-        let full = self.temp_dir.join(path);
+
+        // Pre-condition: validate path containment before write
+        let full = validate_path_containment(&self.temp_dir, path)?;
+
+        // Write the file
         std::fs::File::create(&full)
             .and_then(|mut f| f.write_all(content.as_bytes()))
             .map_err(|e| format!("Write failed: {}", e))?;
+
+        // Post-condition: verify containment after write (catches symlink swaps)
+        let canonical_after = full
+            .canonicalize()
+            .map_err(|e| format!("Cannot canonicalize after write {:?}: {}", full, e))?;
+        let canonical_root = self
+            .temp_dir
+            .canonicalize()
+            .map_err(|e| format!("Cannot canonicalize sandbox root: {}", e))?;
+        if !canonical_after.starts_with(&canonical_root) {
+            // File was created via symlink outside sandbox - delete and error
+            let _ = std::fs::remove_file(&full);
+            return Err(format!("Path escapes sandbox after write: {}", path));
+        }
+
         Ok(full)
     }
 

src/citation_verification.rs

@@ -27,7 +27,7 @@ pub struct CitationReport {
 ///
 /// On failure:
 /// - `confidence_score *= 0.5`
-/// - Appends to `verification_notes`: "citation verification failed: <reason>"
+/// - Appends to `verification_notes`: "citation verification failed: reason" (where reason is the failure cause)
 ///
 /// Returns a summary report with counts.
 pub fn verify_citations(

src/cli/report.rs

@@ -26,6 +26,7 @@ impl std::fmt::Display for ReportFormat {
 pub fn run_report(
     input: &Path,
     format: ReportFormat,
+    config_path: Option<&Path>,
     quiet: bool,
 ) -> Result<(), Box<dyn std::error::Error>> {
     let findings = validation::validate_findings(input)?;
@@ -42,15 +43,29 @@ pub fn run_report(
         ReportFormat::Markdown => output_dir.join("report.md"),
     };
 
+    // Load config if provided
+    let config = if let Some(cfg_path) = config_path {
+        Some(crate::config::ScannerConfig::from_file(
+            cfg_path.to_string_lossy().as_ref(),
+        )?)
+    } else {
+        None
+    };
+
     if !quiet {
         info!("Generating {} report to {:?}", format, output_path);
     }
 
     match format {
         ReportFormat::Html => {
             use crate::report::html::generate_html_report;
-            generate_html_report(&findings, &output_path.to_string_lossy(), None, None)
-                .map_err(|e| format!("Failed to generate HTML report: {}", e))?;
+            generate_html_report(
+                &findings,
+                &output_path.to_string_lossy(),
+                config.as_ref(),
+                None,
+            )
+            .map_err(|e| format!("Failed to generate HTML report: {}", e))?;
         }
         ReportFormat::Json => {
             use crate::report::json::write_findings_json;
@@ -59,7 +74,7 @@ pub fn run_report(
                 &[],
                 &output_path.to_string_lossy(),
                 None,
-                None,
+                config.as_ref(),
                 None,
                 None, // scan_health
             )
@@ -68,7 +83,7 @@ pub fn run_report(
         ReportFormat::Sarif => {
             use crate::report::sarif::generate_sarif_report;
             let sarif_path = output_path.clone();
-            let sarif_json = generate_sarif_report(&findings, None)?;
+            let sarif_json = generate_sarif_report(&findings, config.as_ref())?;
             std::fs::write(&sarif_path, sarif_json)
                 .map_err(|e| format!("Failed to write SARIF report: {}", e))?;
             if !quiet {
@@ -84,7 +99,13 @@ pub fn run_report(
                 .and_then(|p| p.file_name())
                 .map(|n| n.to_string_lossy().to_string())
                 .unwrap_or_else(|| "unknown".to_string());
-            let md_content = generate_markdown_report(&findings, &project_name);
+            // Markdown does not take config, so use pre-filtered slice
+            let gated_findings = if config.as_ref().is_some_and(|c| c.output.evidence_gate) {
+                crate::report::apply_evidence_gate(&findings, config.as_ref())
+            } else {
+                findings.clone()
+            };
+            let md_content = generate_markdown_report(&gated_findings, &project_name);
             std::fs::write(&md_path, md_content)
                 .map_err(|e| format!("Failed to write markdown report: {}", e))?;
             if !quiet {