@cdxgen/cdxgen 13.0.1 → 13.2.0

package/lib/stages/postgen/postgen.js

@@ -7,10 +7,12 @@ import { Purl } from "@cdxgen/cdx-purl";
 import {
   DEBUG_MODE,
   isDryRun,
+  isSecureMode,
   readEnvironmentVariable,
   resetActivityContext,
   setActivityContext,
 } from "../../core/activity.js";
+import { getRemediationCatalog } from "../../core/buildLedger.js";
 import { hasAnyProjectType } from "../../core/env.js";
 import {
   getTimestamp,
@@ -44,6 +46,23 @@ import { enhanceBom } from "../../inventory/licenseEnhancer.js";
 import { applyMcpPinningState } from "../../inventory/mcpPinning.js";
 import { buildReleaseNotesFromGit } from "../../inventory/source.js";
 import { extractTags, findBomType, textualMetadata } from "./annotator.js";
+import {
+  applyFormulationRunIdMarker,
+  applyIntrospectionToBom,
+  hasIntrospectionVerdict,
+} from "./introspection/annotate.js";
+import { collectCommandFacts } from "./introspection/commandFacts.js";
+import {
+  blockRemediationsForDryRun,
+  emitIntrospectionReports,
+  printIntrospectionSummary,
+} from "./introspection/emit.js";
+import {
+  isIntrospectionEnabled,
+  reflectOnRun,
+} from "./introspection/reflect.js";
+import { scoreReflection } from "./introspection/score.js";
+import { repairParentDependencyEdge } from "./parentEdge.js";
 import { sortBomCollections } from "./sortBom.js";
 import {
   applyComponentTypeFilter,
@@ -435,6 +454,94 @@ function buildAuditFindingsCitation(bomJson) {
   });
 }
 
+/**
+ * Run the build-introspection reflection over the final BOM, score it, write
+ * the reports, and carry the verdict inside the BOM as metadata properties and
+ * annotations. Introspection is opt-in; when disabled this is a no-op, and
+ * when enabled a reflection failure warns instead of failing the completed
+ * BOM.
+ *
+ * The CI gate is decided here but enforced by the CLI after the BOM is
+ * written, so a below-threshold score never costs the user their output.
+ *
+ * @param {Object} bomNSData BOM with namespaces object
+ * @param {Object} options CLI options
+ * @param {string} [filePath] Source path that was scanned
+ *
+ * @returns {Promise<Object>} The same bomNSData, with `reflection` (carrying its `scoring`) attached when introspection ran
+ */
+async function applyIntrospection(bomNSData, options, filePath) {
+  if (!isIntrospectionEnabled(options) || !bomNSData?.bomJson) {
+    return bomNSData;
+  }
+  // Evidence collection re-processes a finished BOM through a fresh wrapper,
+  // but that pass carries neither the scanned path nor the generation's
+  // ecosystem context: its ledger events belong to the evinse probes and its
+  // marker scan finds nothing, so it would grade a project it never saw. The
+  // verdict describes how the BOM was generated, so it stays with the pass
+  // that generated it — the document itself is what carries that across.
+  if (bomNSData.reflection || hasIntrospectionVerdict(bomNSData.bomJson)) {
+    return bomNSData;
+  }
+  try {
+    const reflection = await reflectOnRun(bomNSData.bomJson, options, {
+      projectPath: filePath || options.filePath || "",
+    });
+    reflection.scoring = scoreReflection(reflection, getRemediationCatalog(), {
+      secureMode: isSecureMode,
+      inContainer: readEnvironmentVariable("CDXGEN_IN_CONTAINER") === "true",
+      commandFacts: collectCommandFacts(filePath || options.filePath || ""),
+    });
+    // Report consumers correlate a report with the BOM it describes through
+    // these two facts, so they travel on the reflection document itself.
+    reflection.bom = {
+      serialNumber: bomNSData.bomJson?.serialNumber,
+      componentCount: Array.isArray(bomNSData.bomJson?.components)
+        ? bomNSData.bomJson.components.length
+        : 0,
+    };
+    bomNSData.reflection = reflection;
+    if (isDryRun) {
+      blockRemediationsForDryRun(reflection.scoring);
+    }
+    // A document at a spec version that predates annotations still carries
+    // the metadata properties; only the annotations are version-gated.
+    const annotationsSupported =
+      normalizeCycloneDxSpecVersion(
+        options?.specVersion || bomNSData.bomJson?.specVersion,
+      ) >= 1.5;
+    applyFormulationRunIdMarker(bomNSData.bomJson, reflection.runId);
+    applyIntrospectionToBom(bomNSData.bomJson, reflection, reflection.scoring, {
+      annotations: annotationsSupported,
+    });
+    const delivery = emitIntrospectionReports(
+      reflection,
+      reflection.scoring,
+      options,
+    );
+    printIntrospectionSummary(reflection.scoring, delivery);
+    const threshold = options?.introspectFailBelow;
+    if (typeof threshold === "number" && Number.isFinite(threshold)) {
+      const score = reflection.scoring.overallScore;
+      bomNSData.introspectionGate = {
+        threshold,
+        score,
+        passed: score >= threshold,
+      };
+    }
+    if (!reflection.ledgerComplete) {
+      console.warn(
+        "Build introspection: the ledger is incomplete (buffer truncated or recorder event); treat the verdict with care and re-run with CDXGEN_INTROSPECT_LEDGER set.",
+      );
+    }
+  } catch (err) {
+    console.warn(
+      `Build introspection failed to complete and was skipped: ${err?.message}`,
+    );
+  }
+  return bomNSData;
+}
+
 /**
  * Filter and enhance BOM post generation.
  *
@@ -442,9 +549,9 @@ function buildAuditFindingsCitation(bomJson) {
  * @param {Object} options CLI options
  * @param {string} [filePath] Source path used for formulation and metadata context
  *
- * @returns {Object} Modified bomNSData
+ * @returns {Promise<Object>} Modified bomNSData
  */
