@cyclonedx/cdxgen 12.2.1 → 12.3.0

package/lib/helpers/containerRisk.js

@@ -0,0 +1,186 @@
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import { getGtfoBinsMetadata } from "./gtfobins.js";
+import { dirNameStr, safeExistsSync } from "./utils.js";
+
+const CONTAINER_RISK_INDEX_FILE = join(
+  dirNameStr,
+  "data",
+  "container-knowledge-index.json",
+);
+const DEFAULT_CONTAINER_RISK_INDEX = { entries: {}, sources: {} };
+const CONTAINER_RISK_INDEX = loadContainerRiskIndex();
+
+function loadContainerRiskIndex() {
+  if (!safeExistsSync(CONTAINER_RISK_INDEX_FILE)) {
+    return DEFAULT_CONTAINER_RISK_INDEX;
+  }
+  try {
+    return JSON.parse(readFileSync(CONTAINER_RISK_INDEX_FILE, "utf8"));
+  } catch {
+    return DEFAULT_CONTAINER_RISK_INDEX;
+  }
+}
+
+function normalizeCandidate(candidate) {
+  if (!candidate || typeof candidate !== "string") {
+    return undefined;
+  }
+  const trimmed = basename(candidate.trim()).toLowerCase();
+  if (!trimmed) {
+    return undefined;
+  }
+  return trimmed;
+}
+
+function uniqueSortedStrings(values) {
+  return Array.from(
+    new Set(
+      values.filter(
+        (value) => typeof value === "string" && value.trim().length,
+      ),
+    ),
+  ).sort();
+}
+
+function resolveContainerEntry(name, linkedName, gtfoMetadata) {
+  const directCandidate = normalizeCandidate(name);
+  if (directCandidate && CONTAINER_RISK_INDEX.entries?.[directCandidate]) {
+    return {
+      canonicalName: directCandidate,
+      entry: CONTAINER_RISK_INDEX.entries[directCandidate],
+      matchSource: "basename",
+    };
+  }
+  const linkedCandidate = normalizeCandidate(linkedName);
+  if (linkedCandidate && CONTAINER_RISK_INDEX.entries?.[linkedCandidate]) {
+    return {
+      canonicalName: linkedCandidate,
+      entry: CONTAINER_RISK_INDEX.entries[linkedCandidate],
+      matchSource: "symlink",
+    };
+  }
+  const gtfoCandidate = normalizeCandidate(gtfoMetadata?.canonicalName);
+  if (gtfoCandidate && CONTAINER_RISK_INDEX.entries?.[gtfoCandidate]) {
+    return {
+      canonicalName: gtfoCandidate,
+      entry: CONTAINER_RISK_INDEX.entries[gtfoCandidate],
+      matchSource: "gtfobins",
+    };
+  }
+  return undefined;
+}
+
+function resolveKnowledgeSourceRefs(sourceKeys) {
+  const refs = [];
+  for (const sourceKey of sourceKeys || []) {
+    const ref = CONTAINER_RISK_INDEX.sources?.[sourceKey];
+    if (ref) {
+      refs.push(ref);
+    }
+  }
+  return uniqueSortedStrings(refs);
+}
+
+export function getContainerRiskMetadata(name, linkedName) {
+  const gtfoMetadata = getGtfoBinsMetadata(name, linkedName);
+  const resolvedEntry = resolveContainerEntry(name, linkedName, gtfoMetadata);
+  if (!resolvedEntry) {
+    return undefined;
+  }
+  const attackTactics = uniqueSortedStrings(
+    resolvedEntry.entry.attackTactics || [],
+  );
+  const attackTechniques = uniqueSortedStrings([
+    ...(resolvedEntry.entry.attackTechniques || []),
+    ...(gtfoMetadata?.mitreTechniques || []),
+  ]);
+  const knowledgeSources = uniqueSortedStrings(
+    resolvedEntry.entry.sourceKeys || [],
+  );
+  const knowledgeSourceRefs = resolveKnowledgeSourceRefs(knowledgeSources);
+  const offenseTools = uniqueSortedStrings(
+    resolvedEntry.entry.offenseTools || [],
+  );
+  const riskTags = uniqueSortedStrings([
+    ...(resolvedEntry.entry.riskTags || []),
+    ...(gtfoMetadata?.riskTags || []),
+  ]);
+  const seccompBlockedSyscalls = uniqueSortedStrings(
+    resolvedEntry.entry.seccompBlockedSyscalls || [],
+  );
+  return {
+    attackTactics,
+    attackTechniques,
+    canonicalName: resolvedEntry.canonicalName,
+    knowledgeSourceRefs,
+    knowledgeSources,
+    matchSource: resolvedEntry.matchSource,
+    offenseTools,
+    riskTags,
+    seccompBlockedSyscalls,
+    seccompProfile: resolvedEntry.entry.seccompProfile || "",
+  };
+}
+
+export function createContainerRiskProperties(name, linkedName) {
+  const metadata = getContainerRiskMetadata(name, linkedName);
+  if (!metadata) {
+    return [];
+  }
+  const properties = [
+    { name: "cdx:container:matched", value: "true" },
+    { name: "cdx:container:name", value: metadata.canonicalName },
+    { name: "cdx:container:matchSource", value: metadata.matchSource },
+  ];
+  if (metadata.attackTactics.length) {
+    properties.push({
+      name: "cdx:container:attackTactics",
+      value: metadata.attackTactics.join(","),
+    });
+  }
+  if (metadata.attackTechniques.length) {
+    properties.push({
+      name: "cdx:container:attackTechniques",
+      value: metadata.attackTechniques.join(","),
+    });
+  }
+  if (metadata.knowledgeSources.length) {
+    properties.push({
+      name: "cdx:container:knowledgeSources",
+      value: metadata.knowledgeSources.join(","),
+    });
+  }
+  if (metadata.knowledgeSourceRefs.length) {
+    properties.push({
+      name: "cdx:container:knowledgeSourceRefs",
+      value: metadata.knowledgeSourceRefs.join(","),
+    });
+  }
+  if (metadata.offenseTools.length) {
+    properties.push({
+      name: "cdx:container:offenseTools",
+      value: metadata.offenseTools.join(","),
+    });
+  }
+  if (metadata.riskTags.length) {
+    properties.push({
+      name: "cdx:container:riskTags",
+      value: metadata.riskTags.join(","),
+    });
+  }
+  if (metadata.seccompBlockedSyscalls.length) {
+    properties.push({
+      name: "cdx:container:seccompBlockedSyscalls",
+      value: metadata.seccompBlockedSyscalls.join(","),
+    });
+  }
+  if (metadata.seccompProfile) {
+    properties.push({
+      name: "cdx:container:seccompProfile",
+      value: metadata.seccompProfile,
+    });
+  }
+  return properties;
+}

