feat(agent): OscalControlsProvider — pull + snapshot breakpilot OSCAL catalog

Implements ControlsProvider by fetching GET /api/compliance/v1/oscal/catalog from
breakpilot-compliance, snapshotting the exact bytes to disk, and mapping the
catalog into the corpus controls the mapping engine consumes. Deterministic /
offline-capable: on fetch failure it falls back to the last snapshot so scans
still run (matters for on-prem/werkbank).

- controls/oscal_provider.rs: HTTP fetch (bearer-optional) + atomic snapshot +
  offline fallback + naive context ranking; ControlsProvider impl ("breakpilot-oscal")
- controls/mod.rs + lib.rs: register module
- 3 lib tests: url/path building, context ranking, snapshot round-trip + fallback

Not yet wired into startup — no ControlsProvider consumer exists until the
assessment-plan router lands. clippy -D warnings + fmt --all --check clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

compliance-agent/src/controls/mod.rs

@@ -0,0 +1,10 @@
+//! Controls corpus providers.
+//!
+//! Implementations of [`compliance_core::traits::ControlsProvider`] that supply
+//! the control corpus the mapping engine assesses findings against. Currently:
+//! [`OscalControlsProvider`], which pulls breakpilot-compliance's OSCAL catalog
+//! and snapshots it locally.
+
+mod oscal_provider;
+
+pub use oscal_provider::OscalControlsProvider;

compliance-agent/src/controls/oscal_provider.rs

