@cdxgen/cdxgen 13.0.1 → 13.2.0

package/data/rules/cargo-rust.yaml

@@ -0,0 +1,132 @@
+# Cargo and Rust Rules
+# Categories: cargo-security, cargo-compliance
+# Evaluates the cdx:cargo:* properties cdxgen emits for Rust projects, with the
+# native-library rules keyed on the `links` evidence that only `--deep` can
+# produce.
+
+- id: CARGO-SEC-001
+  name: "Statically linked native library has no resolvable version"
+  description: "A -sys crate compiles a C library into the artifact, but nothing in the build states which version, so no advisory can be matched against it"
+  severity: medium
+  category: cargo-security
+  dry-run-support: full
+  condition: |
+    components[
+      $prop($, 'cdx:cargo:linkage') = 'static'
+      and ($not($exists(version)) or version = '')
+    ]
+  location: |
+    { "bomRef": $."bom-ref", "purl": purl }
+  message: "Native library '{{ name }}' is compiled into the artifact by '{{ $prop($, 'cdx:cargo:providedBy') }}' with no resolvable version"
+  mitigation: "Pin the library version explicitly, or build against a crate release whose version encodes the upstream version as build metadata. Until the version is known, the bundled library has to be reviewed by hand: a vulnerability scanner matching on purl cannot see it"
+  evidence: |
+    {
+      "nativeLibrary": $prop($, 'cdx:cargo:nativeLibrary'),
+      "providedBy": $prop($, 'cdx:cargo:providedBy'),
+      "linkageEvidence": $prop($, 'cdx:cargo:linkageEvidence'),
+      "versionCandidates": $prop($, 'cdx:cargo:upstreamVersionCandidates')
+    }
+
+- id: CARGO-SEC-002
+  name: "Native C library is vendored into the Rust artifact"
+  description: "The resolver enabled a vendoring feature, so the library's own advisories and license obligations travel with the binary rather than with the host"
+  severity: low
+  category: cargo-security
+  dry-run-support: full
+  condition: |
+    components[
+      $prop($, 'cdx:cargo:linkage') = 'static'
+      and $exists(version)
+      and version != ''
+    ]
+  location: |
+    { "bomRef": $."bom-ref", "purl": purl }
+  message: "Native library '{{ name }}' version '{{ version }}' is compiled into the artifact by '{{ $prop($, 'cdx:cargo:providedBy') }}'"
+  mitigation: "Track this library's advisories directly; the cargo dependency graph will not report them. Confirm that updating the -sys crate is enough to pick up a library fix, and that the vendored build is rebuilt when the library is patched"
+  evidence: |
+    {
+      "nativeLibrary": $prop($, 'cdx:cargo:nativeLibrary'),
+      "providedBy": $prop($, 'cdx:cargo:providedBy'),
+      "linkageEvidence": $prop($, 'cdx:cargo:linkageEvidence'),
+      "upstreamVersionSource": $prop($, 'cdx:cargo:upstreamVersionSource')
+    }
+
+- id: CARGO-SEC-003
+  name: "Rust artifact links a native library the environment must provide"
+  description: "A -sys crate links a C library dynamically, so the deployed artifact depends on a library version this BOM cannot state"
+  severity: low
+  category: cargo-security
+  dry-run-support: full
+  condition: |
+    components[$prop($, 'cdx:cargo:linkage') = 'dynamic']
+  location: |
+    { "bomRef": $."bom-ref", "purl": purl }
+  message: "Native library '{{ name }}' is linked dynamically by '{{ $prop($, 'cdx:cargo:providedBy') }}' and has to be present and patched on the deployment host"
+  mitigation: "Record the library version the deployment environment provides, through a container or host inventory. Where the artifact must be self-contained, enable the crate's vendoring feature so the version becomes part of this BOM"
+  evidence: |
+    {
+      "nativeLibrary": $prop($, 'cdx:cargo:nativeLibrary'),
+      "providedBy": $prop($, 'cdx:cargo:providedBy')
+    }
+
+- id: CARGO-COMP-001
+  name: "Vendored library version is ambiguous between shipped variants"
+  description: "The crate ships several variants of the library and the enabled features do not say which one is compiled, so the version was left unstated"
+  severity: medium
+  category: cargo-compliance
+  dry-run-support: full
+  condition: |
+    components[
+      $prop($, 'cdx:cargo:upstreamVersionCandidates') != null
+    ]
+  location: |
+    { "bomRef": $."bom-ref", "purl": purl }
+  message: "Native library '{{ name }}' could be any of '{{ $prop($, 'cdx:cargo:upstreamVersionCandidates') }}' depending on which variant '{{ $prop($, 'cdx:cargo:providedBy') }}' compiles"
+  mitigation: "Read the crate's build script to see which variant the enabled features select, then record the version. The variants can carry different licenses, so a license review cannot be completed from this BOM alone"
+  evidence: |
+    {
+      "versionCandidates": $prop($, 'cdx:cargo:upstreamVersionCandidates'),
+      "providedBy": $prop($, 'cdx:cargo:providedBy'),
+      "resolvedFeatures": $prop($, 'cdx:cargo:resolvedFeatures')
+    }
+
+- id: CARGO-SEC-004
+  name: "Crate resolved from a registry other than crates.io"
+  description: "A crate came from an alternative or private registry, which can publish any name and version, including ones that also exist on crates.io"
+  severity: medium
+  category: cargo-security
+  dry-run-support: full
+  condition: |
+    $append(components, formulation.components)[
+      $prop($, 'cdx:cargo:alternateRegistry') = 'true'
+    ]
+  location: |
+    { "bomRef": $."bom-ref", "purl": purl }
+  message: "Crate '{{ name }}' was resolved from '{{ $prop($, 'cdx:cargo:sourceUrl') }}' rather than crates.io"
+  mitigation: "Confirm the registry is one your organisation operates and that the crate name is not also claimed on crates.io, which would let a resolver change pull a different crate. Verify the registry authenticates publishers and serves checksums"
+  evidence: |
+    {
+      "sourceKind": $prop($, 'cdx:cargo:sourceKind'),
+      "sourceUrl": $prop($, 'cdx:cargo:sourceUrl')
+    }
+
+- id: CARGO-SEC-005
+  name: "Procedural macro crate executes during compilation"
+  description: "A proc-macro crate runs arbitrary code in the compiler on the build host, before any of the project's own code runs"
+  severity: low
+  category: cargo-security
+  dry-run-support: full
+  condition: |
+    $append(components, formulation.components)[
+      $prop($, 'cdx:cargo:procMacro') = 'true'
+    ]
+  location: |
+    { "bomRef": $."bom-ref", "purl": purl }
+  message: "Crate '{{ name }}' is a procedural macro and runs in the compiler on every build"
+  mitigation: "Treat this crate's compromise as equivalent to build-host compromise. Review its publisher and release history, pin it, and confirm the build host has no credentials a compile-time macro should not reach"
+  evidence: |
+    {
+      "dependencyKind": $prop($, 'cdx:cargo:dependencyKind'),
+      "publisher": $prop($, 'cdx:cargo:publisher'),
+      "resolvedFeatures": $prop($, 'cdx:cargo:resolvedFeatures')
+    }