package/lib/helpers/containerRisk.poku.js

@@ -0,0 +1,52 @@
+import { strict as assert } from "node:assert";
+
+import { describe, it } from "poku";
+
+import {
+  createContainerRiskProperties,
+  getContainerRiskMetadata,
+} from "./containerRisk.js";
+
+describe("container risk helpers", () => {
+  it("returns offensive toolkit metadata for direct container tool matches", () => {
+    const metadata = getContainerRiskMetadata("cdk");
+    assert.ok(metadata);
+    assert.strictEqual(metadata.canonicalName, "cdk");
+    assert.ok(metadata.offenseTools.includes("cdk"));
+    assert.ok(metadata.riskTags.includes("offensive-toolkit"));
+    assert.ok(metadata.attackTechniques.includes("T1611"));
+  });
+
+  it("maps kubernetes control-plane helpers to ATT&CK and offensive playbooks", () => {
+    const metadata = getContainerRiskMetadata("kubectl");
+    assert.ok(metadata);
+    assert.ok(metadata.offenseTools.includes("peirates"));
+    assert.ok(metadata.offenseTools.includes("cdk"));
+    assert.ok(metadata.attackTechniques.includes("T1613"));
+    assert.ok(metadata.riskTags.includes("k8s-cluster-pivot"));
+  });
+
+  it("tracks seccomp-sensitive namespace escape helpers", () => {
+    const metadata = getContainerRiskMetadata("nsenter");
+    assert.ok(metadata);
+    assert.strictEqual(metadata.seccompProfile, "docker-default");
+    assert.ok(metadata.seccompBlockedSyscalls.includes("setns"));
+    assert.ok(metadata.seccompBlockedSyscalls.includes("unshare"));
+  });
+
+  it("emits stable CycloneDX properties for enriched container binaries", () => {
+    const properties = createContainerRiskProperties("docker");
+    const propertyMap = Object.fromEntries(
+      properties.map((property) => [property.name, property.value]),
+    );
+    assert.strictEqual(propertyMap["cdx:container:matched"], "true");
+    assert.strictEqual(propertyMap["cdx:container:name"], "docker");
+    assert.ok(propertyMap["cdx:container:attackTechniques"].includes("T1611"));
+    assert.ok(propertyMap["cdx:container:offenseTools"].includes("deepce"));
+    assert.ok(
+      propertyMap["cdx:container:knowledgeSources"].includes(
+        "attack-containers",
+      ),
+    );
+  });
+});

