feat(controls): B2 — grounded surface checks for absence-based CRA controls (#219)

compliance-agent/src/controls/surface.rs

@@ -0,0 +1,246 @@
+//! Surface retrieval for absence-based controls.
+//!
+//! Some CRA controls are violated by an *absence* — no rate limiting on login, no
+//! security logging, no signature check on an update — so there's no offending
+//! pattern for semgrep to match. Instead we deterministically locate the code
+//! *surface* the control governs (a login route, a logging setup, update/download
+//! code) by identifier/route terms, then hand each surface region to the grounded
+//! judge, which decides whether the control is satisfied there. The resulting
+//! finding grounds to the surface snippet, so nothing fabricated survives.
+//!
+//! Retrieval is intentionally cheap and bounded: keyword match + a fixed window,
+//! capped per control to keep the downstream LLM cost predictable.
+
+use std::path::Path;
+
+use compliance_core::control_check::CandidateRegion;
+
+/// An absence-based control and the case-insensitive terms that mark the code
+/// surface it governs.
+pub struct Surface {
+    pub control_id: &'static str,
+    pub terms: &'static [&'static str],
+}
+
+/// The absence-based CRA controls we retrieve surfaces for — the grounded half of
+/// the hybrid coverage (the pattern-expressible half is custom semgrep rules).
+pub const SURFACES: &[Surface] = &[
+    Surface {
+        control_id: "cra-ai-6", // Integritaetspruefung
+        terms: &[
+            "checksum",
+            "sha256",
+            "signature",
+            "hmac",
+            "integrity",
+            "verify",
+        ],
+    },
+    Surface {
+        control_id: "cra-ai-11", // Brute-Force-Schutz
+        terms: &[
+            "login",
+            "signin",
+            "authenticate",
+            "/auth",
+            "password",
+            "ratelimit",
+        ],
+    },
+    Surface {
+        control_id: "cra-ai-24", // Security-Logging
+        terms: &["login", "authorize", "permission", "role", "admin", "audit"],
+    },
+    Surface {
+        control_id: "cra-ai-27", // Log-Integritaet und -Aufbewahrung
+        terms: &["logging", "logger", "getlogger", "audit_log"],
+    },
+    Surface {
+        control_id: "cra-ai-28", // Sichere Update-Mechanismen
+        terms: &["update", "upgrade", "download", "firmware"],
+    },
+    Surface {
+        control_id: "cra-ai-29", // Update-Authentizitaet
+        terms: &["update", "signature", "verify", "pubkey", "certificate"],
+    },
+    Surface {
+        control_id: "cra-ai-30", // Update-Integritaet
+        terms: &["update", "checksum", "digest", "integrity", "verify"],
+    },
+];
+
+/// Source file extensions worth reading (skip binaries/assets/lockfiles).
+const CODE_EXTS: &[&str] = &[
+    "py", "js", "ts", "tsx", "jsx", "go", "java", "rb", "php", "rs", "cs", "kt",
+];
+/// Directories never worth walking.
+const SKIP_DIRS: &[&str] = &[
+    ".git",
+    "node_modules",
+    "target",
+    "vendor",
+    ".venv",
+    "__pycache__",
+    "dist",
+    "build",
+];
+/// Lines of context on each side of a hit.
+const WINDOW: usize = 6;
+/// Cap on regions per control, to bound downstream LLM calls.
+const MAX_REGIONS_PER_CONTROL: usize = 8;
+/// Skip files larger than this (generated/minified).
+const MAX_FILE_BYTES: u64 = 512 * 1024;
+
+/// Deterministically retrieve up to [`MAX_REGIONS_PER_CONTROL`] code regions in
+/// `repo_path` whose lines mention any of `terms`. Hits close together within a
+/// file are merged into one region; results are capped to bound LLM cost.
+pub fn retrieve(repo_path: &Path, terms: &[&str]) -> Vec<CandidateRegion> {
+    let lowered: Vec<String> = terms.iter().map(|t| t.to_lowercase()).collect();
+    let mut regions = Vec::new();
+    for entry in walk(repo_path) {
+        if regions.len() >= MAX_REGIONS_PER_CONTROL {
+            break;
+        }
+        let path = entry.path();
+        if !has_code_ext(path) {
+            continue;
+        }
+        let Ok(meta) = entry.metadata() else { continue };
+        if !meta.is_file() || meta.len() > MAX_FILE_BYTES {
+            continue;
+        }
+        let Ok(content) = std::fs::read_to_string(path) else {
+            continue;
+        };
+        let rel = path
+            .strip_prefix(repo_path)
+            .unwrap_or(path)
+            .to_string_lossy()
+            .to_string();
+        let lines: Vec<&str> = content.lines().collect();
+        let hits: Vec<usize> = lines
+            .iter()
+            .enumerate()
+            .filter(|(_, line)| {
+                let ll = line.to_lowercase();
+                lowered.iter().any(|t| ll.contains(t.as_str()))
+            })
+            .map(|(i, _)| i)
+            .collect();
+        for center in merge_centers(&hits) {
+            if regions.len() >= MAX_REGIONS_PER_CONTROL {
+                break;
+            }
+            let start = center.saturating_sub(WINDOW);
+            let end = (center + WINDOW + 1).min(lines.len());
+            regions.push(CandidateRegion {
+                file: rel.clone(),
+                start_line: (start as u32) + 1,
+                content: lines[start..end].join("\n"),
+            });
+        }
+    }
+    regions
+}
+
+/// Collapse ascending hit indices that fall within one window into a single
+/// representative center, so overlapping regions aren't judged repeatedly.
+fn merge_centers(hits: &[usize]) -> Vec<usize> {
+    let mut out: Vec<usize> = Vec::new();
+    for &h in hits {
+        match out.last() {
+            Some(&last) if h.saturating_sub(last) <= WINDOW => {}
+            _ => out.push(h),
+        }
+    }
+    out
+}
+
+fn has_code_ext(path: &Path) -> bool {
+    path.extension()
+        .and_then(|e| e.to_str())
+        .is_some_and(|e| CODE_EXTS.contains(&e))
+}
+
+fn walk(root: &Path) -> Vec<walkdir::DirEntry> {
+    walkdir::WalkDir::new(root)
+        .into_iter()
+        .filter_entry(|e| {
+            let name = e.file_name().to_string_lossy();
+            !SKIP_DIRS.contains(&name.as_ref())
+        })
+        .filter_map(|e| e.ok())
+        .collect()
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used)]
+mod tests {
+    use super::*;
+
+    fn write(dir: &Path, rel: &str, body: &str) {
+        let p = dir.join(rel);
+        if let Some(parent) = p.parent() {
+            std::fs::create_dir_all(parent).unwrap();
+        }
+        std::fs::write(p, body).unwrap();
+    }
+
+    fn terms_for(control_id: &str) -> &'static [&'static str] {
+        SURFACES
+            .iter()
+            .find(|s| s.control_id == control_id)
+            .unwrap()
+            .terms
+    }
+
+    #[test]
+    fn surfaces_cover_the_absence_based_controls() {
+        assert_eq!(SURFACES.len(), 7);
+        for id in [
+            "cra-ai-6",
+            "cra-ai-11",
+            "cra-ai-24",
+            "cra-ai-27",
+            "cra-ai-28",
+            "cra-ai-29",
+            "cra-ai-30",
+        ] {
+            assert!(SURFACES.iter().any(|s| s.control_id == id), "{id} missing");
+        }
+    }
+
+    #[test]
+    fn retrieves_matching_region_with_context() {
+        let dir = std::env::temp_dir().join(format!("surface-{}", uuid::Uuid::new_v4()));
+        std::fs::create_dir_all(&dir).unwrap();
+        write(
+            &dir,
+            "app/auth.py",
+            "import x\n\n\n\n\n\n\ndef login(u, p):\n    return check(u, p)\n",
+        );
+        let regions = retrieve(&dir, terms_for("cra-ai-11"));
+        assert_eq!(regions.len(), 1);
+        assert!(regions[0].content.contains("def login"));
+        assert_eq!(regions[0].file, "app/auth.py");
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn skips_non_code_and_vendored() {
+        let dir = std::env::temp_dir().join(format!("surface-{}", uuid::Uuid::new_v4()));
+        std::fs::create_dir_all(&dir).unwrap();
+        write(&dir, "README.md", "login and password and audit\n"); // not code ext
+        write(&dir, "node_modules/pkg/index.js", "function login() {}\n"); // vendored
+        assert!(retrieve(&dir, terms_for("cra-ai-11")).is_empty());
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn merges_adjacent_hits_into_one_region() {
+        // Two hits one line apart collapse to a single center/region.
+        assert_eq!(merge_centers(&[10, 11, 30]), vec![10, 30]);
+        assert_eq!(merge_centers(&[]), Vec::<usize>::new());
+        assert_eq!(merge_centers(&[5]), vec![5]);
+    }
+}