feat(controls): B3 — categorize the rest of needs_tooling (architectural + RBAC)

Closes out B's coverage of the 16 needs_tooling CRA controls:

- cra-ai-2,3,4,5 (minimal attack surface, secure architecture, least-privilege,
  tamper protection) are design properties, not local code patterns -> marked
  not_code_checkable (out of static-scan scope) with reviewer notes.
- cra-ai-12 (RBAC) is surface-checkable (authorization points) -> added to the
  grounded surface pass; note points to the gated grounded mechanism.

Final CRA coverage: covered 13 | needs_tooling 8 (all grounded-covered, gated) |
not_code_checkable 19. The 16 needs_tooling now fully categorized:
4 custom-semgrep (B1) + 8 grounded surface (B2/B3, gated) + 4 architectural (B3).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.gitea/workflows/ci.yml

@@ -206,11 +206,13 @@ jobs:
           apk add --no-cache git curl openssl
           git init && git remote add origin "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
           git fetch --depth=1 origin "${GITHUB_SHA}" && git checkout FETCH_HEAD
-          IMAGE=registry.meghsakha.com/compliance-agent
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login registry.meghsakha.com -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+          IMAGE=repo.meghsakha.com/certifai/compliance-agent
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login repo.meghsakha.com -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
           DOCKER_BUILDKIT=1 docker build --secret id=tramiton_token,env=TRAMITON_FETCH_TOKEN \
             -f Dockerfile.agent -t "$IMAGE:latest" -t "$IMAGE:${GITHUB_SHA}" .
           docker push "$IMAGE:latest" && docker push "$IMAGE:${GITHUB_SHA}"
+          command -v cosign >/dev/null 2>&1 || { curl -sSfLo /usr/local/bin/cosign https://github.com/sigstore/cosign/releases/download/v2.4.3/cosign-linux-amd64 && chmod +x /usr/local/bin/cosign; }
+          cosign sign --yes --key env://COSIGN_KEY "$IMAGE:latest" || echo "::warning::cosign failed"
           PAYLOAD=$(printf '{"ref":"refs/heads/main","repository":{"full_name":"sharang/compliance-scanner-agent"},"head_commit":{"id":"%s","message":"deploy agent"}}' "${GITHUB_SHA}")
           SIG=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "${{ secrets.ORCA_WEBHOOK_SECRET }}" | awk '{print $2}')
           RESP=$(curl -fsS -w "\nHTTP %{http_code}" -X POST "http://46.225.100.82:6880/api/v1/webhooks/github" -H "Content-Type: application/json" -H "X-Hub-Signature-256: sha256=$SIG" -d "$PAYLOAD"); echo "$RESP"
@@ -230,11 +232,13 @@ jobs:
           apk add --no-cache git curl openssl
           git init && git remote add origin "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
           git fetch --depth=1 origin "${GITHUB_SHA}" && git checkout FETCH_HEAD
-          IMAGE=registry.meghsakha.com/compliance-dashboard
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login registry.meghsakha.com -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+          IMAGE=repo.meghsakha.com/certifai/compliance-dashboard
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login repo.meghsakha.com -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
           DOCKER_BUILDKIT=1 docker build --secret id=tramiton_token,env=TRAMITON_FETCH_TOKEN \
             -f Dockerfile.dashboard -t "$IMAGE:latest" -t "$IMAGE:${GITHUB_SHA}" .
           docker push "$IMAGE:latest" && docker push "$IMAGE:${GITHUB_SHA}"
+          command -v cosign >/dev/null 2>&1 || { curl -sSfLo /usr/local/bin/cosign https://github.com/sigstore/cosign/releases/download/v2.4.3/cosign-linux-amd64 && chmod +x /usr/local/bin/cosign; }
+          cosign sign --yes --key env://COSIGN_KEY "$IMAGE:latest" || echo "::warning::cosign failed"
           PAYLOAD=$(printf '{"ref":"refs/heads/main","repository":{"full_name":"sharang/compliance-scanner-agent"},"head_commit":{"id":"%s","message":"deploy dashboard"}}' "${GITHUB_SHA}")
           SIG=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "${{ secrets.ORCA_WEBHOOK_SECRET }}" | awk '{print $2}')
           RESP=$(curl -fsS -w "\nHTTP %{http_code}" -X POST "http://46.225.100.82:6880/api/v1/webhooks/github" -H "Content-Type: application/json" -H "X-Hub-Signature-256: sha256=$SIG" -d "$PAYLOAD"); echo "$RESP"
@@ -252,10 +256,12 @@ jobs:
           apk add --no-cache git curl openssl
           git init && git remote add origin "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
           git fetch --depth=1 origin "${GITHUB_SHA}" && git checkout FETCH_HEAD
-          IMAGE=registry.meghsakha.com/compliance-docs
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login registry.meghsakha.com -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+          IMAGE=repo.meghsakha.com/certifai/compliance-docs
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login repo.meghsakha.com -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
           docker build -f Dockerfile.docs -t "$IMAGE:latest" -t "$IMAGE:${GITHUB_SHA}" .
           docker push "$IMAGE:latest" && docker push "$IMAGE:${GITHUB_SHA}"
+          command -v cosign >/dev/null 2>&1 || { curl -sSfLo /usr/local/bin/cosign https://github.com/sigstore/cosign/releases/download/v2.4.3/cosign-linux-amd64 && chmod +x /usr/local/bin/cosign; }
+          cosign sign --yes --key env://COSIGN_KEY "$IMAGE:latest" || echo "::warning::cosign failed"
           PAYLOAD=$(printf '{"ref":"refs/heads/main","repository":{"full_name":"sharang/compliance-scanner-agent"},"head_commit":{"id":"%s","message":"deploy docs"}}' "${GITHUB_SHA}")
           SIG=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "${{ secrets.ORCA_WEBHOOK_SECRET }}" | awk '{print $2}')
           RESP=$(curl -fsS -w "\nHTTP %{http_code}" -X POST "http://46.225.100.82:6880/api/v1/webhooks/github" -H "Content-Type: application/json" -H "X-Hub-Signature-256: sha256=$SIG" -d "$PAYLOAD"); echo "$RESP"
@@ -275,11 +281,13 @@ jobs:
           apk add --no-cache git curl openssl
           git init && git remote add origin "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
           git fetch --depth=1 origin "${GITHUB_SHA}" && git checkout FETCH_HEAD
-          IMAGE=registry.meghsakha.com/compliance-mcp
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login registry.meghsakha.com -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+          IMAGE=repo.meghsakha.com/certifai/compliance-mcp
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login repo.meghsakha.com -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
           DOCKER_BUILDKIT=1 docker build --secret id=tramiton_token,env=TRAMITON_FETCH_TOKEN \
             -f Dockerfile.mcp -t "$IMAGE:latest" -t "$IMAGE:${GITHUB_SHA}" .
           docker push "$IMAGE:latest" && docker push "$IMAGE:${GITHUB_SHA}"
+          command -v cosign >/dev/null 2>&1 || { curl -sSfLo /usr/local/bin/cosign https://github.com/sigstore/cosign/releases/download/v2.4.3/cosign-linux-amd64 && chmod +x /usr/local/bin/cosign; }
+          cosign sign --yes --key env://COSIGN_KEY "$IMAGE:latest" || echo "::warning::cosign failed"
           PAYLOAD=$(printf '{"ref":"refs/heads/main","repository":{"full_name":"sharang/compliance-scanner-agent"},"head_commit":{"id":"%s","message":"deploy mcp"}}' "${GITHUB_SHA}")
           SIG=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "${{ secrets.ORCA_WEBHOOK_SECRET }}" | awk '{print $2}')
           RESP=$(curl -fsS -w "\nHTTP %{http_code}" -X POST "http://46.225.100.82:6880/api/v1/webhooks/github" -H "Content-Type: application/json" -H "X-Hub-Signature-256: sha256=$SIG" -d "$PAYLOAD"); echo "$RESP"

compliance-agent/rules/cra_semgrep.yaml