package/data/rules/mcp-servers.yaml

@@ -386,3 +386,125 @@
       "configuredServiceCount": $prop($, 'cdx:mcp:configuredServiceCount'),
       "configuredServiceNames": $prop($, 'cdx:mcp:configuredServiceNames')
     }
+
+- id: MCP-009
+  name: "MCP configuration relies on deprecated protocol features"
+  description: "The MCP 2026-07-28 specification deprecates the legacy HTTP+SSE transport, dynamic client registration, sampling, logging, and roots. Configurations that still depend on these features need a migration plan before the deprecation window closes."
+  severity: medium
+  category: mcp-server
+  dry-run-support: full
+  standards:
+    owasp-ai-top-10:
+      - "LLM05: Supply Chain Vulnerabilities"
+      - "LLM03:2025 Supply Chain"
+    owasp-agentic-top-10-2026:
+      - "Agentic Supply Chain"
+    eu-ai-act:
+      - "Technical documentation and traceability"
+    eu-cra:
+      - "Technical documentation for software components"
+    nist-ai-rmf:
+      - "Govern"
+      - "Map"
+    nist-ssdf:
+      - "Plan migration away from deprecated protocol features"
+  condition: |
+    $auditServices($)[
+      $nullSafeProp($, 'cdx:mcp:deprecatedFeatures') != ''
+    ]
+  location: |
+    {
+      "bomRef": $."bom-ref",
+      "file": $prop($, 'internal:SrcFile')
+    }
+  message: "MCP service '{{ name }}' uses deprecated protocol features"
+  mitigation: "Migrate off legacy SSE transport, dynamic client registration, sampling, logging, and roots to the MCP 2026-07-28 replacements within the deprecation window."
+  evidence: |
+    {
+      "protocolVersion": $prop($, 'cdx:mcp:protocolVersion'),
+      "deprecatedFeatures": $prop($, 'cdx:mcp:deprecatedFeatures'),
+      "transport": $prop($, 'cdx:mcp:transport')
+    }
+
+- id: MCP-010
+  name: "MCP bundle declares secret configuration fields"
+  description: "MCPB/DXT bundles that declare secret-typed user_config fields have those values injected into the bundled server's environment on launch. Declaring such a field is the correct way to build a bundle, so this is an inventory disclosure to aid credential-handling review rather than a defect."
+  severity: low
+  category: mcp-server
+  dry-run-support: full
+  standards:
+    owasp-ai-top-10:
+      - "LLM05: Supply Chain Vulnerabilities"
+      - "LLM03:2025 Supply Chain"
+    owasp-agentic-top-10-2026:
+      - "Agentic Supply Chain"
+    eu-ai-act:
+      - "Technical documentation and traceability"
+    eu-cra:
+      - "Software supply chain visibility"
+    nist-ai-rmf:
+      - "Govern"
+    nist-ssdf:
+      - "Review secret handling in installable AI extensions"
+  condition: |
+    components[
+      $prop($, 'cdx:file:kind') = 'mcp-bundle'
+      and $prop($, 'cdx:mcpb:injectsSecretEnv') = 'true'
+    ]
+  location: |
+    {
+      "bomRef": $."bom-ref",
+      "file": $prop($, 'internal:SrcFile')
+    }
+  message: "MCP bundle '{{ name }}' declares secret configuration fields injected as environment variables"
+  mitigation: "Review the declared secret fields and prefer runtime secret stores or references over values captured through the extension manifest."
+  evidence: |
+    {
+      "serverType": $prop($, 'cdx:mcpb:serverType'),
+      "secretFieldCount": $prop($, 'cdx:mcpb:secretFieldCount'),
+      "platformBinaryCount": $prop($, 'cdx:mcpb:platformBinaryCount')
+    }
+
+- id: MCP-011
+  name: "MCP bundle ships precompiled platform binaries"
+  description: "MCPB/DXT bundles that ship precompiled per-platform binaries execute vendor-provided native code on the host with no build-from-source step. These binaries deserve provenance and signing review before a bundle is installed."
+  severity: medium
+  category: mcp-server
+  dry-run-support: full
+  attack:
+    tactics: [TA0002]
+    techniques: [T1195.002]
+  standards:
+    owasp-ai-top-10:
+      - "LLM05: Supply Chain Vulnerabilities"
+      - "LLM03:2025 Supply Chain"
+    owasp-agentic-top-10-2026:
+      - "Agentic Supply Chain"
+    eu-ai-act:
+      - "Technical documentation and traceability"
+      - "Accuracy, robustness and cybersecurity"
+    eu-cra:
+      - "Software supply chain visibility"
+      - "Protection against untrusted code execution"
+    nist-ai-rmf:
+      - "Map"
+      - "Manage"
+    nist-ssdf:
+      - "Verify provenance of precompiled binaries before execution"
+  condition: |
+    components[
+      $prop($, 'cdx:file:kind') = 'mcp-bundle'
+      and $number($nullSafeProp($, 'cdx:mcpb:platformBinaryCount')) > 0
+    ]
+  location: |
+    {
+      "bomRef": $."bom-ref",
+      "file": $prop($, 'internal:SrcFile')
+    }
+  message: "MCP bundle '{{ name }}' ships precompiled platform binaries"
+  mitigation: "Verify the provenance and signatures of the bundled platform binaries, or prefer a bundle that builds from source, before installing."
+  evidence: |
+    {
+      "serverType": $prop($, 'cdx:mcpb:serverType'),
+      "platformBinaryCount": $prop($, 'cdx:mcpb:platformBinaryCount')
+    }