-export function postProcess(bomNSData, options, filePath) {
+export async function postProcess(bomNSData, options, filePath) {
   let jsonPayload = bomNSData.bomJson;
   if (
     typeof bomNSData.bomJson === "string" ||
@@ -458,14 +565,27 @@ export function postProcess(bomNSData, options, filePath) {
   bomNSData.bomJson = applyMetadata(bomNSData.bomJson, options);
   bomNSData.bomJson = applyLicenseEnhancement(bomNSData.bomJson, options);
   bomNSData.bomJson = applyContainerInventoryMetadata(bomNSData.bomJson);
+  const buildOnlyComponents = extractBuildOnlyComponents(
+    bomNSData.bomJson,
+    options,
+  );
   bomNSData.bomJson = applyFormulation(
     bomNSData.bomJson,
     options,
     filePath,
-    bomNSData.formulationList,
+    buildOnlyComponents.length
+      ? [...(bomNSData.formulationList || []), ...buildOnlyComponents]
+      : bomNSData.formulationList,
+  );
+  bomNSData.bomJson = applyBuildOnlyFormulation(
+    bomNSData.bomJson,
+    buildOnlyComponents,
   );
   bomNSData.bomJson = applyReleaseNotes(bomNSData.bomJson, options, filePath);
   bomNSData.bomJson = applyComponentTypeFilter(bomNSData.bomJson, options);
+  // Filtering can leave the tree without a way in, so this runs on the final
+  // component set and before annotations, which report on reachability.
+  bomNSData.bomJson = repairParentDependencyEdge(bomNSData.bomJson);
   bomNSData.bomJson = applySpecVersionCompatibility(bomNSData.bomJson, options);
   bomNSData.bomJson = validateTlpClassification(bomNSData.bomJson, options);
   // Support for automatic annotations
@@ -495,6 +615,9 @@ export function postProcess(bomNSData, options, filePath) {
   cleanupEnv(options);
   cleanupTmpDir();
   sortBomCollections(bomNSData.bomJson);
+  // Reflection reads the finished BOM, so it runs after sorting; it returns
+  // its verdict alongside the BOM instead of mutating it.
+  await applyIntrospection(bomNSData, options, filePath);
   return bomNSData;
 }
 
@@ -851,6 +974,154 @@ function getIdentityTechniques(comp) {
   return techniques;
 }
 
+/**
+ * Ensure the components moved out of the assembly have landed in the
+ * formulation section.
+ *
+ * With `--include-formulation` they were handed to the full formulation pass.
+ * Without it there is no formulation section, so a minimal one is created for
+ * them alone: moving a component out of `components[]` and then dropping it
+ * would lose it from the document.
+ *
+ * @param {Object} bomJson BOM JSON object
+ * @param {Object[]} buildOnlyComponents Components removed from `components[]`
+ *
+ * @returns {Object} The same `bomJson`
+ */
+function applyBuildOnlyFormulation(bomJson, buildOnlyComponents) {
+  if (!buildOnlyComponents?.length || !bomJson) {
+    return bomJson;
+  }
+  const alreadyPlaced = (bomJson.formulation || []).some((formula) =>
+    formula?.components?.some((comp) =>
+      buildOnlyComponents.some((moved) => moved["bom-ref"] === comp["bom-ref"]),
+    ),
+  );
+  if (alreadyPlaced) {
+    return bomJson;
+  }
+  if (!bomJson.formulation) {
+    bomJson.formulation = [];
+  }
+  bomJson.formulation.push({
+    "bom-ref": `${bomJson.metadata?.component?.["bom-ref"] || "cdxgen"}#build-dependencies`,
+    components: buildOnlyComponents,
+  });
+  return bomJson;
+}
+
+/**
+ * Report whether a component exists only to produce the build, rather than
+ * being part of the delivered assembly. A cargo build dependency and a
+ * proc-macro crate are both marked with `cdx:cargo:hostOnly`.
+ *
+ * @param {Object} comp Component
+ * @returns {boolean} True for a build-time-only component
+ */
+function isBuildOnlyComponent(comp) {
+  return !!comp?.properties?.some(
+    (property) =>
+      property.name === "cdx:cargo:hostOnly" && property.value === "true",
+  );
+}
+
+/**
+ * Move the build-time-only components out of `components[]`, which describes
+ * the delivered assembly, and hand them to the formulation section, which is
+ * where CycloneDX describes how the assembly was produced.
+ *
+ * Their bom-refs stay valid because the formulation components live in the same
+ * document, so the dependency graph is left intact. `formulation` exists from
+ * CycloneDX 1.5, so an older document keeps them in `components[]` with their
+ * `cdx:cargo:hostOnly` marker rather than losing them.
+ *
+ * @param {Object} bomJson BOM JSON object
+ * @param {Object} options CLI options
+ *
+ * @returns {Object[]} The components removed from `components[]`
+ */
+export function extractBuildOnlyComponents(bomJson, options) {
+  if (options?.specVersion < 1.5 || !bomJson?.components?.length) {
+    return [];
+  }
+  const buildOnlyComponents = [];
+  const retainedComponents = [];
+  for (const comp of bomJson.components) {
+    if (isBuildOnlyComponent(comp)) {
+      buildOnlyComponents.push(comp);
+    } else {
+      retainedComponents.push(comp);
+    }
+  }
+  if (buildOnlyComponents.length) {
+    bomJson.components = retainedComponents;
+  }
+  return buildOnlyComponents;
+}
+
+/**
+ * Report whether a component carries evidence that it is actually used: an
+ * occurrence in the analyzed sources, or a frame in a callstack.
+ *
+ * @param {Object} comp Component
+ * @returns {boolean} True when usage evidence is attached
+ */
+function hasUsageEvidence(comp) {
+  if (comp?.evidence?.occurrences?.length) {
+    return true;
+  }
+  return !!comp?.evidence?.callstack?.frames?.length;
+}
+
+/**
+ * Re-apply the `--required-only` filter once the evidence stage has attached
+ * occurrence and callstack data.
+ *
+ * A manifest can only say that a dependency is optional; the evidence says
+ * whether it is reached. A component the analyzers observed in the sources is
+ * promoted to `required` so it survives the filter, while an optional component
+ * with no observed usage is dropped as before. A component scoped `excluded` -
+ * a dev or test dependency - keeps that scope: an occurrence inside the test
+ * sources is not evidence that it ships.
+ *
+ * @param {Object} bomJson BOM JSON object carrying evidence
+ * @param {Object} options CLI options
+ *
+ * @returns {Object} Filtered BOM JSON
+ */
+export function applyEvidenceBasedFilter(bomJson, options) {
+  if (!options?.requiredOnly || !bomJson?.components?.length) {
+    return bomJson;
+  }
+  if (!(options.evidence || options.includeCrypto)) {
+    return bomJson;
+  }
+  for (const comp of bomJson.components) {
+    if (!hasUsageEvidence(comp)) {
+      continue;
+    }
+    if (!comp.properties) {
+      comp.properties = [];
+    }
+    const observed = comp.evidence?.occurrences?.length
+      ? "occurrence"
+      : "callstack";
+    if (
+      !comp.properties.some(
+        (property) => property.name === "cdx:evidence:usage",
+      )
+    ) {
+      comp.properties.push({ name: "cdx:evidence:usage", value: observed });
+    }
+    if (comp.scope === "optional") {
+      comp.scope = "required";
+    }
+  }
+  // `evidenceFilterStage` tells filterBom that the evidence is in hand, so the
+  // scope filter it deferred earlier must run now.
+  return filterBom(bomJson, { ...options, evidenceFilterStage: true });
+}
+
 /**
  * Filter BOM based on options
  *
@@ -870,6 +1141,15 @@ export function filterBom(bomJson, options) {
   const allowedComponentTypes = new Set(
     normalizeCycloneDxComponentTypeFilter(options?.componentType),
   );
+  // Evidence generation runs after this stage, so dropping the optional
+  // components here would deny the analyzers the chance to prove that one is
+  // used. The scope filter is re-applied by applyEvidenceBasedFilter once the
+  // occurrence and callstack evidence is attached.
+  const deferRequiredOnly = !!(
+    options.requiredOnly &&
+    !options.evidenceFilterStage &&
+    (options.evidence || options.includeCrypto)
+  );
   for (const comp of bomJson.components) {
     if (shouldExcludeInventoryType(comp, options)) {
       filtered = true;
@@ -912,6 +1192,7 @@ export function filterBom(bomJson, options) {
     }
     if (
       options.requiredOnly &&
+      !deferRequiredOnly &&
       comp.scope &&
       ["optional", "excluded"].includes(comp.scope)
     ) {

package/lib/stages/postgen/ruleEngine.js

@@ -494,6 +494,23 @@ function registerCdxHelpers(expression, helpers = {}) {
   expression.registerFunction("formulationComponents", (bomJson) =>
     getFormulationComponents(bomJson),
   );
+  // Formulation-derived rules need to know whether the formulation section
+  // describes the run being reflected (whose probes the ledger already
+  // counted) or a foreign BOM's record. The caller that read the evidence
+  // passes its origin verdict through the options; without one, rules gated
+  // on a specific origin stay silent.
+  expression.registerFunction(
+    "formulationOrigin",
+    () => helpers?.formulationEvidence?.origin || "unknown",
+  );
+  // The toolchain mismatch a foreign BOM's formulation proves: the recorded
+  // version of this runtime's own family differs from the runtime in use, so
+  // the record describes another machine. Computed by the caller, which owns
+  // the runtime facts.
+  expression.registerFunction(
+    "formulationRuntimeMismatch",
+    () => helpers?.formulationEvidence?.runtimeMismatch,
+  );
   return expression;
 }
 

package/lib/stages/pregen/envAudit.js

@@ -47,8 +47,44 @@ const RISKY_PRESENCE_VARS = [
 // SSH_AUTH_SOCK (ends with _SOCK) and __CF_USER_TEXT_ENCODING (ends with _ENCODING)
 // are NOT flagged as false positives.
 // `cred` is kept alongside `credential(?:s)?` to also catch short-form names like MY_CRED.
+// `session` must be followed by an id qualifier (SESSION_ID, SESSIONID, SESSION-ID):
+// a bare _SESSION suffix names a session/desktop type (DESKTOP_SESSION, GDM_SESSION),
+// not a secret-bearing session identifier.
 const CREDENTIAL_VAR_PATTERN =
-  /_(?:token|key|secret|pass(?:word)?|credential(?:s)?|cred|user|email|auth|session)$/i;
+  /_(?:token|key|secret|pass(?:word)?|credential(?:s)?|cred|user|email|auth|session[_-]?id)$/i;
+
+// OS/desktop-layer variables whose names match CREDENTIAL_VAR_PATTERN but whose
+// values are public session or identity identifiers, never secrets. Each entry
+// is set automatically by the operating system or desktop environment, so
+// flagging it would warn on nearly every desktop/developer machine:
+// - GNOME_DESKTOP_SESSION_ID: deprecated gnome-session marker, always the
+//   literal string "this-is-deprecated" (kept by GNOME ≤ 3.28 and RHEL 8).
+// - KDE_SESSION_ID: numeric KDE session identifier (legacy ksmserver-era KDE).
+// - SHELL_SESSION_ID: UUID assigned to each Konsole (KDE terminal) tab/session.
+// - TERM_SESSION_ID: window/tab/process indices plus a UUID, set by Apple
+//   Terminal (documented in /etc/zshrc_Apple_Terminal) and iTerm2.
+// - ITERM_SESSION_ID: iTerm2 per-pane identifier in the same format.
+// - XDG_SESSION_ID: numeric logind audit-session id set by pam_systemd on
+//   every systemd login.
+// - SUDO_USER / DOAS_USER: login name of the invoking user, set by sudo/doas.
+// - XDG_ACTIVATION_TOKEN: single-use Wayland xdg-activation focus token set
+//   by GNOME/GLib and KDE launchers; only grants a newly launched app the
+//   right to focus its own window.
+// Native Windows variables (USERNAME, SESSIONNAME, USERDOMAIN, …) use
+// non-underscored names and cannot match the pattern, so none appear here.
+// SSH_USER_AUTH is deliberately NOT exempted: sshd only sets it with the
+// non-default `ExposeAuthInfo yes` and it points at key-fingerprint data.
+const CREDENTIAL_VAR_EXCEPTIONS = new Set([
+  "GNOME_DESKTOP_SESSION_ID",
+  "KDE_SESSION_ID",
+  "SHELL_SESSION_ID",
+  "TERM_SESSION_ID",
+  "ITERM_SESSION_ID",
+  "XDG_SESSION_ID",
+  "SUDO_USER",
+  "DOAS_USER",
+  "XDG_ACTIVATION_TOKEN",
+]);
 
 // Proxy variables — NO_PROXY is a bypass-list and should not trigger a finding on its own.
 const PROXY_VARS = ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"];
@@ -283,7 +319,11 @@ export function auditEnvironment(env = process.env, options = {}) {
 
   // Credential exposure — detect any env var whose name follows a credential-naming convention.
   for (const [varName, varValue] of Object.entries(env)) {
-    if (varValue && CREDENTIAL_VAR_PATTERN.test(varName)) {
+    if (
+      varValue &&
+      CREDENTIAL_VAR_PATTERN.test(varName) &&
+      !CREDENTIAL_VAR_EXCEPTIONS.has(varName)
+    ) {
       recordEnvironmentRead(varName, { source: envSource });
       findings.push({
         type: "credential-exposure",