@@ -0,0 +1,117 @@
+# Custom semgrep rules for CRA controls that no off-the-shelf ruleset digs out.
+# Each rule id is `cra-ai-<n>-<slug>` and is keyed back to its control via the
+# `control-map` LUT (by rule-id suffix, so semgrep's path prefix on check_id does
+# not matter). Detection here is deterministic; the grounded LLM judge downstream
+# only confirms/refutes — it never detects. Keep patterns tight: a false positive
+# that the judge refutes marks the whole finding a false positive.
+rules:
+  # --- cra-ai-1: Secure-by-Default-Konfiguration -------------------------------
+  - id: cra-ai-1-flask-debug-enabled
+    languages: [python]
+    severity: WARNING
+    message: Flask app started with debug=True — ships an interactive debugger / code execution in production (secure-by-default violation).
+    metadata:
+      cwe: ["CWE-489: Active Debug Code"]
+      control: cra-ai-1
+    patterns:
+      - pattern: '$APP.run(..., debug=True, ...)'
+
+  - id: cra-ai-1-django-debug-true
+    languages: [python]
+    severity: WARNING
+    message: Django DEBUG = True — leaks stack traces / settings in production (secure-by-default violation).
+    metadata:
+      cwe: ["CWE-489: Active Debug Code"]
+      control: cra-ai-1
+    patterns:
+      - pattern: 'DEBUG = True'
+
+  - id: cra-ai-1-tls-verify-disabled
+    languages: [python]
+    severity: ERROR
+    message: TLS certificate verification disabled (verify=False) — defeats transport security by default.
+    metadata:
+      cwe: ["CWE-295: Improper Certificate Validation"]
+      control: cra-ai-1
+    patterns:
+      - pattern: 'requests.$M(..., verify=False, ...)'
+
+  - id: cra-ai-1-cors-wildcard
+    languages: [javascript, typescript]
+    severity: WARNING
+    message: CORS Access-Control-Allow-Origin set to "*" — opens the API to any origin by default.
+    metadata:
+      cwe: ["CWE-942: Permissive Cross-domain Policy with Untrusted Domains"]
+      control: cra-ai-1
+    patterns:
+      - pattern-either:
+          - pattern: '$RES.header("Access-Control-Allow-Origin", "*")'
+          - pattern: '$RES.setHeader("Access-Control-Allow-Origin", "*")'
+
+  # --- cra-ai-7: Starke Authentifizierung (weak password hashing) --------------
+  - id: cra-ai-7-weak-password-hash
+    languages: [python]
+    severity: ERROR
+    message: Password/secret hashed with a fast, broken digest (md5/sha1) — use a password KDF (bcrypt/scrypt/argon2).
+    metadata:
+      cwe: ["CWE-916: Use of Password Hash With Insufficient Computational Effort"]
+      control: cra-ai-7
+    patterns:
+      - pattern-either:
+          - pattern: 'hashlib.md5($PW)'
+          - pattern: 'hashlib.sha1($PW)'
+      - metavariable-regex:
+          metavariable: $PW
+          regex: '(?i).*(pass|pwd|secret|cred|token).*'
+
+  # --- cra-ai-10: Sitzungsmanagement (insecure session cookies) ----------------
+  - id: cra-ai-10-session-cookie-insecure
+    languages: [python]
+    severity: ERROR
+    message: Session cookie hardened flag explicitly disabled (Secure/HttpOnly = False) — session token exposed to theft.
+    metadata:
+      cwe: ["CWE-614: Sensitive Cookie in HTTPS Session Without 'Secure' Attribute"]
+      control: cra-ai-10
+    patterns:
+      - pattern-either:
+          - pattern: 'SESSION_COOKIE_SECURE = False'
+          - pattern: 'SESSION_COOKIE_HTTPONLY = False'
+
+  - id: cra-ai-10-express-cookie-insecure
+    languages: [javascript, typescript]
+    severity: ERROR
+    message: Express cookie set with secure/httpOnly = false — session token exposed to interception / XSS theft.
+    metadata:
+      cwe: ["CWE-614: Sensitive Cookie in HTTPS Session Without 'Secure' Attribute"]
+      control: cra-ai-10
+    patterns:
+      - pattern-either:
+          - pattern: '$RES.cookie($NAME, $VAL, {..., secure: false, ...})'
+          - pattern: '$RES.cookie($NAME, $VAL, {..., httpOnly: false, ...})'
+
+  # --- cra-ai-14: Speicher-Schutz / Data at Rest (weak cipher) -----------------
+  - id: cra-ai-14-python-weak-cipher
+    languages: [python]
+    severity: ERROR
+    message: Data-at-rest encrypted with a broken cipher/mode (ECB, DES, 3DES) — provides no real confidentiality.
+    metadata:
+      cwe: ["CWE-327: Use of a Broken or Risky Cryptographic Algorithm"]
+      control: cra-ai-14
+    patterns:
+      - pattern-either:
+          - pattern: 'AES.new($K, AES.MODE_ECB, ...)'
+          - pattern: 'DES.new(...)'
+          - pattern: 'DES3.new(...)'
+
+  - id: cra-ai-14-node-weak-cipher
+    languages: [javascript, typescript]
+    severity: ERROR
+    message: Data-at-rest encrypted with a broken cipher (DES / deprecated createCipher) — provides no real confidentiality.
+    metadata:
+      cwe: ["CWE-327: Use of a Broken or Risky Cryptographic Algorithm"]
+      control: cra-ai-14
+    patterns:
+      - pattern-either:
+          - pattern: 'crypto.createCipheriv("des-ecb", ...)'
+          - pattern: 'crypto.createCipheriv("des", ...)'
+          - pattern: 'crypto.createCipher(...)'

compliance-agent/src/api/handlers/oscal.rs

@@ -1,9 +1,9 @@
 //! OSCAL assessment endpoint.
 //!
-//! Assesses a target's findings against the breakpilot-compliance control
-//! catalog and returns a standard OSCAL assessment-results document. Ties
-//! together the ingest provider ([`OscalControlsProvider`]) and the assessment
-//! emitter (`compliance_core::models::oscal_assessment`).
+//! Returns a standard OSCAL assessment-results document for a target's findings,
+//! driven by each finding's stamped `control_refs` (from the scan's control-triage
+//! stage): mapped findings target their controls, unmapped findings are reported
+//! as-is. See `compliance_core::models::oscal_assessment`.
 
 use axum::extract::Extension;
 use axum::http::StatusCode;
@@ -12,45 +12,24 @@ use axum::Json;
 use mongodb::bson::doc;
 use serde::Deserialize;
 
-use compliance_core::models::onboarding::ComplianceFramework;
-use compliance_core::models::oscal_assessment::{assess, ControlLinker};
+use compliance_core::models::oscal_assessment::assess;
 use compliance_core::models::Finding;
 use compliance_core::tenant_ctx::TenantCtx;
 
 use super::dto::{collect_cursor_async, tenant_db, AgentExt};
-use crate::controls::OscalControlsProvider;
 
 #[derive(Debug, Deserialize)]
 pub struct AssessRequest {
     /// The target / repo id whose findings are assessed.
     pub target_id: String,
-    /// Frameworks to assess against; defaults to `[Cra]` when empty.
-    #[serde(default)]
-    pub frameworks: Vec<ComplianceFramework>,
 }
 
-/// `POST /api/v1/oscal/assess` — pull the catalog(s), load the target's findings,
-/// and emit an OSCAL assessment-results document linking findings to controls.
+/// `POST /api/v1/oscal/assess` — OSCAL assessment-results for a target's findings.
 pub async fn assess_target(
     Extension(agent): AgentExt,
     tenant: TenantCtx,
     Json(req): Json<AssessRequest>,
 ) -> Response {
-    let cfg = &agent.config.breakpilot;
-    let Some(base_url) = cfg.base_url.clone() else {
-        return (
-            StatusCode::SERVICE_UNAVAILABLE,
-            "breakpilot base URL not configured (set BREAKPILOT_BASE_URL)",
-        )
-            .into_response();
-    };
-
-    let frameworks = if req.frameworks.is_empty() {
-        vec![ComplianceFramework::Cra]
-    } else {
-        req.frameworks.clone()
-    };
-
     let db = match tenant_db(&agent, &tenant).await {
         Ok(db) => db,
         Err(code) => return code.into_response(),
@@ -65,25 +44,5 @@ pub async fn assess_target(
         }
     };
 
-    let provider = OscalControlsProvider::new(
-        agent.http.clone(),
-        base_url,
-        cfg.token.clone(),
-        &cfg.snapshot_dir,
-    );
-    let mut controls = Vec::new();
-    for framework in &frameworks {
-        match provider.load(*framework).await {
-            Ok(document) => controls.extend(document.to_controls()),
-            Err(e) => tracing::warn!(?framework, error = %e, "OSCAL catalog load failed"),
-        }
-    }
-
-    let assessment = assess(
-        &controls,
-        &findings,
-        &ControlLinker::cra_seed(),
-        chrono::Utc::now(),
-    );
-    Json(assessment).into_response()
+    Json(assess(&findings, chrono::Utc::now())).into_response()
 }

compliance-agent/src/config.rs

@@ -100,5 +100,11 @@ fn load_breakpilot_config() -> BreakpilotConfig {
         base_url: env_var_opt("BREAKPILOT_BASE_URL"),
         token: env_secret_opt("BREAKPILOT_TOKEN"),
         snapshot_dir: env_var_opt("BREAKPILOT_SNAPSHOT_DIR").unwrap_or(d.snapshot_dir),
+        semantic_mapping: env_var_opt("BREAKPILOT_SEMANTIC_MAPPING")
+            .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
+            .unwrap_or(d.semantic_mapping),
+        grounded_control_checks: env_var_opt("BREAKPILOT_GROUNDED_CHECKS")
+            .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
+            .unwrap_or(d.grounded_control_checks),
     }
 }

compliance-agent/src/controls/index.rs