package/data/rules/package-integrity.yaml

@@ -250,7 +250,7 @@
       and $prop($, 'cdx:cargo:hasNativeBuild') = 'true'
       and $count($$.components[
         $prop($, 'cdx:github:action:ecosystem') = 'cargo'
-        and $contains($prop($, 'cdx:github:action:role'), 'toolchain')
+        and $contains($nullSafeProp($, 'cdx:github:action:role'), 'toolchain')
         and $prop($, 'cdx:github:action:versionPinningType') != 'sha'
       ]) > 0
     ]
@@ -267,7 +267,7 @@
       "buildScriptCapabilities": $prop($, 'cdx:cargo:buildScriptCapabilities'),
       "toolchainActions": $$.components[
         $prop($, 'cdx:github:action:ecosystem') = 'cargo'
-        and $contains($prop($, 'cdx:github:action:role'), 'toolchain')
+        and $contains($nullSafeProp($, 'cdx:github:action:role'), 'toolchain')
         and $prop($, 'cdx:github:action:versionPinningType') != 'sha'
       ].$prop($, 'cdx:github:action:uses')
     }
@@ -283,17 +283,17 @@
       $prop($, 'cdx:rust:buildTool') = 'cargo'
       and $prop($, 'cdx:cargo:hasNativeBuild') = 'true'
       and (
-        $contains($prop($, 'cdx:cargo:buildScriptCapabilities'), 'process-execution')
-        or $contains($prop($, 'cdx:cargo:buildScriptCapabilities'), 'network-access')
-        or $contains($prop($, 'cdx:cargo:nativeBuildIndicators'), '-sys')
+        $contains($nullSafeProp($, 'cdx:cargo:buildScriptCapabilities'), 'process-execution')
+        or $contains($nullSafeProp($, 'cdx:cargo:buildScriptCapabilities'), 'network-access')
+        or $contains($nullSafeProp($, 'cdx:cargo:nativeBuildIndicators'), '-sys')
       )
       and $count($$.components[
         $prop($, 'cdx:github:step:usesCargo') = 'true'
         and (
-          $contains($prop($, 'cdx:github:step:cargoSubcommands'), 'build')
-          or $contains($prop($, 'cdx:github:step:cargoSubcommands'), 'test')
-          or $contains($prop($, 'cdx:github:step:cargoSubcommands'), 'package')
-          or $contains($prop($, 'cdx:github:step:cargoSubcommands'), 'publish')
+          $contains($nullSafeProp($, 'cdx:github:step:cargoSubcommands'), 'build')
+          or $contains($nullSafeProp($, 'cdx:github:step:cargoSubcommands'), 'test')
+          or $contains($nullSafeProp($, 'cdx:github:step:cargoSubcommands'), 'package')
+          or $contains($nullSafeProp($, 'cdx:github:step:cargoSubcommands'), 'publish')
         )
       ]) > 0
     ]
