scanners+diff: surface labels/annotations and promote opt-in provenance (#20) (#21)

Layer 1 (additive): docker, kubernetes manifest, and helm chart scanners
now emit `labels` / `annotations` from the parsed file in `Resource.extra`
verbatim. Compose accepts both list-form (`["k=v"]`) and map-form labels;
non-string scalars (numbers, bools) are coerced to strings so unquoted
YAML values still surface instead of being silently dropped.

Layer 2 (opt-in): a new `scan { provenance_labels = [...],
provenance_annotations = [...] }` block in the Compositfile lifts
configured keys to a structured `provenance` block on the resource. The
first matching label provides `source_kind`, the first matching
annotation provides `source_ref`, and every match goes into `raw`. The
diff reporter appends `(source: <kind> <ref>)` to per-resource violation
messages so drift attributable to an upstream spec generator points at
the spec rather than the generated artefact.

Resolution runs as a post-scan pass in `registry::run_all` next to the
existing RFC-006 / RFC-007 passes, so individual scanners stay oblivious
to the feature. Shared `yaml_string_map_to_json` helper extracted to
`core::yaml_utils` to avoid duplicating coercion rules between scanners.

Closes #20

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 7schmiede

src/commands/diff.rs

@@ -670,8 +670,10 @@ fn check_resources(governance: &Governance, report: &Report) -> ViolationCategor
                                 severity: Severity::Error,
                                 rule: "image_not_allowed".to_string(),
                                 message: format!(
-                                    "Image \"{}\" not in allowed list for {}",
-                                    image, rule.resource_type
+                                    "Image \"{}\" not in allowed list for {}{}",
+                                    image,
+                                    rule.resource_type,
+                                    provenance_suffix(r)
                                 ),
                                 details: r.path.clone(),
                                 expected: Some(rule.allowed_images.join("\n")),
@@ -693,8 +695,10 @@ fn check_resources(governance: &Governance, report: &Report) -> ViolationCategor
                                 severity: Severity::Error,
                                 rule: "resource_subtype_not_allowed".to_string(),
                                 message: format!(
-                                    "Resource type \"{}\" not in allowed types for {}",
-                                    rt, rule.resource_type
+                                    "Resource type \"{}\" not in allowed types for {}{}",
+                                    rt,
+                                    rule.resource_type,
+                                    provenance_suffix(r)
                                 ),
                                 details: r.path.clone(),
                                 expected: Some(rule.allowed_types.join("\n")),
@@ -854,8 +858,9 @@ fn check_resolution(report: &Report, scan: &ScanSettings) -> ViolationCategory {
                 severity: Severity::Info,
                 rule: "vault_unsupported".to_string(),
                 message: format!(
-                    "Template {} is ansible-vault encrypted and was not rendered",
-                    r.path.as_deref().unwrap_or("-")
+                    "Template {} is ansible-vault encrypted and was not rendered{}",
+                    r.path.as_deref().unwrap_or("-"),
+                    provenance_suffix(r)
                 ),
                 details: Some(
                     "composit does not decrypt vault files. Role constraints on \
@@ -1145,6 +1150,25 @@ fn string_list(items: &[String]) -> String {
     items.join("\n")
 }
 
+/// Issue #20: when a resource carries a `provenance` block (set by the
+/// post-scan `apply_provenance` pass), append `(source: <kind> <ref>)` to
+/// the violation message so reports point operators to the upstream spec
+/// rather than the generated artefact. Empty string when no provenance
+/// is present, so callers can append unconditionally.
+fn provenance_suffix(r: &Resource) -> String {
+    let Some(prov) = r.extra.get("provenance").and_then(|v| v.as_object()) else {
+        return String::new();
+    };
+    let kind = prov.get("source_kind").and_then(|v| v.as_str());
+    let source_ref = prov.get("source_ref").and_then(|v| v.as_str());
+    match (kind, source_ref) {
+        (Some(k), Some(rf)) => format!(" (source: {} {})", k, rf),
+        (Some(k), None) => format!(" (source: {})", k),
+        (None, Some(rf)) => format!(" (source: {})", rf),
+        (None, None) => String::new(),
+    }
+}
+
 /// Human-readable summary of which resources a role matched. Used in the
 /// `details` field of role violations so the HTML diff shows authors
 /// *which* services tripped the rule, not just how many.
@@ -1248,8 +1272,10 @@ fn check_role_constraints(
                         severity: Severity::Error,
                         rule: "role_image_not_pinned".to_string(),
                         message: format!(
-                            "Role \"{}\": image \"{}\" not in pinned list",
-                            role.name, image
+                            "Role \"{}\": image \"{}\" not in pinned list{}",
+                            role.name,
+                            image,
+                            provenance_suffix(r)
                         ),
                         details: Some(detail.clone()),
                         expected: Some(string_list(&role.image_pin)),
@@ -1270,8 +1296,10 @@ fn check_role_constraints(
                         severity: Severity::Error,
                         rule: "role_image_prefix_mismatch".to_string(),
                         message: format!(
-                            "Role \"{}\": image \"{}\" does not match any allowed prefix",
-                            role.name, image
+                            "Role \"{}\": image \"{}\" does not match any allowed prefix{}",
+                            role.name,
+                            image,
+                            provenance_suffix(r)
                         ),
                         details: Some(detail.clone()),
                         expected: Some(string_list(&role.image_prefix)),
@@ -1297,8 +1325,11 @@ fn check_role_constraints(
                     severity: Severity::Error,
                     rule: "role_port_missing".to_string(),
                     message: format!(
-                        "Role \"{}\": required ports {:?} not exposed (missing {:?})",
-                        role.name, role.must_expose, missing
+                        "Role \"{}\": required ports {:?} not exposed (missing {:?}){}",
+                        role.name,
+                        role.must_expose,
+                        missing,
+                        provenance_suffix(r)
                     ),
                     details: Some(detail.clone()),
                     expected: Some(
@@ -1336,13 +1367,14 @@ fn check_role_constraints(
                     severity: Severity::Error,
                     rule: "role_network_missing".to_string(),
                     message: format!(
-                        "Role \"{}\": not attached to required networks ({})",
+                        "Role \"{}\": not attached to required networks ({}){}",
                         role.name,
                         missing
                             .iter()
                             .map(|s| s.as_str())
                             .collect::<Vec<_>>()
-                            .join(", ")
+                            .join(", "),
+                        provenance_suffix(r)
                     ),
                     details: Some(detail.clone()),
                     expected: Some(string_list(&role.must_attach_to)),
@@ -1371,13 +1403,14 @@ fn check_role_constraints(
                         severity: Severity::Error,
                         rule: "role_env_var_missing".to_string(),
                         message: format!(
-                            "Role \"{}\": env vars not set: {}",
+                            "Role \"{}\": env vars not set: {}{}",
                             role.name,
                             missing
                                 .iter()
                                 .map(|s| s.as_str())
                                 .collect::<Vec<_>>()
-                                .join(", ")
+                                .join(", "),
+                            provenance_suffix(r)
                         ),
                         details: Some(detail.clone()),
                         expected: Some(string_list(&role.must_set_env)),
@@ -1402,13 +1435,14 @@ fn check_role_constraints(
                         severity: Severity::Error,
                         rule: "role_env_var_forbidden".to_string(),
                         message: format!(
-                            "Role \"{}\": forbidden env vars present: {}",
+                            "Role \"{}\": forbidden env vars present: {}{}",
                             role.name,
                             present
                                 .iter()
                                 .map(|s| s.as_str())
                                 .collect::<Vec<_>>()
-                                .join(", ")
+                                .join(", "),
+                            provenance_suffix(r)
                         ),
                         details: Some(detail.clone()),
                         expected: Some(string_list(&role.forbidden_env)),
@@ -1478,8 +1512,9 @@ fn check_role_constraints(
                             severity: Severity::Error,
                             rule: "template_value_mismatch".to_string(),
                             message: format!(
-                                "Role \"{}\": template rendering ({}) key \"{}\" does not satisfy \"{}\"",
-                                role.name, src_tag, key, expected_glob
+                                "Role \"{}\": template rendering ({}) key \"{}\" does not satisfy \"{}\"{}",
+                                role.name, src_tag, key, expected_glob,
+                                provenance_suffix(r)
                             ),
                             details: Some(format!("{} @ {}", role_tag, path)),
                             expected: Some(format!("{} = {}", key, expected_glob)),

src/core/compositfile.rs

@@ -63,6 +63,11 @@ fn parse_scan_block(block: &hcl::Block) -> Result<ScanSettings> {
     let exclude_paths = get_string_array_attr(&block.body, "exclude");
     let resolvable = get_optional_string_array_attr(&block.body, "resolvable");
     let redact = get_string_array_attr(&block.body, "redact");
+    // Issue #20: opt-in provenance promotion. Each list names label /
+    // annotation keys whose values get lifted to a structured `provenance`
+    // block on every resource that carries them.
+    let provenance_labels = get_string_array_attr(&block.body, "provenance_labels");
+    let provenance_annotations = get_string_array_attr(&block.body, "provenance_annotations");
 
     let mut extra_patterns = Vec::new();
     for inner in block.body.blocks() {
@@ -139,6 +144,8 @@ fn parse_scan_block(block: &hcl::Block) -> Result<ScanSettings> {
         resolvable,
         redact,
         ansible,
+        provenance_labels,
+        provenance_annotations,
     })
 }
 
@@ -942,6 +949,53 @@ mod tests {
         assert!(gov.scan.is_scanner_enabled("docker"));
     }
 
+    #[test]
+    fn test_scan_block_reads_provenance_attributes() {
+        // Issue #20: provenance_labels and provenance_annotations are
+        // string arrays inside `scan { }`. Both default to empty when
+        // absent, which keeps the feature off for users who don't opt in.
+        let gov = parse_hcl(
+            r#"
+            workspace "test" {
+              scan {
+                provenance_labels      = ["app.kubernetes.io/managed-by", "vendor/source"]
+                provenance_annotations = ["vendor/workload-name"]
+              }
+            }
+            "#,
+        )
+        .unwrap();
+
+        assert_eq!(
+            gov.scan.provenance_labels,
+            vec![
+                "app.kubernetes.io/managed-by".to_string(),
+                "vendor/source".to_string(),
+            ]
+        );
+        assert_eq!(
+            gov.scan.provenance_annotations,
+            vec!["vendor/workload-name".to_string()]
+        );
+    }
+
+    #[test]
+    fn test_scan_block_omitting_provenance_yields_empty_lists() {
+        // Without the new attributes the lists must default to empty —
+        // that's how `apply_provenance` short-circuits as a no-op for
+        // users who haven't opted in.
+        let gov = parse_hcl(
+            r#"
+            workspace "test" {
+              scan {}
+            }
+            "#,
+        )
+        .unwrap();
+        assert!(gov.scan.provenance_labels.is_empty());
+        assert!(gov.scan.provenance_annotations.is_empty());
+    }
+
     #[test]
     fn test_parse_role_block_with_matcher_and_constraints() {
         let gov = parse_hcl(

src/core/governance.rs

@@ -61,6 +61,21 @@ pub struct ScanSettings {
     /// into rendering.
     #[serde(default)]
     pub ansible: AnsibleSettings,
+
+    /// Issue #20: label keys whose values get promoted to a structured
+    /// `provenance` block on the resource. The first key from this list
+    /// that matches an actual label provides `provenance.source_kind`;
+    /// every match is also recorded under `provenance.raw`. Empty default
+    /// means provenance promotion is off (labels still surface verbatim
+    /// via Layer 1).
+    #[serde(default)]
+    pub provenance_labels: Vec<String>,
+
+    /// Issue #20: annotation counterpart to `provenance_labels`. The first
+    /// matching annotation provides `provenance.source_ref`. Empty default
+    /// means provenance promotion is off for annotations.
+    #[serde(default)]
+    pub provenance_annotations: Vec<String>,
 }
 
 /// RFC 007: Ansible rendering knobs.

src/core/mod.rs

@@ -2,8 +2,10 @@ pub mod attribution;
 pub mod compositfile;
 pub mod governance;
 pub mod opa_eval;
+pub mod provenance;
 pub mod registry;
 pub mod rego;
 pub mod report;
 pub mod scanner;
 pub mod types;
+pub mod yaml_utils;