@@ -0,0 +1,245 @@
+//! In-memory embedding index over the control corpus, for region → control
+//! retrieval.
+//!
+//! At master-control scale (~13.6k) findings can't be mapped by CWE (the master
+//! controls carry none), so we map by *similarity*: embed each control's
+//! requirement text once, then for a code region pull the top-K nearest controls
+//! to hand to the grounded judge. This is the retrieval half of the semantic path.
+
+use std::path::Path;
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use compliance_core::control_check::ControlCheckSpec;
+use compliance_core::error::CoreError;
+
+use crate::llm::LlmClient;
+
+/// A control spec paired with its requirement-text embedding.
+pub struct ControlIndex {
+    entries: Vec<(ControlCheckSpec, Vec<f64>)>,
+}
+
+/// On-disk form of the index: the corpus identity hash plus every spec+embedding.
+/// The hash lets a later scan reuse the embeddings only if the corpus is unchanged.
+#[derive(Serialize, Deserialize)]
+struct PersistedIndex {
+    corpus_hash: String,
+    entries: Vec<PersistedEntry>,
+}
+
+#[derive(Serialize, Deserialize)]
+struct PersistedEntry {
+    spec: ControlCheckSpec,
+    embedding: Vec<f64>,
+}
+
+/// Stable hash of the corpus identity (each control's id + requirement text, in
+/// order). Same catalog → same hash → the cached embeddings are reused instead of
+/// re-embedding the whole corpus.
+fn corpus_hash(specs: &[ControlCheckSpec]) -> String {
+    let mut hasher = Sha256::new();
+    for s in specs {
+        hasher.update(s.control_id.as_bytes());
+        hasher.update([0u8]);
+        hasher.update(s.requirement.as_bytes());
+        hasher.update([0u8]);
+    }
+    format!("{:x}", hasher.finalize())
+}
+
+impl ControlIndex {
+    /// Build directly from precomputed embeddings (used by tests + callers that
+    /// already embedded the corpus).
+    pub fn from_embeddings(entries: Vec<(ControlCheckSpec, Vec<f64>)>) -> Self {
+        Self { entries }
+    }
+
+    /// Load the index from `cache_path` if it still matches the current corpus,
+    /// otherwise embed the corpus and persist it there. This turns the per-scan
+    /// re-embed of the whole (~13.6k) master-control corpus into a one-time cost
+    /// that survives across scans; the cache self-invalidates when the catalog
+    /// changes (its [`corpus_hash`] no longer matches).
+    pub async fn load_or_build(
+        llm: &LlmClient,
+        specs: Vec<ControlCheckSpec>,
+        cache_path: &Path,
+    ) -> Result<Self, CoreError> {
+        let hash = corpus_hash(&specs);
+        if let Some(index) = Self::load_cache(cache_path, &hash).await {
+            tracing::debug!(
+                controls = index.len(),
+                "reusing cached control embedding index"
+            );
+            return Ok(index);
+        }
+        let index = Self::build(llm, specs).await?;
+        if let Err(e) = index.write_cache(cache_path, &hash).await {
+            tracing::warn!(error = %e, "failed to persist control embedding index");
+        }
+        Ok(index)
+    }
+
+    /// Read a persisted index, returning it only if its corpus hash matches.
+    async fn load_cache(path: &Path, hash: &str) -> Option<Self> {
+        let raw = tokio::fs::read(path).await.ok()?;
+        let persisted: PersistedIndex = serde_json::from_slice(&raw).ok()?;
+        if persisted.corpus_hash != hash {
+            return None;
+        }
+        Some(Self {
+            entries: persisted
+                .entries
+                .into_iter()
+                .map(|e| (e.spec, e.embedding))
+                .collect(),
+        })
+    }
+
+    /// Persist the index atomically (temp file + rename) keyed by corpus hash.
+    async fn write_cache(&self, path: &Path, hash: &str) -> Result<(), CoreError> {
+        if let Some(parent) = path.parent() {
+            tokio::fs::create_dir_all(parent).await?;
+        }
+        let persisted = PersistedIndex {
+            corpus_hash: hash.to_string(),
+            entries: self
+                .entries
+                .iter()
+                .map(|(spec, emb)| PersistedEntry {
+                    spec: spec.clone(),
+                    embedding: emb.clone(),
+                })
+                .collect(),
+        };
+        let raw = serde_json::to_vec(&persisted)?;
+        let tmp = path.with_extension("json.tmp");
+        tokio::fs::write(&tmp, &raw).await?;
+        tokio::fs::rename(&tmp, path).await?;
+        Ok(())
+    }
+
+    /// Build by embedding each control's requirement text.
+    pub async fn build(llm: &LlmClient, specs: Vec<ControlCheckSpec>) -> Result<Self, CoreError> {
+        if specs.is_empty() {
+            return Ok(Self {
+                entries: Vec::new(),
+            });
+        }
+        let texts: Vec<String> = specs.iter().map(|s| s.requirement.clone()).collect();
+        let embeddings = llm
+            .embed(texts)
+            .await
+            .map_err(|e| CoreError::Llm(e.to_string()))?;
+        Ok(Self {
+            entries: specs.into_iter().zip(embeddings).collect(),
+        })
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    /// The top-`k` control specs whose embedding is nearest (cosine) to `query`.
+    pub fn nearest(&self, query: &[f64], k: usize) -> Vec<ControlCheckSpec> {
+        let mut scored: Vec<(f64, &ControlCheckSpec)> = self
+            .entries
+            .iter()
+            .map(|(spec, emb)| (cosine(query, emb), spec))
+            .collect();
+        scored.sort_by(|a, b| b.0.total_cmp(&a.0));
+        scored.into_iter().take(k).map(|(_, s)| s.clone()).collect()
+    }
+}
+
+/// Cosine similarity; 0.0 for length-mismatched, empty, or zero vectors.
+fn cosine(a: &[f64], b: &[f64]) -> f64 {
+    if a.len() != b.len() || a.is_empty() {
+        return 0.0;
+    }
+    let dot: f64 = a.iter().zip(b).map(|(x, y)| x * y).sum();
+    let na: f64 = a.iter().map(|x| x * x).sum();
+    let nb: f64 = b.iter().map(|x| x * x).sum();
+    if na == 0.0 || nb == 0.0 {
+        return 0.0;
+    }
+    dot / (na.sqrt() * nb.sqrt())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use compliance_core::models::finding::Severity;
+
+    fn spec(id: &str) -> ControlCheckSpec {
+        ControlCheckSpec {
+            control_id: id.into(),
+            title: id.into(),
+            requirement: id.into(),
+            default_cwe: None,
+            severity: Severity::Medium,
+        }
+    }
+
+    #[test]
+    fn nearest_ranks_by_cosine() {
+        let index = ControlIndex::from_embeddings(vec![
+            (spec("a"), vec![1.0, 0.0]),
+            (spec("b"), vec![0.0, 1.0]),
+            (spec("c"), vec![0.7, 0.7]),
+        ]);
+        let hits = index.nearest(&[0.9, 0.1], 2);
+        assert_eq!(hits.len(), 2);
+        assert_eq!(hits[0].control_id, "a"); // closest to [0.9,0.1]
+    }
+
+    #[test]
+    fn cosine_edges_are_zero() {
+        assert_eq!(cosine(&[1.0], &[1.0, 2.0]), 0.0); // length mismatch
+        assert_eq!(cosine(&[0.0, 0.0], &[1.0, 1.0]), 0.0); // zero vector
+        assert!((cosine(&[1.0, 0.0], &[1.0, 0.0]) - 1.0).abs() < 1e-9); // identical
+    }
+
+    #[test]
+    fn corpus_hash_is_stable_and_identity_sensitive() {
+        let a = corpus_hash(&[spec("x"), spec("y")]);
+        assert_eq!(a, corpus_hash(&[spec("x"), spec("y")])); // same corpus → same hash
+        assert_ne!(a, corpus_hash(&[spec("y"), spec("x")])); // reorder → different
+        assert_ne!(a, corpus_hash(&[spec("x")])); // fewer controls → different
+    }
+
+    #[tokio::test]
+    #[allow(clippy::unwrap_used)]
+    async fn cache_round_trips_and_misses_on_corpus_change() {
+        let dir = std::env::temp_dir().join(format!("cidx-{}", uuid::Uuid::new_v4()));
+        let path = dir.join("control-index.json");
+        let specs = [spec("a"), spec("b")];
+        let hash = corpus_hash(&specs);
+        let index = ControlIndex::from_embeddings(vec![
+            (spec("a"), vec![1.0, 0.0]),
+            (spec("b"), vec![0.0, 1.0]),
+        ]);
+        index.write_cache(&path, &hash).await.unwrap();
+
+        // matching corpus hash → hit
+        let loaded = ControlIndex::load_cache(&path, &hash).await.unwrap();
+        assert_eq!(loaded.len(), 2);
+        assert_eq!(loaded.nearest(&[0.9, 0.1], 1)[0].control_id, "a");
+        // corpus changed → miss (forces a rebuild)
+        assert!(ControlIndex::load_cache(&path, "differenthash")
+            .await
+            .is_none());
+        // absent file → miss, not an error
+        assert!(
+            ControlIndex::load_cache(dir.join("nope.json").as_path(), &hash)
+                .await
+                .is_none()
+        );
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+}

compliance-agent/src/controls/mod.rs

@@ -6,13 +6,18 @@
 //! and snapshots it locally.
 
 mod checker;
+mod index;
 mod judge;
 mod oscal_provider;
 mod scan_triage;
+mod semantic;
+mod surface;
 mod triage;
 
 pub use checker::GroundedControlChecker;
+pub use index::ControlIndex;
 pub use judge::{ControlJudge, LlmControlJudge, PROMPT_VERSION};
 pub use oscal_provider::OscalControlsProvider;
-pub use scan_triage::triage_repo_findings;
+pub use scan_triage::{grounded_surface_findings, semantic_stamp_findings, triage_repo_findings};
+pub use semantic::SemanticControlChecker;
 pub use triage::{ControlTriage, TriageOutcome};

compliance-agent/src/controls/oscal_provider.rs

@@ -43,20 +43,20 @@ impl OscalControlsProvider {
         }
     }
 
-    fn catalog_url(&self, framework: ComplianceFramework) -> String {
+    fn catalog_url(&self, framework: &str) -> String {
         format!(
             "{}/api/compliance/v1/oscal/catalog?framework={framework}",
             self.base_url.trim_end_matches('/')
         )
     }
 
-    fn snapshot_path(&self, framework: ComplianceFramework) -> PathBuf {
+    fn snapshot_path(&self, framework: &str) -> PathBuf {
         self.snapshot_dir
             .join(format!("oscal-catalog-{framework}.json"))
     }
 
-    /// Fetch the raw catalog bytes for a framework over HTTP.
-    async fn fetch_raw(&self, framework: ComplianceFramework) -> Result<Vec<u8>, CoreError> {
+    /// Fetch the raw catalog bytes for a framework token over HTTP.
+    async fn fetch_raw(&self, framework: &str) -> Result<Vec<u8>, CoreError> {
         let mut req = self.http.get(self.catalog_url(framework));
         if let Some(token) = &self.token {
             req = req.bearer_auth(token.expose_secret());
@@ -78,11 +78,7 @@ impl OscalControlsProvider {
     }
 
     /// Write a catalog snapshot atomically (temp file + rename).
-    async fn write_snapshot(
-        &self,
-        framework: ComplianceFramework,
-        raw: &[u8],
-    ) -> Result<(), CoreError> {
+    async fn write_snapshot(&self, framework: &str, raw: &[u8]) -> Result<(), CoreError> {
         tokio::fs::create_dir_all(&self.snapshot_dir).await?;
         let path = self.snapshot_path(framework);
         let tmp = path.with_extension("json.tmp");
@@ -92,10 +88,7 @@ impl OscalControlsProvider {
     }
 
     /// Read a previously written snapshot, if one exists.
-    async fn read_snapshot(
-        &self,
-        framework: ComplianceFramework,
-    ) -> Result<Option<OscalDocument>, CoreError> {
+    async fn read_snapshot(&self, framework: &str) -> Result<Option<OscalDocument>, CoreError> {
         match tokio::fs::read(self.snapshot_path(framework)).await {
             Ok(raw) => Ok(Some(serde_json::from_slice(&raw)?)),
             Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
@@ -103,21 +96,21 @@ impl OscalControlsProvider {
         }
     }
 
-    /// Load the catalog for a framework: fetch fresh + snapshot the exact bytes;
-    /// on network failure, fall back to the last snapshot so scans still run.
-    pub async fn load(&self, framework: ComplianceFramework) -> Result<OscalDocument, CoreError> {
+    /// Load the catalog for a framework token: fetch fresh + snapshot the exact
+    /// bytes; on network failure, fall back to the last snapshot so scans run.
+    async fn load_token(&self, framework: &str) -> Result<OscalDocument, CoreError> {
         match self.fetch_raw(framework).await {
             Ok(raw) => {
                 let doc: OscalDocument = serde_json::from_slice(&raw)?;
                 if let Err(e) = self.write_snapshot(framework, &raw).await {
-                    tracing::warn!(%framework, error = %e, "failed to write OSCAL snapshot");
+                    tracing::warn!(framework, error = %e, "failed to write OSCAL snapshot");
                 }
                 Ok(doc)
             }
             Err(fetch_err) => match self.read_snapshot(framework).await? {
                 Some(doc) => {
                     tracing::warn!(
-                        %framework, error = %fetch_err,
+                        framework, error = %fetch_err,
                         "OSCAL catalog fetch failed; falling back to snapshot"
                     );
                     Ok(doc)
@@ -126,6 +119,17 @@ impl OscalControlsProvider {
             },
         }
     }
+
+    /// Load the OSCAL catalog for a compliance framework.
+    pub async fn load(&self, framework: ComplianceFramework) -> Result<OscalDocument, CoreError> {
+        self.load_token(&framework.to_string()).await
+    }
+
+    /// Load the code-checkable master-controls catalog
+    /// (`?framework=master-controls`).
+    pub async fn load_master_controls(&self) -> Result<OscalDocument, CoreError> {
+        self.load_token("master-controls").await
+    }
 }
 
 /// Order controls whose title/text mention the query context first (stable), then
@@ -181,11 +185,11 @@ mod tests {
     fn builds_catalog_url_and_snapshot_path() {
         let p = provider(std::path::Path::new("/snap"));
         assert_eq!(
-            p.catalog_url(ComplianceFramework::Cra),
+            p.catalog_url("cra"),
             "http://unused/api/compliance/v1/oscal/catalog?framework=cra"
         );
         assert_eq!(
-            p.snapshot_path(ComplianceFramework::Cra),
+            p.snapshot_path("cra"),
             std::path::Path::new("/snap/oscal-catalog-cra.json")
         );
     }
@@ -213,19 +217,11 @@ mod tests {
     async fn snapshot_round_trip_and_offline_fallback() {
         let dir = std::env::temp_dir().join(format!("oscal-test-{}", uuid::Uuid::new_v4()));
         let p = provider(&dir);
-        assert!(p
-            .read_snapshot(ComplianceFramework::Cra)
-            .await
-            .unwrap()
-            .is_none());
-        p.write_snapshot(ComplianceFramework::Cra, MINI_CATALOG.as_bytes())
+        assert!(p.read_snapshot("cra").await.unwrap().is_none());
+        p.write_snapshot("cra", MINI_CATALOG.as_bytes())
             .await
             .unwrap();
-        let doc = p
-            .read_snapshot(ComplianceFramework::Cra)
-            .await
-            .unwrap()
-            .unwrap();
+        let doc = p.read_snapshot("cra").await.unwrap().unwrap();
         assert_eq!(doc.to_controls().len(), 1);
         assert_eq!(doc.framework(), Some(ComplianceFramework::Cra));
         let _ = std::fs::remove_dir_all(&dir);

compliance-agent/src/controls/scan_triage.rs

@@ -16,9 +16,16 @@ use compliance_core::models::onboarding::ComplianceFramework;
 use compliance_core::AgentConfig;
 use control_map::ControlMap;
 
-use super::{ControlTriage, LlmControlJudge, OscalControlsProvider, TriageOutcome};
+use super::surface;
+use super::{
+    ControlIndex, ControlTriage, GroundedControlChecker, LlmControlJudge, OscalControlsProvider,
+    SemanticControlChecker, TriageOutcome,
+};
 use crate::llm::LlmClient;
 
+/// Nearest master controls judged per code region in the semantic pass.
+const SEMANTIC_TOP_K: usize = 5;
+
 /// Lines of context to read on each side of a finding's line.
 const REGION_WINDOW: usize = 6;
 
@@ -99,6 +106,50 @@ async fn build_specs(provider: &OscalControlsProvider) -> HashMap<String, Contro
     specs
 }
 
+/// Absence-based control pass (the grounded half of the hybrid coverage): for each
+/// control with a [`surface`] definition, deterministically retrieve the code
+/// surfaces it governs (login routes, logging setup, update/download code) and have
+/// the grounded judge decide whether the control holds there. Returns net-new
+/// findings, each already tagged with its control and grounded to a real snippet.
+///
+/// Gated: the orchestrator runs this only when `breakpilot.grounded_control_checks`
+/// is set. Absence detection is the least deterministic path (the judge decides
+/// presence/absence, not a syntactic pattern), so it stays off until tuned live.
+pub async fn grounded_surface_findings(
+    config: &AgentConfig,
+    llm: Arc<LlmClient>,
+    repo_path: &Path,
+    repo_id: &str,
+) -> Vec<Finding> {
+    let Some(base_url) = config.breakpilot.base_url.clone() else {
+        return Vec::new();
+    };
+    let provider = OscalControlsProvider::new(
+        reqwest::Client::new(),
+        base_url,
+        config.breakpilot.token.clone(),
+        &config.breakpilot.snapshot_dir,
+    );
+    let specs = build_specs(&provider).await;
+    if specs.is_empty() {
+        return Vec::new();
+    }
+    let checker = GroundedControlChecker::new(LlmControlJudge::new(llm));
+
+    let mut out = Vec::new();
+    for surf in surface::SURFACES {
+        let Some(spec) = specs.get(surf.control_id) else {
+            continue; // catalog doesn't carry this control
+        };
+        let regions = surface::retrieve(repo_path, surf.terms);
+        if regions.is_empty() {
+            continue;
+        }
+        out.extend(checker.check(spec, &regions, repo_id).await);
+    }
+    out
+}
+
 /// Read a window of lines around `line` (1-based) from `repo_path/file`.
 fn fetch_region(repo_path: &Path, file: &str, line: u32) -> Option<CandidateRegion> {
     let content = std::fs::read_to_string(repo_path.join(file)).ok()?;
@@ -116,6 +167,107 @@ fn fetch_region(repo_path: &Path, file: &str, line: u32) -> Option<CandidateRegi
     })
 }
 
+/// Master-controls **semantic** pass: for each finding's code region, retrieve the
+/// top-K nearest master controls by embedding, have the grounded judge confirm,
+/// and stamp the confirmed control ids onto the finding — the scale path for the
+/// ~13.6k master-control corpus (which has no CWE to LUT on). Returns the number
+/// of findings that gained a master-control ref.
+///
+/// Gated: the orchestrator runs this only when `breakpilot.semantic_mapping` is
+/// set (default off, flipped on once the master-controls catalog is live). The
+/// control embedding index is built once and cached to `snapshot_dir` keyed by
+/// corpus hash ([`ControlIndex::load_or_build`]), so only the first scan after a
+/// catalog change pays the embedding cost.
+pub async fn semantic_stamp_findings(
+    config: &AgentConfig,
+    llm: Arc<LlmClient>,
+    repo_path: &Path,
+    findings: &mut [Finding],
+) -> usize {
+    let Some(base_url) = config.breakpilot.base_url.clone() else {
+        return 0;
+    };
+    let provider = OscalControlsProvider::new(
+        reqwest::Client::new(),
+        base_url,
+        config.breakpilot.token.clone(),
+        &config.breakpilot.snapshot_dir,
+    );
+    let doc = match provider.load_master_controls().await {
+        Ok(d) => d,
+        Err(e) => {
+            tracing::warn!(error = %e, "master-controls catalog unavailable; skipping semantic pass");
+            return 0;
+        }
+    };
+    let specs: Vec<ControlCheckSpec> = doc
+        .to_controls()
+        .into_iter()
+        .map(|c| ControlCheckSpec {
+            control_id: c.id,
+            title: c.title,
+            requirement: c.text,
+            default_cwe: None,
+            severity: Severity::Medium,
+        })
+        .collect();
+    let cache_path =
+        Path::new(&config.breakpilot.snapshot_dir).join("control-index-master-controls.json");
+    let index = match ControlIndex::load_or_build(&llm, specs, &cache_path).await {
+        Ok(i) if !i.is_empty() => i,
+        Ok(_) => return 0,
+        Err(e) => {
+            tracing::warn!(error = %e, "failed to embed master-controls corpus");
+            return 0;
+        }
+    };
+    let checker = SemanticControlChecker::new(LlmControlJudge::new(llm.clone()));
+
+    let mut tagged = 0;
+    for finding in findings.iter_mut() {
+        if finding.status == FindingStatus::FalsePositive {
+            continue;
+        }
+        let (Some(file), Some(line)) = (finding.file_path.clone(), finding.line_number) else {
+            continue;
+        };
+        let Some(region) = fetch_region(repo_path, &file, line) else {
+            continue;
+        };
+        let region_emb = match llm.embed(vec![region.content.clone()]).await {
+            Ok(mut embs) => match embs.pop() {
+                Some(v) => v,
+                None => continue,
+            },
+            Err(e) => {
+                tracing::warn!(error = %e, "region embed failed; skipping finding");
+                continue;
+            }
+        };
+        let confirmed = checker
+            .check(
+                &index,
+                &region,
+                &region_emb,
+                SEMANTIC_TOP_K,
+                &finding.repo_id,
+            )
+            .await;
+        let before = finding.control_refs.len();
+        for f in confirmed {
+            for cref in f.control_refs {
+                if !finding.control_refs.contains(&cref) {
+                    finding.control_refs.push(cref);
+                }
+            }
+        }
+        if finding.control_refs.len() > before {
+            tagged += 1;
+        }
+    }
+    tagged
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

compliance-agent/src/controls/semantic.rs

@@ -0,0 +1,119 @@
+//! Semantic control mapping: retrieve the top-K controls nearest a code region,
+//! then confirm each with the grounded judge.
+//!
+//! The `region → controls` direction (vs. the CWE-LUT's `finding → control`) is
+//! what scales to the full master-control corpus: the LLM only ever judges a
+//! handful of retrieved candidates, and every surviving verdict is still anchored
+//! to real code by the grounding gate.
+
+use compliance_core::control_check::{ground, CandidateRegion};
+use compliance_core::models::Finding;
+
+use super::index::ControlIndex;
+use super::judge::ControlJudge;
+
+/// Retrieve → judge → ground, generic over the judge so tests use a stub.
+pub struct SemanticControlChecker<J> {
+    judge: J,
+}
+
+impl<J: ControlJudge> SemanticControlChecker<J> {
+    pub fn new(judge: J) -> Self {
+        Self { judge }
+    }
+
+    /// Map a code region to the controls it violates. `region_embedding` is the
+    /// region's embedding (the caller computes it via the LLM); the top-`k`
+    /// nearest controls in `index` are judged and grounded.
+    pub async fn check(
+        &self,
+        index: &ControlIndex,
+        region: &CandidateRegion,
+        region_embedding: &[f64],
+        k: usize,
+        repo_id: &str,
+    ) -> Vec<Finding> {
+        let candidates = index.nearest(region_embedding, k);
+        let mut findings = Vec::new();
+        for spec in &candidates {
+            let verdict = self.judge.judge(spec, region).await;
+            if let Some(finding) = ground(spec, region, &verdict, repo_id) {
+                findings.push(finding);
+            }
+        }
+        findings
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use compliance_core::control_check::{ControlCheckSpec, LlmVerdict};
+    use compliance_core::models::finding::Severity;
+
+    struct StubJudge {
+        verdict: LlmVerdict,
+    }
+    impl ControlJudge for StubJudge {
+        async fn judge(&self, _s: &ControlCheckSpec, _r: &CandidateRegion) -> LlmVerdict {
+            self.verdict.clone()
+        }
+    }
+
+    fn spec(id: &str) -> ControlCheckSpec {
+        ControlCheckSpec {
+            control_id: id.into(),
+            title: id.into(),
+            requirement: id.into(),
+            default_cwe: None,
+            severity: Severity::Medium,
+        }
+    }
+
+    #[tokio::test]
+    async fn retrieves_then_grounds_the_nearest_control() {
+        let index = ControlIndex::from_embeddings(vec![
+            (spec("mc-near"), vec![1.0, 0.0]),
+            (spec("mc-far"), vec![0.0, 1.0]),
+        ]);
+        let checker = SemanticControlChecker::new(StubJudge {
+            verdict: LlmVerdict {
+                violates: true,
+                snippet: "PASSWORD = \"admin\"".into(),
+                cwe: None,
+                confidence: 0.9,
+            },
+        });
+        let region = CandidateRegion {
+            file: "src/auth.py".into(),
+            start_line: 1,
+            content: "PASSWORD = \"admin\"\n".into(),
+        };
+        // Query embedding nearest to mc-near; k=1 → only mc-near is judged.
+        let findings = checker
+            .check(&index, &region, &[0.95, 0.05], 1, "repo")
+            .await;
+        assert_eq!(findings.len(), 1);
+        assert_eq!(findings[0].control_refs, vec!["mc-near".to_string()]);
+    }
+
+    #[tokio::test]
+    async fn ungrounded_verdict_is_dropped() {
+        let index = ControlIndex::from_embeddings(vec![(spec("mc-near"), vec![1.0, 0.0])]);
+        let checker = SemanticControlChecker::new(StubJudge {
+            verdict: LlmVerdict {
+                violates: true,
+                snippet: "not in the region".into(),
+                cwe: None,
+                confidence: 0.9,
+            },
+        });
+        let region = CandidateRegion {
+            file: "f".into(),
+            start_line: 1,
+            content: "real code\n".into(),
+        };
+        let findings = checker.check(&index, &region, &[1.0, 0.0], 1, "repo").await;
+        assert!(findings.is_empty());
+    }
+}

compliance-agent/src/controls/surface.rs

@@ -0,0 +1,258 @@
+//! 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-12", // Rollenbasierte Autorisierung (RBAC)
+        terms: &[
+            "authorize",
+            "permission",
+            "role",
+            "rbac",
+            "require_role",
+            "has_role",
+        ],
+    },
+    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(), 8);
+        for id in [
+            "cra-ai-6",
+            "cra-ai-11",
+            "cra-ai-12",
+            "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]);
+    }
+}

compliance-agent/src/controls/triage.rs

@@ -44,10 +44,14 @@ impl<J: ControlJudge> ControlTriage<J> {
     /// Triage one tool finding. `region` is the code around the finding, used as
     /// the grounding evidence for the judge.
     pub async fn triage(&self, finding: &Finding, region: &CandidateRegion) -> TriageOutcome {
-        let Some(cwe) = finding.cwe.as_deref() else {
-            return TriageOutcome::Unmapped;
-        };
-        let mapped = self.map.controls_for(&finding.scanner, cwe);
+        // Match by CWE (off-the-shelf findings) and/or rule id (our custom
+        // detectors, which carry no LUT-bound CWE). A finding with neither is
+        // simply unmapped.
+        let mapped = self.map.controls_for_finding(
+            &finding.scanner,
+            finding.cwe.as_deref(),
+            finding.rule_id.as_deref(),
+        );
         if mapped.is_empty() {
             return TriageOutcome::Unmapped;
         }
@@ -162,6 +166,52 @@ mod tests {
         assert_eq!(out, TriageOutcome::FalsePositive);
     }
 
+    #[tokio::test]
+    async fn custom_rule_finding_without_cwe_is_confirmed() {
+        // A custom detector finding carries a rule id but no LUT-bound CWE; it must
+        // still map (by rule id) and confirm.
+        let mut specs = specs();
+        specs.insert(
+            "cra-ai-1".to_string(),
+            ControlCheckSpec {
+                control_id: "cra-ai-1".into(),
+                title: "Secure-by-Default".into(),
+                requirement: "Ship secure defaults".into(),
+                default_cwe: None,
+                severity: Severity::Medium,
+            },
+        );
+        let triage = ControlTriage::new(
+            StubJudge {
+                verdict: LlmVerdict {
+                    violates: true,
+                    snippet: "app.run(debug=True)".into(),
+                    cwe: None,
+                    confidence: 0.9,
+                },
+            },
+            ControlMap::cra().unwrap(),
+            specs,
+        );
+        let mut f = Finding::new(
+            "repo".into(),
+            "fp".into(),
+            "semgrep".into(),
+            ScanType::Sast,
+            "flask debug".into(),
+            "desc".into(),
+            Severity::Medium,
+        );
+        f.rule_id = Some("tmp.x.cra-ai-1-flask-debug-enabled".into()); // no cwe
+        let region = CandidateRegion {
+            file: "app.py".into(),
+            start_line: 1,
+            content: "app.run(debug=True)\n".into(),
+        };
+        let out = triage.triage(&f, &region).await;
+        assert_eq!(out, TriageOutcome::Confirmed(vec!["cra-ai-1".to_string()]));
+    }
+
     #[tokio::test]
     async fn unmapped_cwe_is_left_untagged() {
         let triage = ControlTriage::new(

compliance-agent/src/pipeline/orchestrator.rs

@@ -230,6 +230,53 @@ impl PipelineOrchestrator {
             tracing::info!("[{repo_id}] Control triage tagged {tagged} findings with control refs");
         }
 
+        // Stage 5c: semantic control mapping — scale path for the master-controls
+        // corpus (no CWE to LUT on): embed each finding's region, retrieve the
+        // nearest master controls, grounded-judge, and stamp confirmed refs. Gated
+        // (default off) as the corpus embedding + per-finding judging is the heavy
+        // path; enabled once verified live against a deployed master-controls catalog.
+        if self.config.breakpilot.semantic_mapping {
+            self.update_phase(scan_run_id, "semantic_control_mapping")
+                .await;
+            let sem = crate::controls::semantic_stamp_findings(
+                &self.config,
+                self.llm.clone(),
+                &repo_path,
+                &mut all_findings,
+            )
+            .await;
+            if sem > 0 {
+                tracing::info!(
+                    "[{repo_id}] Semantic mapping tagged {sem} findings with master-control refs"
+                );
+            }
+        }
+
+        // Stage 5d: grounded surface checks — the absence-based controls (no
+        // rate limiting, no security logging, no update-signature check) have no
+        // syntactic pattern to match, so we retrieve the code surface each governs
+        // and let the grounded judge decide whether it holds, producing net-new
+        // findings already tagged + grounded. Gated (default off): absence
+        // detection is the least deterministic path, kept off until tuned live.
+        if self.config.breakpilot.grounded_control_checks {
+            self.update_phase(scan_run_id, "grounded_control_checks")
+                .await;
+            let grounded = crate::controls::grounded_surface_findings(
+                &self.config,
+                self.llm.clone(),
+                &repo_path,
+                &repo_id,
+            )
+            .await;
+            if !grounded.is_empty() {
+                tracing::info!(
+                    "[{repo_id}] Grounded surface checks raised {} control findings",
+                    grounded.len()
+                );
+                all_findings.extend(grounded);
+            }
+        }
+
         // Dedup against existing findings and insert new ones
         let mut new_count = 0u32;
         let mut new_findings: Vec<Finding> = Vec::new();

compliance-agent/src/pipeline/semgrep.rs

@@ -1,4 +1,4 @@
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
 use compliance_core::models::{Finding, ScanType, Severity};
 use compliance_core::traits::{ScanOutput, Scanner};
@@ -6,6 +6,30 @@ use compliance_core::CoreError;
 
 use crate::pipeline::dedup;
 
+/// Custom CRA-control detectors bundled into the binary and staged to a temp file
+/// at scan time so semgrep can `--config` them alongside the auto ruleset. These
+/// cover controls no off-the-shelf rule digs out (secure defaults, weak password
+/// hashing, insecure session cookies, weak data-at-rest ciphers); each rule id is
+/// keyed back to its control by the `control-map` LUT.
+const CRA_RULES: &str = include_str!("../../rules/cra_semgrep.yaml");
+
+/// Write the bundled CRA rules to a stable temp path (atomic: unique tmp +
+/// rename). Returns `None` on failure — the scan then runs with auto rules only.
+async fn stage_cra_rules() -> Option<PathBuf> {
+    let dir = std::env::temp_dir();
+    let path = dir.join("compliance-cra-semgrep.yaml");
+    let tmp = dir.join(format!("compliance-cra-semgrep.{}.tmp", std::process::id()));
+    if let Err(e) = tokio::fs::write(&tmp, CRA_RULES).await {
+        tracing::warn!(error = %e, "failed to stage custom CRA semgrep rules; using auto rules only");
+        return None;
+    }
+    if let Err(e) = tokio::fs::rename(&tmp, &path).await {
+        tracing::warn!(error = %e, "failed to stage custom CRA semgrep rules; using auto rules only");
+        return None;
+    }
+    Some(path)
+}
+
 pub struct SemgrepScanner;
 
 impl Scanner for SemgrepScanner {
@@ -19,30 +43,26 @@ impl Scanner for SemgrepScanner {
 
     #[tracing::instrument(skip_all)]
     async fn scan(&self, repo_path: &Path, repo_id: &str) -> Result<ScanOutput, CoreError> {
-        let output = tokio::time::timeout(
-            std::time::Duration::from_secs(600),
-            tokio::process::Command::new("semgrep")
-                .args([
-                    "--config=auto",
-                    "--json",
-                    "--quiet",
-                    "--max-memory",
-                    "500",
-                    "--jobs",
-                    "1",
-                ])
-                .arg(repo_path)
-                .output(),
-        )
-        .await
-        .map_err(|_| CoreError::Scanner {
-            scanner: "semgrep".to_string(),
-            source: "timed out after 10 minutes".into(),
-        })?
-        .map_err(|e| CoreError::Scanner {
-            scanner: "semgrep".to_string(),
-            source: Box::new(e),
-        })?;
+        let cra_rules = stage_cra_rules().await;
+        let mut command = tokio::process::Command::new("semgrep");
+        command.arg("--config=auto");
+        if let Some(path) = &cra_rules {
+            command.arg(format!("--config={}", path.display()));
+        }
+        command
+            .args(["--json", "--quiet", "--max-memory", "500", "--jobs", "1"])
+            .arg(repo_path);
+
+        let output = tokio::time::timeout(std::time::Duration::from_secs(600), command.output())
+            .await
+            .map_err(|_| CoreError::Scanner {
+                scanner: "semgrep".to_string(),
+                source: "timed out after 10 minutes".into(),
+            })?
+            .map_err(|e| CoreError::Scanner {
+                scanner: "semgrep".to_string(),
+                source: Box::new(e),
+            })?;
 
         if !output.status.success() && output.stdout.is_empty() {
             let stderr = String::from_utf8_lossy(&output.stderr);

compliance-core/src/config.rs

@@ -75,6 +75,16 @@ pub struct BreakpilotConfig {
     pub token: Option<SecretString>,
     /// Directory for catalog snapshots.
     pub snapshot_dir: String,
+    /// Enable the master-controls **semantic** mapping pass (embed regions,
+    /// retrieve nearest controls, grounded-judge). Off by default: it is the
+    /// scale path and stays gated until verified live against a deployed
+    /// master-controls catalog.
+    pub semantic_mapping: bool,
+    /// Enable the **grounded surface** pass for absence-based controls (retrieve
+    /// the code surface a control governs, judge whether it holds). Off by
+    /// default: absence detection is the least deterministic path and stays gated
+    /// until tuned against live scans.
+    pub grounded_control_checks: bool,
 }
 
 impl Default for BreakpilotConfig {
@@ -83,6 +93,8 @@ impl Default for BreakpilotConfig {
             base_url: None,
             token: None,
             snapshot_dir: "/data/compliance-scanner/oscal".to_string(),
+            semantic_mapping: false,
+            grounded_control_checks: false,
         }
     }
 }

compliance-core/src/control_check.rs

@@ -14,13 +14,14 @@
 //! The LLM supplies cross-language / cross-stack pattern recognition; this module
 //! supplies the determinism.
 
+use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
 
 use crate::models::finding::{Finding, Severity};
 use crate::models::scan::ScanType;
 
 /// A control rendered as a check the LLM judges code against.
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ControlCheckSpec {
     /// Stable control id, e.g. `"cra-ai-8"`.
     pub control_id: String,

compliance-core/src/models/oscal_assessment.rs

@@ -15,8 +15,7 @@ use chrono::{DateTime, Utc};
 use serde::Serialize;
 use uuid::Uuid;
 
-use crate::models::finding::Finding;
-use crate::traits::Control;
+use crate::models::finding::{Finding, FindingStatus};
 
 const OSCAL_VERSION: &str = "1.1.2";
 /// Same namespace as the catalog exporter, so ids are stable and correlatable.
@@ -83,22 +82,23 @@ impl ControlLinker {
     }
 }
 
-/// Assess `findings` against `controls`: link findings to control-ids and build a
-/// standard OSCAL assessment-results document. `at` is the assessment timestamp.
-pub fn assess(
-    controls: &[Control],
-    findings: &[Finding],
-    linker: &ControlLinker,
-    at: DateTime<Utc>,
-) -> AssessmentResultsDoc {
+/// Build a standard OSCAL assessment-results document from `findings`, using each
+/// finding's stamped `control_refs` for control linkage. EVERY non-false-positive
+/// finding is emitted as an observation — mapped findings additionally produce a
+/// per-control `not-satisfied` finding; **unmapped findings are reported as-is**
+/// (an observation carrying their CWE/tool/severity, with no control target) so
+/// nothing is lost. `at` is the assessment timestamp.
+pub fn assess(findings: &[Finding], at: DateTime<Utc>) -> AssessmentResultsDoc {
     let ts = at.to_rfc3339();
 
     let mut observations = Vec::new();
     let mut obs_by_control: HashMap<String, Vec<String>> = HashMap::new();
+    let mut mapped = 0usize;
+    let mut unmapped = 0usize;
+
     for finding in findings {
-        let targets = linker.controls_for(finding);
-        if targets.is_empty() {
-            continue;
+        if finding.status == FindingStatus::FalsePositive {
+            continue; // flagged tool false positive — excluded from the report
         }
         let obs_uuid = det_uuid(&format!("obs:{}", finding.fingerprint));
         let location = match (&finding.file_path, finding.line_number) {
@@ -106,58 +106,67 @@ pub fn assess(
             (Some(f), None) => Some(f.clone()),
             _ => None,
         };
+        let is_mapped = !finding.control_refs.is_empty();
+        if is_mapped {
+            mapped += 1;
+        } else {
+            unmapped += 1;
+        }
+        let mut props = vec![
+            ObsProp::new("tool", &finding.scanner),
+            ObsProp::new("severity", &finding.severity.to_string()),
+            ObsProp::new("mapping", if is_mapped { "mapped" } else { "unmapped" }),
+        ];
+        if let Some(cwe) = &finding.cwe {
+            props.push(ObsProp::new("cwe", cwe));
+        }
         observations.push(Observation {
             uuid: obs_uuid.clone(),
-            description: finding.title.clone(),
+            title: finding.title.clone(),
+            description: finding.description.clone(),
             methods: vec!["TEST".to_string()],
             collected: ts.clone(),
+            props,
             relevant_evidence: vec![RelevantEvidence {
                 href: location.map(|l| format!("file://{l}")),
                 description: format!("[{}] {}", finding.scanner, finding.title),
             }],
         });
-        for control_id in targets {
+        for control_id in &finding.control_refs {
             obs_by_control
-                .entry(control_id)
+                .entry(control_id.clone())
                 .or_default()
                 .push(obs_uuid.clone());
         }
     }
 
-    let titles: HashMap<&str, &str> = controls
-        .iter()
-        .map(|c| (c.id.as_str(), c.title.as_str()))
-        .collect();
     let mut hit_controls: Vec<&String> = obs_by_control.keys().collect();
     hit_controls.sort();
     let ar_findings: Vec<ArFinding> = hit_controls
-        .into_iter()
-        .map(|control_id| {
-            let title = titles.get(control_id.as_str()).copied().unwrap_or("");
-            ArFinding {
-                uuid: det_uuid(&format!("finding:{control_id}")),
-                title: format!("Findings affect {control_id}: {title}"),
-                target: FindingTarget {
-                    target_type: "statement-id".to_string(),
-                    target_id: format!("{control_id}_smt"),
-                    status: TargetStatus {
-                        state: "not-satisfied".to_string(),
-                    },
+        .iter()
+        .map(|control_id| ArFinding {
+            uuid: det_uuid(&format!("finding:{control_id}")),
+            title: format!("Findings affect {control_id}"),
+            target: FindingTarget {
+                target_type: "statement-id".to_string(),
+                target_id: format!("{control_id}_smt"),
+                status: TargetStatus {
+                    state: "not-satisfied".to_string(),
                 },
-                related_observations: obs_by_control[control_id]
-                    .iter()
-                    .map(|u| RelatedObservation {
-                        observation_uuid: u.clone(),
-                    })
-                    .collect(),
-            }
+            },
+            related_observations: obs_by_control[*control_id]
+                .iter()
+                .map(|u| RelatedObservation {
+                    observation_uuid: u.clone(),
+                })
+                .collect(),
         })
         .collect();
 
-    let include_controls = controls
+    let include_controls: Vec<SelectControlById> = hit_controls
         .iter()
         .map(|c| SelectControlById {
-            control_id: c.id.clone(),
+            control_id: (*c).clone(),
         })
         .collect();
 
@@ -165,9 +174,9 @@ pub fn assess(
         uuid: det_uuid("result:cra"),
         title: "Automated code-compliance assessment".to_string(),
         description: format!(
-            "{} finding-linked observation(s) across {} reviewed control(s)",
+            "{} observation(s): {mapped} control-linked, {unmapped} unmapped (as-is); {} control(s) affected",
             observations.len(),
-            controls.len()
+            include_controls.len()
         ),
         start: ts.clone(),
         reviewed_controls: ReviewedControls {
@@ -262,13 +271,33 @@ pub struct SelectControlById {
 #[derive(Debug, Clone, Serialize)]
 pub struct Observation {
     pub uuid: String,
+    pub title: String,
     pub description: String,
     pub methods: Vec<String>,
     pub collected: String,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub props: Vec<ObsProp>,
     #[serde(rename = "relevant-evidence", skip_serializing_if = "Vec::is_empty")]
     pub relevant_evidence: Vec<RelevantEvidence>,
 }
 
+/// A name/value observation property (cwe, tool, severity, mapping status). Lets an
+/// unmapped finding be reported fully as-is.
+#[derive(Debug, Clone, Serialize)]
+pub struct ObsProp {
+    pub name: String,
+    pub value: String,
+}
+
+impl ObsProp {
+    fn new(name: &str, value: &str) -> Self {
+        Self {
+            name: name.to_string(),
+            value: value.to_string(),
+        }
+    }
+}
+
 #[derive(Debug, Clone, Serialize)]
 pub struct RelevantEvidence {
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -310,20 +339,9 @@ pub struct RelatedObservation {
 mod tests {
     use super::*;
     use crate::models::finding::Severity;
-    use crate::models::onboarding::ComplianceFramework;
     use crate::models::scan::ScanType;
 
-    fn control(id: &str, title: &str) -> Control {
-        Control {
-            id: id.into(),
-            framework: ComplianceFramework::Cra,
-            title: title.into(),
-            text: String::new(),
-            source: None,
-        }
-    }
-
-    fn finding(fp: &str, cwe: Option<&str>) -> Finding {
+    fn finding(fp: &str, cwe: Option<&str>, refs: &[&str]) -> Finding {
         let mut f = Finding::new(
             "repo".into(),
             fp.into(),
@@ -336,6 +354,7 @@ mod tests {
         f.cwe = cwe.map(Into::into);
         f.file_path = Some("src/auth.rs".into());
         f.line_number = Some(42);
+        f.control_refs = refs.iter().map(|s| s.to_string()).collect();
         f
     }
 
@@ -346,57 +365,60 @@ mod tests {
     }
 
     #[test]
-    fn links_cwe_finding_to_control_not_satisfied() {
-        let controls = vec![
-            control("cra-ai-8", "No default passwords"),
-            control("cra-ai-13", "Crypto"),
-        ];
-        let findings = vec![finding("f1", Some("CWE-798"))];
-        let doc = assess(&controls, &findings, &ControlLinker::cra_seed(), at());
+    fn mapped_finding_becomes_control_finding() {
+        let doc = assess(&[finding("f1", Some("CWE-798"), &["cra-ai-8"])], at());
         let r = &doc.assessment_results.results[0];
         assert_eq!(r.observations.len(), 1);
         assert_eq!(r.findings.len(), 1);
         assert_eq!(r.findings[0].target.target_id, "cra-ai-8_smt");
         assert_eq!(r.findings[0].target.status.state, "not-satisfied");
-        assert_eq!(r.findings[0].related_observations.len(), 1);
         assert_eq!(
             r.reviewed_controls.control_selections[0]
                 .include_controls
                 .len(),
-            2
+            1
         );
     }
 
     #[test]
-    fn unlinked_finding_yields_no_control_finding() {
-        let controls = vec![control("cra-ai-8", "x")];
-        let findings = vec![finding("f1", Some("CWE-99999"))];
-        let doc = assess(&controls, &findings, &ControlLinker::cra_seed(), at());
+    fn unmapped_finding_is_reported_as_is() {
+        let doc = assess(&[finding("f1", Some("CWE-319"), &[])], at());
         let r = &doc.assessment_results.results[0];
-        assert!(r.observations.is_empty());
-        assert!(r.findings.is_empty());
+        assert_eq!(r.observations.len(), 1); // still emitted...
+        assert!(r.findings.is_empty()); // ...but no control finding
+        assert!(r.reviewed_controls.control_selections[0]
+            .include_controls
+            .is_empty());
+        let props: Vec<(&str, &str)> = r.observations[0]
+            .props
+            .iter()
+            .map(|p| (p.name.as_str(), p.value.as_str()))
+            .collect();
+        assert!(props.contains(&("mapping", "unmapped")));
+        assert!(props.contains(&("cwe", "CWE-319")));
     }
 
     #[test]
-    fn output_is_deterministic_and_valid_oscal() {
-        let controls = vec![control("cra-ai-8", "x")];
-        let findings = vec![finding("f1", Some("798"))];
-        let a = serde_json::to_string(&assess(
-            &controls,
-            &findings,
-            &ControlLinker::cra_seed(),
-            at(),
-        ))
-        .unwrap();
-        let b = serde_json::to_string(&assess(
-            &controls,
-            &findings,
-            &ControlLinker::cra_seed(),
-            at(),
-        ))
-        .unwrap();
+    fn false_positive_is_excluded() {
+        let mut f = finding("f1", Some("CWE-798"), &["cra-ai-8"]);
+        f.status = FindingStatus::FalsePositive;
+        let doc = assess(&[f], at());
+        assert!(doc.assessment_results.results[0].observations.is_empty());
+    }
+
+    #[test]
+    fn deterministic_and_valid_oscal() {
+        let mk = || {
+            vec![
+                finding("f1", Some("CWE-798"), &["cra-ai-8"]),
+                finding("f2", Some("CWE-319"), &[]),
+            ]
+        };
+        let a = serde_json::to_string(&assess(&mk(), at())).unwrap();
+        let b = serde_json::to_string(&assess(&mk(), at())).unwrap();
         assert_eq!(a, b);
         assert!(a.contains("\"oscal-version\":\"1.1.2\""));
         assert!(a.contains("\"not-satisfied\""));
+        assert!(a.contains("\"mapping\""));
     }
 }

compliance-mcp/src/server.rs

@@ -4,7 +4,7 @@ use rmcp::{
 
 use crate::auth::current_tenant_id;
 use crate::database::{Database, DatabasePool};
-use crate::tools::{dast, findings, pentest, sbom};
+use crate::tools::{dast, findings, oscal, pentest, sbom};
 
 pub struct ComplianceMcpServer {
     pool: DatabasePool,
@@ -68,6 +68,17 @@ impl ComplianceMcpServer {
         findings::findings_summary(&db, params).await
     }
 
+    #[tool(
+        description = "Emit an OSCAL 1.1 assessment-results document for a repo's findings (mapped findings target their compliance controls; unmapped findings are reported as-is)"
+    )]
+    async fn oscal_assessment(
+        &self,
+        Parameters(params): Parameters<oscal::OscalAssessmentParams>,
+    ) -> Result<CallToolResult, rmcp::ErrorData> {
+        let db = self.tenant_db()?;
+        oscal::oscal_assessment(&db, params).await
+    }
+
     // ── SBOM ──────────────────────────────────────────────
 
     #[tool(

compliance-mcp/src/tools/mod.rs

@@ -1,4 +1,5 @@
 pub mod dast;
 pub mod findings;
+pub mod oscal;
 pub mod pentest;
 pub mod sbom;

compliance-mcp/src/tools/oscal.rs

@@ -0,0 +1,51 @@
+//! OSCAL assessment MCP tool.
+//!
+//! Emits a standard OSCAL assessment-results document for a repo's findings —
+//! what breakpilot's scanner MCP client pulls. Mapped findings target their
+//! compliance controls (via the stamped `control_refs`); unmapped findings are
+//! reported as-is, so nothing is lost.
+
+use mongodb::bson::doc;
+use rmcp::{model::*, ErrorData as McpError};
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+use compliance_core::models::oscal_assessment::assess;
+use compliance_core::models::Finding;
+
+use crate::database::Database;
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct OscalAssessmentParams {
+    /// Repository / target id to assess.
+    pub repo_id: String,
+}
+
+pub async fn oscal_assessment(
+    db: &Database,
+    params: OscalAssessmentParams,
+) -> Result<CallToolResult, McpError> {
+    let mut cursor = db
+        .findings()
+        .find(doc! { "repo_id": &params.repo_id })
+        .await
+        .map_err(|e| McpError::internal_error(format!("DB error: {e}"), None))?;
+
+    let mut findings: Vec<Finding> = Vec::new();
+    while cursor
+        .advance()
+        .await
+        .map_err(|e| McpError::internal_error(format!("cursor error: {e}"), None))?
+    {
+        findings.push(
+            cursor
+                .deserialize_current()
+                .map_err(|e| McpError::internal_error(format!("deserialize error: {e}"), None))?,
+        );
+    }
+
+    let document = assess(&findings, chrono::Utc::now());
+    let json = serde_json::to_string_pretty(&document)
+        .map_err(|e| McpError::internal_error(format!("json error: {e}"), None))?;
+    Ok(CallToolResult::success(vec![Content::text(json)]))
+}

control-map/data/cra_control_map.json

@@ -5,51 +5,72 @@
     {
       "control": "cra-ai-1",
       "title": "Secure-by-Default-Konfiguration",
-      "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
-      "status": "needs_tooling"
+      "scans": [
+        {
+          "tool": "semgrep",
+          "scan_type": "sast",
+          "cwe": [],
+          "rules": [
+            "cra-ai-1-flask-debug-enabled",
+            "cra-ai-1-django-debug-true",
+            "cra-ai-1-tls-verify-disabled",
+            "cra-ai-1-cors-wildcard"
+          ]
+        }
+      ],
+      "note": null,
+      "status": "covered"
     },
     {
       "control": "cra-ai-2",
       "title": "Minimale Angriffsflaeche",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
-      "status": "needs_tooling"
+      "note": "design property (minimal attack surface) — not derivable from local code patterns; architecture/threat-model review",
+      "status": "not_code_checkable"
     },
     {
       "control": "cra-ai-3",
       "title": "Sichere Systemarchitektur",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
-      "status": "needs_tooling"
+      "note": "design property (secure system architecture) — architecture review, not statically code-checkable",
+      "status": "not_code_checkable"
     },
     {
       "control": "cra-ai-4",
       "title": "Least-Privilege-Prinzip",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
-      "status": "needs_tooling"
+      "note": "design property (least-privilege) — deployment/IAM & architecture review, not a local code pattern",
+      "status": "not_code_checkable"
     },
     {
       "control": "cra-ai-5",
       "title": "Manipulationsschutz",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
-      "status": "needs_tooling"
+      "note": "design property (tamper protection) — hardware/runtime & operational control, not statically code-checkable",
+      "status": "not_code_checkable"
     },
     {
       "control": "cra-ai-6",
       "title": "Integritaetspruefung",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
+      "note": "absence-based — no syntactic pattern; covered by the grounded surface check (retrieve surface + LLM judge), gated (BREAKPILOT_GROUNDED_CHECKS) pending live tuning",
       "status": "needs_tooling"
     },
     {
       "control": "cra-ai-7",
       "title": "Starke Authentifizierung",
-      "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
-      "status": "needs_tooling"
+      "scans": [
+        {
+          "tool": "semgrep",
+          "scan_type": "sast",
+          "cwe": [],
+          "rules": [
+            "cra-ai-7-weak-password-hash"
+          ]
+        }
+      ],
+      "note": null,
+      "status": "covered"
     },
     {
       "control": "cra-ai-8",
@@ -100,22 +121,32 @@
     {
       "control": "cra-ai-10",
       "title": "Sitzungsmanagement",
-      "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
-      "status": "needs_tooling"
+      "scans": [
+        {
+          "tool": "semgrep",
+          "scan_type": "sast",
+          "cwe": [],
+          "rules": [
+            "cra-ai-10-session-cookie-insecure",
+            "cra-ai-10-express-cookie-insecure"
+          ]
+        }
+      ],
+      "note": null,
+      "status": "covered"
     },
     {
       "control": "cra-ai-11",
       "title": "Brute-Force-Schutz",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
+      "note": "absence-based — no syntactic pattern; covered by the grounded surface check (retrieve surface + LLM judge), gated (BREAKPILOT_GROUNDED_CHECKS) pending live tuning",
       "status": "needs_tooling"
     },
     {
       "control": "cra-ai-12",
       "title": "Rollenbasierte Autorisierung",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
+      "note": "absence-based — no syntactic pattern; covered by the grounded surface check (retrieve surface + LLM judge), gated (BREAKPILOT_GROUNDED_CHECKS) pending live tuning",
       "status": "needs_tooling"
     },
     {
@@ -138,9 +169,19 @@
     {
       "control": "cra-ai-14",
       "title": "Speicher-Schutz (Data at Rest)",
-      "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
-      "status": "needs_tooling"
+      "scans": [
+        {
+          "tool": "semgrep",
+          "scan_type": "sast",
+          "cwe": [],
+          "rules": [
+            "cra-ai-14-python-weak-cipher",
+            "cra-ai-14-node-weak-cipher"
+          ]
+        }
+      ],
+      "note": null,
+      "status": "covered"
     },
     {
       "control": "cra-ai-15",
@@ -267,7 +308,7 @@
       "control": "cra-ai-24",
       "title": "Security-Logging",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
+      "note": "absence-based — no syntactic pattern; covered by the grounded surface check (retrieve surface + LLM judge), gated (BREAKPILOT_GROUNDED_CHECKS) pending live tuning",
       "status": "needs_tooling"
     },
     {
@@ -288,28 +329,28 @@
       "control": "cra-ai-27",
       "title": "Log-Integritaet und -Aufbewahrung",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
+      "note": "absence-based — no syntactic pattern; covered by the grounded surface check (retrieve surface + LLM judge), gated (BREAKPILOT_GROUNDED_CHECKS) pending live tuning",
       "status": "needs_tooling"
     },
     {
       "control": "cra-ai-28",
       "title": "Sichere Update-Mechanismen",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
+      "note": "absence-based — no syntactic pattern; covered by the grounded surface check (retrieve surface + LLM judge), gated (BREAKPILOT_GROUNDED_CHECKS) pending live tuning",
       "status": "needs_tooling"
     },
     {
       "control": "cra-ai-29",
       "title": "Update-Authentizitaet",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
+      "note": "absence-based — no syntactic pattern; covered by the grounded surface check (retrieve surface + LLM judge), gated (BREAKPILOT_GROUNDED_CHECKS) pending live tuning",
       "status": "needs_tooling"
     },
     {
       "control": "cra-ai-30",
       "title": "Update-Integritaet",
       "scans": [],
-      "note": "code-checkable but no off-the-shelf tool digs it out — author a detector (custom semgrep rule / check)",
+      "note": "absence-based — no syntactic pattern; covered by the grounded surface check (retrieve surface + LLM judge), gated (BREAKPILOT_GROUNDED_CHECKS) pending live tuning",
       "status": "needs_tooling"
     },
     {

control-map/src/lib.rs

@@ -66,6 +66,14 @@ pub struct ControlMap {
 
 const CRA_MAP_JSON: &str = include_str!("../data/cra_control_map.json");
 
+/// Whether an authored rule id `bound` matches a scanner's emitted rule id
+/// `actual`. semgrep prefixes local-rule check_ids with a path
+/// (`tmp.compliance-cra-semgrep.cra-ai-1-flask-debug-enabled`), so match the final
+/// id segment rather than requiring exact equality.
+fn rule_id_matches(bound: &str, actual: &str) -> bool {
+    actual == bound || actual.ends_with(&format!(".{bound}"))
+}
+
 impl ControlMap {
     /// Load the built-in CRA control map (the embedded, authored LUT).
     pub fn cra() -> Result<Self, MapError> {
@@ -80,12 +88,28 @@ impl ControlMap {
     /// Controls whose bindings include the given `tool` + `cwe` — used to attach a
     /// raw tool finding back to the control(s) it's evidence for.
     pub fn controls_for(&self, tool: &str, cwe: &str) -> Vec<&ControlEntry> {
+        self.controls_for_finding(tool, Some(cwe), None)
+    }
+
+    /// Controls a tool finding is evidence for, matched by CWE and/or the specific
+    /// rule id that fired. Off-the-shelf findings bind by CWE; our custom detectors
+    /// bind by rule id (precise — a broad CWE would over-attribute and then the
+    /// grounded judge could drop a genuine finding as a control false positive).
+    pub fn controls_for_finding(
+        &self,
+        tool: &str,
+        cwe: Option<&str>,
+        rule_id: Option<&str>,
+    ) -> Vec<&ControlEntry> {
         self.controls
             .iter()
             .filter(|c| {
-                c.scans
-                    .iter()
-                    .any(|s| s.tool == tool && s.cwe.iter().any(|w| w == cwe))
+                c.scans.iter().any(|s| {
+                    s.tool == tool
+                        && (cwe.is_some_and(|w| s.cwe.iter().any(|x| x == w))
+                            || rule_id
+                                .is_some_and(|r| s.rules.iter().any(|b| rule_id_matches(b, r))))
+                })
             })
             .collect()
     }
@@ -160,4 +184,67 @@ mod tests {
         assert!(s.needs_tooling > 0);
         assert!(s.not_code_checkable > 0);
     }
+
+    #[test]
+    fn rule_id_matching_handles_semgrep_path_prefix() {
+        let bound = "cra-ai-1-flask-debug-enabled";
+        assert!(rule_id_matches(bound, bound)); // exact
+        assert!(rule_id_matches(
+            bound,
+            "tmp.compliance-cra-semgrep.cra-ai-1-flask-debug-enabled"
+        )); // semgrep path prefix
+        assert!(!rule_id_matches(
+            bound,
+            "cra-ai-1-flask-debug-enabled-extra"
+        )); // not a suffix segment
+        assert!(!rule_id_matches(
+            bound,
+            "python.lang.security.exec-detected"
+        )); // unrelated
+    }
+
+    #[test]
+    fn custom_rule_finding_attaches_to_control_by_rule_id() {
+        let map = ControlMap::cra().unwrap();
+        // cra-ai-1 is now tool-covered by custom rules.
+        assert_eq!(map.coverage("cra-ai-1").unwrap().status, Coverage::Covered);
+        // A prefixed check_id still maps back to cra-ai-1 by rule id.
+        let hits =
+            map.controls_for_finding("semgrep", None, Some("tmp.x.cra-ai-1-tls-verify-disabled"));
+        assert!(hits.iter().any(|c| c.control == "cra-ai-1"));
+    }
+
+    #[test]
+    fn coverage_reflects_the_b_track_split() {
+        let s = ControlMap::cra().unwrap().summary();
+        // 9 already tool-covered + B1's 4 custom-semgrep controls.
+        assert_eq!(s.covered, 13);
+        // The 8 grounded surface controls stay needs_tooling until live-tuned.
+        assert_eq!(s.needs_tooling, 8);
+        // B3 marked the 4 pure-architectural controls not code-checkable.
+        assert_eq!(s.not_code_checkable, 19);
+    }
+
+    #[test]
+    fn architectural_controls_are_not_code_checkable() {
+        let map = ControlMap::cra().unwrap();
+        for id in ["cra-ai-2", "cra-ai-3", "cra-ai-4", "cra-ai-5"] {
+            let c = map.coverage(id).unwrap();
+            assert_eq!(c.status, Coverage::NotCodeCheckable, "{id}");
+            assert!(c.scans.is_empty(), "{id} should carry no scan bindings");
+        }
+    }
+
+    #[test]
+    fn custom_rule_controls_do_not_bind_by_broad_cwe() {
+        let map = ControlMap::cra().unwrap();
+        // cra-ai-1 rules emit CWE-489 in metadata, but the LUT binds by rule id
+        // only (cwe: []) — so a stray CWE-489 finding must NOT attach to it.
+        assert!(map.controls_for("semgrep", "CWE-489").is_empty());
+        // The CWE path for off-the-shelf findings is unchanged.
+        assert!(map
+            .controls_for("semgrep", "CWE-798")
+            .iter()
+            .any(|c| c.control == "cra-ai-8"));
+    }
 }