@@ -311,10 +311,10 @@
       "cargoCommands": $$.components[
         $prop($, 'cdx:github:step:usesCargo') = 'true'
         and (
-          $contains($prop($, 'cdx:github:step:cargoSubcommands'), 'build')
-          or $contains($prop($, 'cdx:github:step:cargoSubcommands'), 'test')
-          or $contains($prop($, 'cdx:github:step:cargoSubcommands'), 'package')
-          or $contains($prop($, 'cdx:github:step:cargoSubcommands'), 'publish')
+          $contains($nullSafeProp($, 'cdx:github:step:cargoSubcommands'), 'build')
+          or $contains($nullSafeProp($, 'cdx:github:step:cargoSubcommands'), 'test')
+          or $contains($nullSafeProp($, 'cdx:github:step:cargoSubcommands'), 'package')
+          or $contains($nullSafeProp($, 'cdx:github:step:cargoSubcommands'), 'publish')
         )
       ].$prop($, 'cdx:github:step:command')
     }

package/lib/audit/index.js

@@ -6,9 +6,11 @@ import process from "node:process";
 import { createBom } from "../cli/index.js";
 import {
   isDryRun,
+  isSecureMode,
   readEnvironmentVariable,
   recordActivity,
 } from "../core/activity.js";
+import { getRemediationCatalog } from "../core/buildLedger.js";
 import {
   getTmpDir,
   safeExistsSync,
@@ -53,6 +55,12 @@ import {
   isHbomLikeBom,
   isObomLikeBom,
 } from "../stages/postgen/auditBom.js";
+import {
+  isIntrospectionEnabled,
+  reflectOnRun,
+} from "../stages/postgen/introspection/reflect.js";
+import { buildIntrospectionJson } from "../stages/postgen/introspection/report.js";
+import { scoreReflection } from "../stages/postgen/introspection/score.js";
 import { postProcess } from "../stages/postgen/postgen.js";
 import { formatTargetLabel } from "./progress.js";
 import { renderAuditReport } from "./reporters.js";
@@ -259,7 +267,7 @@ export async function runDirectBomAuditFromBoms(inputBoms, options = {}) {
       ...directAuditOptions,
       getBomWithOras,
     });