@@ -0,0 +1,233 @@
+//! Pull + snapshot [`ControlsProvider`] backed by breakpilot-compliance's OSCAL
+//! catalog export.
+//!
+//! Fetches `GET {base}/api/compliance/v1/oscal/catalog?framework=<fw>`, snapshots
+//! the exact bytes to disk (so scans are deterministic and keep working offline /
+//! on-prem), and maps the catalog into the corpus controls the mapping engine
+//! consumes. The producer owns the catalog; we own the assessment — this is the
+//! ingest half of the loop.
+
+use std::path::PathBuf;
+
+use secrecy::{ExposeSecret, SecretString};
+
+use compliance_core::error::CoreError;
+use compliance_core::models::onboarding::ComplianceFramework;
+use compliance_core::models::oscal::OscalDocument;
+use compliance_core::traits::{Control, ControlQuery, ControlsProvider};
+
+/// A [`ControlsProvider`] that pulls the OSCAL catalog from breakpilot-compliance
+/// and snapshots it locally for deterministic / offline reuse.
+pub struct OscalControlsProvider {
+    http: reqwest::Client,
+    base_url: String,
+    token: Option<SecretString>,
+    snapshot_dir: PathBuf,
+}
+
+impl OscalControlsProvider {
+    /// Create a provider. `base_url` is the breakpilot-compliance root (e.g.
+    /// `http://backend-compliance:8002`); `snapshot_dir` is where catalog
+    /// snapshots are written so a later scan can reuse them without the network.
+    pub fn new(
+        http: reqwest::Client,
+        base_url: impl Into<String>,
+        token: Option<SecretString>,
+        snapshot_dir: impl Into<PathBuf>,
+    ) -> Self {
+        Self {
+            http,
+            base_url: base_url.into(),
+            token,
+            snapshot_dir: snapshot_dir.into(),
+        }
+    }
+
+    fn catalog_url(&self, framework: ComplianceFramework) -> String {
+        format!(
+            "{}/api/compliance/v1/oscal/catalog?framework={framework}",
+            self.base_url.trim_end_matches('/')
+        )
+    }
+
+    fn snapshot_path(&self, framework: ComplianceFramework) -> 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> {
+        let mut req = self.http.get(self.catalog_url(framework));
+        if let Some(token) = &self.token {
+            req = req.bearer_auth(token.expose_secret());
+        }
+        let resp = req
+            .send()
+            .await
+            .map_err(|e| CoreError::Http(e.to_string()))?;
+        if !resp.status().is_success() {
+            return Err(CoreError::Http(format!(
+                "catalog fetch for {framework} returned HTTP {}",
+                resp.status()
+            )));
+        }
+        resp.bytes()
+            .await
+            .map(|b| b.to_vec())
+            .map_err(|e| CoreError::Http(e.to_string()))
+    }
+
+    /// Write a catalog snapshot atomically (temp file + rename).
+    async fn write_snapshot(
+        &self,
+        framework: ComplianceFramework,
+        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");
+        tokio::fs::write(&tmp, raw).await?;
+        tokio::fs::rename(&tmp, &path).await?;
+        Ok(())
+    }
+
+    /// Read a previously written snapshot, if one exists.
+    async fn read_snapshot(
+        &self,
+        framework: ComplianceFramework,
+    ) -> 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),
+            Err(e) => Err(e.into()),
+        }
+    }
+
+    /// 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> {
+        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");
+                }
+                Ok(doc)
+            }
+            Err(fetch_err) => match self.read_snapshot(framework).await? {
+                Some(doc) => {
+                    tracing::warn!(
+                        %framework, error = %fetch_err,
+                        "OSCAL catalog fetch failed; falling back to snapshot"
+                    );
+                    Ok(doc)
+                }
+                None => Err(fetch_err),
+            },
+        }
+    }
+}
+
+/// Order controls whose title/text mention the query context first (stable), then
+/// truncate to the requested limit. Naive relevance — refined when the assessment
+/// layer lands.
+fn rank_and_truncate(mut controls: Vec<Control>, context: &str, limit: usize) -> Vec<Control> {
+    if !context.is_empty() {
+        let needle = context.to_lowercase();
+        controls.sort_by_key(|c| {
+            let hit =
+                c.title.to_lowercase().contains(&needle) || c.text.to_lowercase().contains(&needle);
+            u8::from(!hit)
+        });
+    }
+    controls.truncate(limit);
+    controls
+}
+
+impl ControlsProvider for OscalControlsProvider {
+    fn name(&self) -> &str {
+        "breakpilot-oscal"
+    }
+
+    async fn controls(&self, query: &ControlQuery<'_>) -> Result<Vec<Control>, CoreError> {
+        let mut out: Vec<Control> = Vec::new();
+        for &framework in query.frameworks {
+            match self.load(framework).await {
+                Ok(doc) => out.extend(doc.to_controls()),
+                Err(e) => {
+                    tracing::warn!(%framework, error = %e, "skipping framework: catalog unavailable")
+                }
+            }
+        }
+        Ok(rank_and_truncate(out, query.context, query.limit))
+    }
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used)]
+mod tests {
+    use super::*;
+
+    const MINI_CATALOG: &str = r#"{"catalog":{"uuid":"u","metadata":{"title":"T",
+      "version":"1.0.0","oscal-version":"1.1.2","props":[{"name":"framework","value":"cra"}]},
+      "groups":[{"id":"g","title":"G","controls":[{"id":"cra-ai-1","title":"MFA",
+      "props":[],"parts":[{"name":"statement","prose":"require mfa"}]}]}]}}"#;
+
+    fn provider(dir: &std::path::Path) -> OscalControlsProvider {
+        OscalControlsProvider::new(reqwest::Client::new(), "http://unused/", None, dir)
+    }
+
+    #[test]
+    fn builds_catalog_url_and_snapshot_path() {
+        let p = provider(std::path::Path::new("/snap"));
+        assert_eq!(
+            p.catalog_url(ComplianceFramework::Cra),
+            "http://unused/api/compliance/v1/oscal/catalog?framework=cra"
+        );
+        assert_eq!(
+            p.snapshot_path(ComplianceFramework::Cra),
+            std::path::Path::new("/snap/oscal-catalog-cra.json")
+        );
+    }
+
+    #[test]
+    fn ranks_context_hits_first_then_truncates() {
+        let mk = |id: &str, title: &str| Control {
+            id: id.into(),
+            framework: ComplianceFramework::Cra,
+            title: title.into(),
+            text: String::new(),
+            source: None,
+        };
+        let controls = vec![
+            mk("a", "logging policy"),
+            mk("b", "multi-factor auth"),
+            mk("c", "backup"),
+        ];
+        let ranked = rank_and_truncate(controls, "auth", 2);
+        assert_eq!(ranked.len(), 2);
+        assert_eq!(ranked[0].id, "b"); // the "auth" hit floats to the top
+    }
+
+    #[tokio::test]
+    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())
+            .await
+            .unwrap();
+        let doc = p
+            .read_snapshot(ComplianceFramework::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/lib.rs

@@ -4,6 +4,7 @@ pub mod agent;
 pub mod api;
 pub mod classify;
 pub mod config;
+pub mod controls;
 pub mod database;
 pub mod error;
 pub mod ingest;

compliance-core/src/models/mod.rs

@@ -10,6 +10,7 @@ pub mod mcp;
 pub mod mcp_token;
 pub mod notification;
 pub mod onboarding;
+pub mod oscal;
 pub mod pentest;
 pub mod repository;
 pub mod sbom;
@@ -39,6 +40,7 @@ pub use onboarding::{
     GitArtifactConfig, IssueTrackerConfig, OnboardedTarget, PlcArtifactConfig, PlcFormat,
     TargetScanConfig, TargetType, TargetTypeCandidate, WebArtifactConfig,
 };
+pub use oscal::OscalDocument;
 pub use pentest::{
     AttackChainNode, AttackNodeStatus, AuthMode, CodeContextHint, Environment, IdentityProvider,
     PentestAuthConfig, PentestConfig, PentestEvent, PentestMessage, PentestSession, PentestStats,

compliance-core/src/models/oscal.rs

@@ -0,0 +1,250 @@
+//! OSCAL 1.1 catalog types + mapping into the controls corpus.
+//!
+//! Deserialises the OSCAL catalog served by breakpilot-compliance
+//! (`GET /api/compliance/v1/oscal/catalog`) and maps its controls into the
+//! framework-agnostic [`crate::traits::Control`] that the mapping engine consumes.
+//! Only the fields we use are modelled; unknown OSCAL fields are ignored so the
+//! producer can add detail without breaking us.
+//!
+//! Scope boundary: this is the *catalog* (domain content). Assessment objectives
+//! and scanner routing live in our assessment layer, not here — see
+//! [`crate::traits::ControlsProvider`].
+
+use serde::Deserialize;
+
+use crate::models::onboarding::ComplianceFramework;
+use crate::traits::Control as CorpusControl;
+
+/// A parsed OSCAL catalog document (`{"catalog": {...}}`).
+#[derive(Debug, Clone, Deserialize)]
+pub struct OscalDocument {
+    pub catalog: Catalog,
+}
+
+/// An OSCAL catalog: metadata + a tree of control groups.
+#[derive(Debug, Clone, Deserialize)]
+pub struct Catalog {
+    pub uuid: String,
+    pub metadata: Metadata,
+    #[serde(default)]
+    pub groups: Vec<Group>,
+    #[serde(rename = "back-matter", default)]
+    pub back_matter: Option<BackMatter>,
+}
+
+/// Catalog metadata (title/version + provenance props).
+#[derive(Debug, Clone, Deserialize)]
+pub struct Metadata {
+    pub title: String,
+    pub version: String,
+    #[serde(rename = "oscal-version")]
+    pub oscal_version: String,
+    #[serde(default)]
+    pub props: Vec<Prop>,
+}
+
+/// A name/value property, optionally namespaced.
+#[derive(Debug, Clone, Deserialize)]
+pub struct Prop {
+    pub name: String,
+    pub value: String,
+    #[serde(default)]
+    pub ns: Option<String>,
+}
+
+/// A control group (may nest sub-groups and controls).
+#[derive(Debug, Clone, Deserialize)]
+pub struct Group {
+    #[serde(default)]
+    pub id: String,
+    #[serde(default)]
+    pub title: String,
+    #[serde(default)]
+    pub controls: Vec<Control>,
+    #[serde(default)]
+    pub groups: Vec<Group>,
+}
+
+/// An OSCAL control (may nest enhancement controls).
+#[derive(Debug, Clone, Deserialize)]
+pub struct Control {
+    pub id: String,
+    #[serde(default)]
+    pub title: String,
+    #[serde(default)]
+    pub props: Vec<Prop>,
+    #[serde(default)]
+    pub parts: Vec<Part>,
+    #[serde(default)]
+    pub links: Vec<Link>,
+    #[serde(default)]
+    pub controls: Vec<Control>,
+}
+
+/// A control part (e.g. the `statement`), may nest sub-parts.
+#[derive(Debug, Clone, Deserialize)]
+pub struct Part {
+    #[serde(default)]
+    pub name: String,
+    #[serde(default)]
+    pub prose: Option<String>,
+    #[serde(default)]
+    pub parts: Vec<Part>,
+}
+
+/// A link, e.g. a `reference` to a back-matter resource.
+#[derive(Debug, Clone, Deserialize)]
+pub struct Link {
+    pub href: String,
+    #[serde(default)]
+    pub rel: Option<String>,
+}
+
+/// Back-matter holding referenced resources (e.g. the CRA measures).
+#[derive(Debug, Clone, Deserialize)]
+pub struct BackMatter {
+    #[serde(default)]
+    pub resources: Vec<Resource>,
+}
+
+/// A back-matter resource referenced by control links.
+#[derive(Debug, Clone, Deserialize)]
+pub struct Resource {
+    pub uuid: String,
+    #[serde(default)]
+    pub title: Option<String>,
+    #[serde(default)]
+    pub description: Option<String>,
+}
+
+impl Metadata {
+    /// First prop value with the given name.
+    pub fn prop(&self, name: &str) -> Option<&str> {
+        self.props
+            .iter()
+            .find(|p| p.name == name)
+            .map(|p| p.value.as_str())
+    }
+}
+
+impl Control {
+    /// First prop value with the given name.
+    pub fn prop(&self, name: &str) -> Option<&str> {
+        self.props
+            .iter()
+            .find(|p| p.name == name)
+            .map(|p| p.value.as_str())
+    }
+
+    /// The control's `statement` prose, if present.
+    pub fn statement(&self) -> Option<&str> {
+        self.parts
+            .iter()
+            .find(|p| p.name == "statement")
+            .and_then(|p| p.prose.as_deref())
+    }
+}
+
+impl OscalDocument {
+    /// The framework this catalog declares (`metadata.props[name="framework"]`).
+    pub fn framework(&self) -> Option<ComplianceFramework> {
+        framework_from_str(self.catalog.metadata.prop("framework")?)
+    }
+
+    /// The catalog `content-hash` prop — consumers pin this to snapshot/detect drift.
+    pub fn content_hash(&self) -> Option<&str> {
+        self.catalog.metadata.prop("content-hash")
+    }
+
+    /// Flatten the catalog into the corpus controls the mapping engine consumes.
+    pub fn to_controls(&self) -> Vec<CorpusControl> {
+        let framework = self.framework().unwrap_or(ComplianceFramework::Cra);
+        let source_label = self.catalog.metadata.title.as_str();
+        let mut out = Vec::new();
+        for group in &self.catalog.groups {
+            collect_group(group, framework, source_label, &mut out);
+        }
+        out
+    }
+}
+
+/// Map an OSCAL framework token (e.g. `"cra"`) to [`ComplianceFramework`] via its
+/// serde snake_case representation.
+fn framework_from_str(raw: &str) -> Option<ComplianceFramework> {
+    serde_json::from_value(serde_json::Value::String(raw.to_string())).ok()
+}
+
+fn collect_group(
+    group: &Group,
+    framework: ComplianceFramework,
+    source_label: &str,
+    out: &mut Vec<CorpusControl>,
+) {
+    for control in &group.controls {
+        collect_control(control, framework, source_label, out);
+    }
+    for sub in &group.groups {
+        collect_group(sub, framework, source_label, out);
+    }
+}
+
+fn collect_control(
+    control: &Control,
+    framework: ComplianceFramework,
+    source_label: &str,
+    out: &mut Vec<CorpusControl>,
+) {
+    let source = match control.prop("annex-anchor") {
+        Some(anchor) => Some(format!("{source_label} · {anchor}")),
+        None => Some(source_label.to_string()),
+    };
+    out.push(CorpusControl {
+        id: control.id.clone(),
+        framework,
+        title: control.title.clone(),
+        text: control.statement().unwrap_or_default().to_string(),
+        source,
+    });
+    for enhancement in &control.controls {
+        collect_control(enhancement, framework, source_label, out);
+    }
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used)]
+mod tests {
+    use super::*;
+
+    const CATALOG: &str = include_str!("../../tests/data/cra_catalog.json");
+
+    fn parse() -> OscalDocument {
+        serde_json::from_str(CATALOG).unwrap()
+    }
+
+    #[test]
+    fn parses_full_catalog() {
+        let doc = parse();
+        assert_eq!(doc.catalog.metadata.oscal_version, "1.1.2");
+        assert!(!doc.catalog.groups.is_empty());
+        assert!(doc.catalog.back_matter.is_some());
+    }
+
+    #[test]
+    fn maps_all_controls_to_corpus() {
+        let doc = parse();
+        let controls = doc.to_controls();
+        assert_eq!(controls.len(), 40);
+        assert_eq!(doc.framework(), Some(ComplianceFramework::Cra));
+
+        let c8 = controls.iter().find(|c| c.id == "cra-ai-8").unwrap();
+        assert_eq!(c8.framework, ComplianceFramework::Cra);
+        assert!(!c8.title.is_empty());
+        assert!(!c8.text.is_empty(), "statement prose should map into text");
+        assert!(c8.source.as_deref().unwrap_or_default().contains("Annex I"));
+    }
+
+    #[test]
+    fn exposes_content_hash_for_snapshotting() {
+        assert_eq!(parse().content_hash().map(str::len), Some(64));
+    }
+}