package/lib/helpers/display.js

@@ -2,6 +2,10 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 
+import {
+  hasComponentRegistryProvenance,
+  REGISTRY_PROVENANCE_ICON,
+} from "./provenanceUtils.js";
 import { createStream, table } from "./table.js";
 import { isSecureMode, safeExistsSync, toCamel } from "./utils.js";
 
@@ -15,12 +19,48 @@ const SYMBOLS_ANSI = {
 };
 
 const MAX_TREE_DEPTH = 6;
+const CYCLE_NODE_ICON = "↺";
+const REPEATED_NODE_ICON = "⤴";
 const highlightStr = (s, highlight) => {
   if (highlight && s?.includes(highlight)) {
     s = s.replaceAll(highlight, `\x1b[1;33m${highlight}\x1b[0m`);
   }
   return s;
 };
+
+const formatComponentName = (component, highlight) => {
+  const displayName = highlightStr(component?.name || "", highlight);
+  if (hasComponentRegistryProvenance(component)) {
+    return `${REGISTRY_PROVENANCE_ICON} ${displayName}`;
+  }
+  return displayName;
+};
+
+const printProvenanceLegend = () => {
+  console.log(
+    `Legend: ${REGISTRY_PROVENANCE_ICON} = registry provenance or trusted publishing evidence`,
+  );
+};
+
+/**
+ * Builds legend lines for dependency tree marker icons.
+ *
+ * @param {string[]} treeGraphics Dependency tree lines
+ * @returns {string[]} Legend lines to print after the tree output
+ */
+export const buildDependencyTreeLegendLines = (treeGraphics) => {
+  const legendLines = [];
+  if (treeGraphics.some((line) => line.includes(`${REPEATED_NODE_ICON} `))) {
+    legendLines.push(`${REPEATED_NODE_ICON} = already shown`);
+  }
+  if (treeGraphics.some((line) => line.includes(`${CYCLE_NODE_ICON} `))) {
+    legendLines.push(`${CYCLE_NODE_ICON} = cycle`);
+  }
+  if (!legendLines.length) {
+    return legendLines;
+  }
+  return [`Legend: ${legendLines.join("; ")}`];
+};
 /**
  * Prints the BOM components as a streaming table to the console.
  * Delegates to {@link printOSTable} automatically when the BOM metadata indicates
@@ -29,12 +69,14 @@ const highlightStr = (s, highlight) => {
  * @param {Object} bomJson CycloneDX BOM JSON object
  * @param {string[]} [filterTypes] Optional list of component types to include; all types shown when omitted
  * @param {string} [highlight] Optional string to highlight in the output
+ * @param {string} [summaryText] Optional summary message to print after the table
  * @returns {void}
  */
 export function printTable(
   bomJson,
   filterTypes = undefined,
   highlight = undefined,
+  summaryText = undefined,
 ) {
   if (!bomJson?.components) {
     return;
@@ -59,6 +101,7 @@ export function printTable(
     ],
   };
   const stream = createStream(config);
+  let displayedProvenanceCount = 0;
   stream.write([
     filterTypes?.includes("cryptographic-asset")
       ? "Asset Type / Group"
@@ -81,9 +124,12 @@ export function printTable(
         (comp.tags || []).join(", "),
       ]);
     } else {
+      if (hasComponentRegistryProvenance(comp)) {
+        displayedProvenanceCount += 1;
+      }
       stream.write([
         highlightStr(comp.group || "", highlight),
-        highlightStr(comp.name, highlight),
+        formatComponentName(comp, highlight),
         `\x1b[1;35m${comp.version || ""}\x1b[0m`,
         comp.scope || "",
         (comp.tags || []).join(", "),
@@ -92,7 +138,9 @@ export function printTable(
   }
   stream.end();
   console.log();
-  if (!filterTypes) {
+  if (summaryText) {
+    console.log(summaryText);
+  } else if (!filterTypes) {
     console.log(
       "BOM includes",
       bomJson?.components?.length || 0,
@@ -103,6 +151,12 @@ export function printTable(
   } else {
     console.log(`Components filtered based on type: ${filterTypes.join(", ")}`);
   }
+  if (displayedProvenanceCount > 0) {
+    printProvenanceLegend();
+    console.log(
+      `${REGISTRY_PROVENANCE_ICON} ${displayedProvenanceCount} component(s) include registry provenance or trusted publishing metadata.`,
+    );
+  }
 }
 const formatProps = (props) => {
   const retList = [];
@@ -326,19 +380,8 @@ export function printDependencyTree(
   if (!dependencies.length) {
     return;
   }
-  const depMap = {};
-  const shownList = [];
-  for (const d of dependencies) {
-    if (d[mode]?.length) {
-      depMap[d.ref] = d[mode].sort();
-    } else {
-      if (mode === "provides") {
-        shownList.push(d.ref);
-      }
-    }
-  }
-  const treeGraphics = [];
-  recursePrint(depMap, dependencies, 0, shownList, treeGraphics);
+  const treeGraphics = buildDependencyTreeLines(dependencies, mode);
+  const legendLines = buildDependencyTreeLegendLines(treeGraphics);
   // table library is too slow for display large lists.
   // Fixes #491
   if (treeGraphics.length && treeGraphics.length < 100) {
@@ -359,64 +402,203 @@ export function printDependencyTree(
   } else {
     console.log(highlightStr(treeGraphics.slice(0, 500).join("\n"), highlight));
   }
+  if (legendLines.length) {
+    console.log(legendLines.join("\n"));
+  }
 }
 
-const levelPrefix = (level, isLast) => {
-  if (level === 0) {
-    return SYMBOLS_ANSI.EMPTY;
+const dependencyTreePrefix = (ancestorContinuations, isLast) => {
+  let prefix = "";
+  for (const hasNextSibling of ancestorContinuations) {
+    prefix = `${prefix}${hasNextSibling ? "│   " : "    "}`;
   }
-  let prefix = `${isLast ? SYMBOLS_ANSI.LAST_BRANCH : SYMBOLS_ANSI.BRANCH}`;
-  for (let i = 0; i < level - 1; i++) {
-    prefix = `${
-      isLast
-        ? SYMBOLS_ANSI.LAST_BRANCH.replace(" ", "─")
-        : SYMBOLS_ANSI.VERTICAL
-    }${isLast ? "" : SYMBOLS_ANSI.INDENT}${prefix}`;
+  return `${prefix}${isLast ? SYMBOLS_ANSI.LAST_BRANCH : SYMBOLS_ANSI.BRANCH}`;
+};
+
+const dependencyTreeRefKey = (ref) => ref.toLowerCase();
+
+const compareDependencyTreeNodes = (a, b) => {
+  if (a.order !== b.order) {
+    return a.order - b.order;
   }
-  return prefix;
+  return a.ref.localeCompare(b.ref);
 };
 
-const isReallyRoot = (depMap, refStr) => {
-  for (const k of Object.keys(depMap)) {
-    const dependsOn = depMap[k] || [];
-    if (
-      dependsOn.includes(refStr) ||
-      dependsOn.includes(refStr.toLowerCase())
-    ) {
-      return false;
+const createDependencyTreeGraph = (dependencies, mode) => {
+  const nodes = new Map();
+  let nextOrder = 0;
+
+  const ensureNode = (ref) => {
+    if (!ref) {
+      return undefined;
+    }
+    const refKey = dependencyTreeRefKey(ref);
+    if (!nodes.has(refKey)) {
+      nodes.set(refKey, {
+        childKeys: new Set(),
+        children: [],
+        order: nextOrder,
+        parents: new Set(),
+        ref,
+      });
+      nextOrder += 1;
+    }
+    return nodes.get(refKey);
+  };
+
+  for (const dependency of dependencies) {
+    const rawChildren = Array.isArray(dependency?.[mode])
+      ? dependency[mode].filter(Boolean)
+      : [];
+    const childRefs = Array.from(new Set(rawChildren)).sort((a, b) =>
+      a.localeCompare(b),
+    );
+    let parentNode;
+    if (mode !== "provides" || childRefs.length) {
+      parentNode = ensureNode(dependency.ref);
+    }
+    if (!childRefs.length) {
+      continue;
+    }
+    parentNode = parentNode || ensureNode(dependency.ref);
+    for (const childRef of childRefs) {
+      const childNode = ensureNode(childRef);
+      if (!parentNode || !childNode) {
+        continue;
+      }
+      parentNode.childKeys.add(dependencyTreeRefKey(childRef));
+      childNode.parents.add(dependencyTreeRefKey(parentNode.ref));
     }
   }
-  return true;
+
+  for (const node of nodes.values()) {
+    node.children = Array.from(node.childKeys).sort((a, b) =>
+      compareDependencyTreeNodes(nodes.get(a), nodes.get(b)),
+    );
+  }
+
+  return nodes;
 };
 
-const recursePrint = (depMap, subtree, level, shownList, treeGraphics) => {
-  const listToUse = Array.isArray(subtree) ? subtree : [subtree];
-  for (let i = 0; i < listToUse.length; i++) {
-    const l = listToUse[i];
-    const refStr = l.ref || l;
-    if (
-      (level === 0 &&
-        isReallyRoot(depMap, refStr) &&
-        !shownList.includes(refStr.toLowerCase())) ||
-      level > 0
-    ) {
+const renderDependencyTreeNode = (
+  nodes,
+  nodeKey,
+  depth,
+  ancestorContinuations,
+  isLast,
+  renderedNodes,
+  treeGraphics,
+  visitingNodes = new Set(),
+) => {
+  const node = nodes.get(nodeKey);
+  if (!node || renderedNodes.has(nodeKey)) {
+    return;
+  }
+  const prefix =
+    depth === 0
+      ? SYMBOLS_ANSI.EMPTY
+      : dependencyTreePrefix(ancestorContinuations, isLast);
+  treeGraphics.push(`${prefix}${node.ref}`);
+  renderedNodes.add(nodeKey);
+  if (depth >= MAX_TREE_DEPTH) {
+    return;
+  }
+  const nextVisitingNodes = new Set(visitingNodes);
+  nextVisitingNodes.add(nodeKey);
+  const nextAncestorContinuations =
+    depth === 0 ? ancestorContinuations : [...ancestorContinuations, !isLast];
+  const childEntries = [];
+  for (const childKey of node.children) {
+    if (nextVisitingNodes.has(childKey)) {
+      childEntries.push({ childKey, isCycle: true });
+      continue;
+    }
+    if (renderedNodes.has(childKey)) {
+      childEntries.push({ childKey, isRepeated: true });
+      continue;
+    }
+    childEntries.push({ childKey, isCycle: false });
+  }
+  for (let i = 0; i < childEntries.length; i++) {
+    const childEntry = childEntries[i];
+    const childNode = nodes.get(childEntry.childKey);
+    const childIsLast = i === childEntries.length - 1;
+    if (!childNode) {
+      continue;
+    }
+    if (childEntry.isCycle) {
       treeGraphics.push(
-        `${levelPrefix(level, i === listToUse.length - 1)}${refStr}`,
+        `${dependencyTreePrefix(nextAncestorContinuations, childIsLast)}${CYCLE_NODE_ICON} ${childNode.ref}`,
       );
-      shownList.push(refStr.toLowerCase());
-      if (l && depMap[refStr]) {
-        if (level < MAX_TREE_DEPTH) {
-          recursePrint(
-            depMap,
-            depMap[refStr],
-            level + 1,
-            shownList,
-            treeGraphics,
-          );
-        }
-      }
+      continue;
+    }
+    if (childEntry.isRepeated) {
+      treeGraphics.push(
+        `${dependencyTreePrefix(nextAncestorContinuations, childIsLast)}${REPEATED_NODE_ICON} ${childNode.ref}`,
+      );
+      continue;
     }
+    renderDependencyTreeNode(
+      nodes,
+      childEntry.childKey,
+      depth + 1,
+      nextAncestorContinuations,
+      childIsLast,
+      renderedNodes,
+      treeGraphics,
+      nextVisitingNodes,
+    );
+  }
+};
+
+/**
+ * Builds printable dependency tree lines from a BOM dependency graph.
+ * Produces a spanning forest so shared children are rendered once, while
+ * disconnected or cyclic subgraphs are still emitted as dangling trees.
+ *
+ * @param {Object[]} dependencies CycloneDX dependency objects
+ * @param {string} [mode="dependsOn"] Dependency relation to traverse
+ * @returns {string[]} Dependency tree lines ready for console rendering
+ */
+export const buildDependencyTreeLines = (dependencies, mode = "dependsOn") => {
+  const nodes = createDependencyTreeGraph(dependencies, mode);
+  if (!nodes.size) {
+    return [];
+  }
+  const nodeEntries = Array.from(nodes.entries()).sort(([, a], [, b]) =>
+    compareDependencyTreeNodes(a, b),
+  );
+  const rootKeys = nodeEntries
+    .filter(([, node]) => !node.parents.size)
+    .map(([nodeKey]) => nodeKey);
+  const renderedNodes = new Set();
+  const treeGraphics = [];
+  for (let i = 0; i < rootKeys.length; i++) {
+    renderDependencyTreeNode(
+      nodes,
+      rootKeys[i],
+      0,
+      [],
+      i === rootKeys.length - 1,
+      renderedNodes,
+      treeGraphics,
+    );
+  }
+  const danglingNodeKeys = nodeEntries
+    .map(([nodeKey]) => nodeKey)
+    .filter((nodeKey) => !renderedNodes.has(nodeKey));
+  for (let i = 0; i < danglingNodeKeys.length; i++) {
+    renderDependencyTreeNode(
+      nodes,
+      danglingNodeKeys[i],
+      0,
+      [],
+      i === danglingNodeKeys.length - 1,
+      renderedNodes,
+      treeGraphics,
+    );
   }
+  return treeGraphics;
 };
 
 /**