-    results.push({
+    const result = {
       auditOptions: directAuditOptions,
       bomFormat: getCycloneDxFormat(inputBom.bomJson),
       findings,
@@ -268,7 +276,43 @@ export async function runDirectBomAuditFromBoms(inputBoms, options = {}) {
       specVersion: inputBom.bomJson?.specVersion,
       status: "audited",
       summary: summarizeDirectAuditFindings(findings),
-    });
+    };
+    if (isIntrospectionEnabled(options)) {
+      // The audited BOM was not generated by this run, so there is no ledger
+      // of its own; the verdict rests on BOM structure alone and says so.
+      try {
+        const reflection = await reflectOnRun(inputBom.bomJson, options, {
+          ledgerEvents: [],
+          ledgerSource: "none",
+          projectPath: inputBom.source || "",
+        });
+        reflection.scoring = scoreReflection(
+          reflection,
+          getRemediationCatalog(),
+          {
+            secureMode: isSecureMode,
+            inContainer:
+              readEnvironmentVariable("CDXGEN_IN_CONTAINER") === "true",
+          },
+        );
+        reflection.bom = {
+          serialNumber: inputBom.bomJson?.serialNumber,
+          componentCount: Array.isArray(inputBom.bomJson?.components)
+            ? inputBom.bomJson.components.length
+            : 0,
+        };
+        result.introspection = buildIntrospectionJson(
+          reflection,
+          reflection.scoring,
+          options,
+        );
+      } catch (err) {
+        console.warn(
+          `Build introspection failed to complete and was skipped: ${err?.message}`,
+        );
+      }
+    }
+    results.push(result);
   }
   const summary = {
     findingsBySeverity: {
@@ -1744,7 +1788,7 @@ async function recheckFindingsAgainstDefaultBranch(
     if (!bomNSData?.bomJson) {
       return undefined;
     }
-    const processedBomNSData = postProcess(
+    const processedBomNSData = await postProcess(
       bomNSData,
       childOptions,
       defaultSourceSelection.scanDir,
@@ -1948,7 +1992,7 @@ export async function auditTarget(target, options) {
           options,
         );
       }
-      const processedBomNSData = postProcess(
+      const processedBomNSData = await postProcess(
         bomNSData,
         childOptions,
         sourceSelection.scanDir,

package/lib/audit/scoring.js

@@ -1,17 +1,11 @@
 import { thoughtLog } from "../core/logger.js";
+import { SEVERITY_ORDER } from "../core/severity.js";
 import {
   hasRegistryProvenanceEvidenceProperties,
   hasTrustedPublishingProperties,
 } from "../inventory/provenanceUtils.js";
 
-/** Map of severity names to numeric ordering used for threshold comparisons. */
-export const SEVERITY_ORDER = {
-  none: -1,
-  low: 0,
-  medium: 1,
-  high: 2,
-  critical: 3,
-};
+export { SEVERITY_ORDER };
 
 const BASE_FINDING_WEIGHT = {
   low: 4,

package/lib/audit/targets.js

@@ -465,8 +465,13 @@ export async function enrichInputBomsWithRegistryMetadata(inputBoms) {
   process.env.CDXGEN_FETCH_PKG_METADATA = "true";
   try {
     const enrichedCandidates = [
+      // The audit scores publisher drift, ownership and release cadence, none
+      // of which the local Cargo registry records: it knows when a version was
+      // published but not by whom. This path pays the registry's rate limit
+      // deliberately rather than audit against metadata that cannot answer the
+      // questions the rules ask.
       ...(cargoCandidates.length
-        ? await getCratesMetadata(cargoCandidates)
+        ? await getCratesMetadata(cargoCandidates, { preferLocalCache: false })
         : []),
       ...(npmCandidates.length ? await getNpmMetadata(npmCandidates) : []),
       ...(pypiCandidates.length

package/lib/cli/bomAssembly.js

@@ -200,6 +200,8 @@ export const determineParentComponent = (options) => {
  * @param {object|undefined} detectedParent Parent the generator derived
  * @param {object[]} components The component list, appended to in place
  * @param {object[]} dependencies Edges the generator produced
+ * @param {object} options CLI options
+ * @param {string} ptype Package type
  * @returns {object[]} Edges to emit, re-anchored when an override applies
  */
 function anchorDetectedParent(
@@ -207,6 +209,8 @@ function anchorDetectedParent(
   detectedParent,
   components,
   dependencies,
+  options,
+  ptype,
 ) {
   const detectedRef = detectedParent?.["bom-ref"];
   const overrideRef = overrideParent?.["bom-ref"];
@@ -225,7 +229,20 @@ function anchorDetectedParent(
     // `metadata.component` is cleaned of. As a regular component it must go
     // through the same conversion or schema validation rejects the document
     // (issue #4320). The copy keeps the caller's context object untouched.
-    components.push(cleanParentComponent({ ...detectedParent }));
+    //
+    // Its workspace members go through `listComponents`, the same conversion
+    // `addMetadata` gives them when the detected parent is the one reaching
+    // `metadata.component`. Without it they keep the raw parser shape
+    // (`homepage: { url }`) that the nested Component schema rejects
+    // (issue #4326).
+    components.push(
+      cleanParentComponent({
+        ...detectedParent,
+        components: detectedParent.components?.length
+          ? listComponents(options, {}, detectedParent.components, ptype)
+          : undefined,
+      }),
+    );
   }
   // The caller owns the array it passed, and postProcess merges these edges
   // across generators, so the re-anchoring is returned rather than spliced in.
@@ -1080,7 +1097,19 @@ export function addComponent(
       component.modelCard = pkg.modelCard || undefined;
       component.data = pkg.data || undefined;
     }
+    if (options.specVersion >= 1.7) {
+      // An external component is provided by the deployment environment rather
+      // than bundled with the product. The schema defaults it to false, so it
+      // is only worth emitting when true.
+      component.isExternal = pkg.isExternal ? true : undefined;
+    }
     component["type"] = determinePackageType(pkg);
+    // `version` is optional in every spec version cdxgen emits. An empty string
+    // is not a version, and a consumer reading one has to guess whether it means
+    // "unknown" or "the empty release"; leaving the field out says it plainly.
+    if (!component.version) {
+      delete component.version;
+    }
     if (pkg["bom-ref"]) {
       component["bom-ref"] = pkg["bom-ref"];
     } else if (purlString) {
@@ -1446,6 +1475,8 @@ export const buildBomNSData = (options, pkgInfo, ptype, context) => {
     context.parentComponent,
     components,
     context.dependencies || [],
+    options,
+    ptype,
   );
   if (
     components &&

package/lib/cli/cliOptions.js

@@ -88,6 +88,21 @@ const POST_BUILD_SUPPORTED_PROJECT_TYPES = new Set([
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * The formulation privacy notice, shared by every path that turns formulation
+ * collection on automatically: the warning about emails and secrets is
+ * identical whichever caller adds the section.
+ *
+ * @returns {OptionsWarning} The notice.
+ */
+function formulationPrivacyNotice() {
+  return {
+    level: "info",
+    message:
+      "NOTE: Automatically collecting formulation information. The section may include sensitive data such as emails and secrets.\nPlease review the generated SBOM before distribution or LLM training.",
+  };
+}
+
 /**
  * Check whether a value was explicitly provided by the user (i.e., is not
  * the yargs default). Yargs always populates default values, so we cannot
@@ -175,7 +190,39 @@ function resolveOutputTarget(args, { filePath, isRemoteOrPurl }) {
     : resolve(join(filePath, args.output));
 }
 
-export function buildInitialOptions(args, { filePath, isRemoteOrPurl }) {
+/**
+ * Resolve the introspection opt-in from the flag and the environment.
+ *
+ * The parser maps `CDXGEN_INTROSPECT` onto the same boolean the flag sets, so
+ * a value outside the documented opt-in vocabulary — an exported but empty
+ * variable most of all — arrives indistinguishable from `--no-introspect`.
+ * The command line is therefore the authority on refusal, and the environment
+ * speaks only through `true` and `1`. An unmentioned flag stays undefined so a
+ * profile can still enable it.
+ *
+ * @param {Object} args Parsed CLI arguments.
+ * @param {string[]} argv Raw command-line arguments the parser was given.
+ * @returns {boolean|undefined} The requested state, or undefined when nothing asked.
+ */
+function resolveIntrospectOption(args, argv) {
+  const refused =
+    args.introspect === false &&
+    argv.some((argument) =>
+      ["--no-introspect", "--introspect=false"].includes(argument),
+    );
+  if (refused) {
+    return false;
+  }
+  return args.introspect === true ||
+    ["true", "1"].includes(readEnvironmentVariable("CDXGEN_INTROSPECT"))
+    ? true
+    : undefined;
+}
+
+export function buildInitialOptions(
+  args,
+  { filePath, isRemoteOrPurl, argv = process.argv },
+) {
   const res = Object.assign({}, args, {
     projectType: args.type,
     multiProject: args.recurse,
@@ -188,6 +235,10 @@ export function buildInitialOptions(args, { filePath, isRemoteOrPurl }) {
     include: args.include || args.includeRegex,
     noIgnore: args.noIgnore,
     gitAiNotesRef: args.gitAiNotesRef || "refs/notes/ai",
+    // Introspection: the flag or the documented environment opt-in. An
+    // explicit --no-introspect stays `false` and beats both, while an
+    // unmentioned flag stays undefined so a profile can still enable it.
+    introspect: resolveIntrospectOption(args, argv),
     // License normalization and enrichment are on by default; the only escape
     // hatch is the corresponding environment variable.
     licenseEnhance:
@@ -318,6 +369,20 @@ export function applyPostConstructionOverrides(options, context) {
     options.installDeps = false;
   }
 
+  // --- Introspection CI gate threshold -----------------------------------
+  if (options.introspectFailBelow !== undefined) {
+    const threshold = Number(options.introspectFailBelow);
+    if (!Number.isFinite(threshold) || threshold < 0 || threshold > 100) {
+      warnings.push({
+        level: "error",
+        message:
+          "--introspect-fail-below requires a number between 0 and 100, where absent means the gate never fails.",
+      });
+    } else {
+      options.introspectFailBelow = threshold;
+    }
+  }
+
   // When a standard is requested, the minimum spec version is 1.6
   if (options.standard) {
     if (!userSetSpecVersion) {
@@ -381,6 +446,8 @@ export function applyAdvancedOptions(options, context = {}) {
   const secureMode = context.isSecureMode ?? isSecureMode;
   const warnings = [];
   const isHbomOnly = isHbomOnlyProjectTypes(options.projectType);
+  const includeFormulationBeforeProfiles = options.includeFormulation === true;
+  const introspectExplicitlyDisabled = options.introspect === false;
 
   // --- Profile expansion -------------------------------------------------
   switch (options.profile) {
@@ -412,6 +479,14 @@ export function applyAdvancedOptions(options, context = {}) {
     case "license-compliance":
       process.env.FETCH_LICENSE = "true";
       break;
+    case "introspect":
+      options.introspect = true;
+      options.introspectAnnotate = options.introspectAnnotate !== false;
+      // The ledger's own record of what ran; formulation is where a consumer
+      // looks for the build environment the SBOM was produced in.
+      options.includeFormulation = !isHbomOnly;
+      options.evidence = true;
+      break;
     case "ml-tiny":
       process.env.FETCH_LICENSE = "true";
       options.deep = false;
@@ -471,17 +546,29 @@ export function applyAdvancedOptions(options, context = {}) {
     }
   }
 
+  // An explicit --no-introspect negates the introspect profile's headline
+  // capability while keeping the bundle's other effects: the user asked for
+  // the profile minus introspection.
+  if (options.profile === "introspect" && introspectExplicitlyDisabled) {
+    options.introspect = false;
+    warnings.push({
+      level: "info",
+      message:
+        "NOTE: Introspection stays off because --no-introspect was passed explicitly; the other introspect profile settings still apply.",
+    });
+  }
+
   // --- BOM audit → auto-formulation --------------------------------------
-  if (options.bomAudit) {
+  const introspectProfileAddsFormulation =
+    options.profile === "introspect" && !includeFormulationBeforeProfiles;
+  if (options.bomAudit || introspectProfileAddsFormulation) {
     if (isHbomOnly) {
       // HBOM-only: skip formulation
     } else if (!options.includeFormulation) {
-      warnings.push({
-        level: "info",
-        message:
-          "NOTE: Automatically collecting formulation information. The section may include sensitive data such as emails and secrets.\nPlease review the generated SBOM before distribution or LLM training.",
-      });
+      warnings.push(formulationPrivacyNotice());
       options.includeFormulation = true;
+    } else if (introspectProfileAddsFormulation) {
+      warnings.push(formulationPrivacyNotice());
     }
   }