@cyclonedx/cdxgen 12.2.0 → 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/depsUtils.js

@@ -119,6 +119,22 @@ export function trimComponents(components) {
           existingComponent.properties = comp.properties;
         }
       }
+      if (comp.hashes) {
+        if (existingComponent.hashes) {
+          for (const newhash of comp.hashes) {
+            if (
+              !existingComponent.hashes.find(
+                (hash) =>
+                  hash.alg === newhash.alg && hash.content === newhash.content,
+              )
+            ) {
+              existingComponent.hashes.push(newhash);
+            }
+          }
+        } else {
+          existingComponent.hashes = comp.hashes;
+        }
+      }
       // Retain all component.evidence.identity
       if (comp?.evidence?.identity) {
         if (!existingComponent.evidence) {

package/lib/helpers/depsUtils.poku.js

@@ -1,6 +1,6 @@
 import { assert, describe, it } from "poku";
 
-import { mergeDependencies } from "./depsUtils.js";
+import { mergeDependencies, trimComponents } from "./depsUtils.js";
 
 describe("mergeDependencies()", () => {
   it("merges two non-overlapping dependency arrays", () => {
@@ -148,3 +148,60 @@ describe("mergeDependencies()", () => {
     assert.ok(!entry.dependsOn.includes(null), "null must be filtered");
   });
 });
+
+describe("trimComponents()", () => {
+  it("retains hashes from duplicate components", () => {
+    const components = [
+      {
+        name: "jquery",
+        version: "3.5.1",
+        purl: "pkg:npm/jquery@3.5.1",
+        type: "library",
+        properties: [{ name: "SrcFile", value: "Scripts/jquery.min.js" }],
+      },
+      {
+        name: "jquery",
+        version: "3.5.1",
+        purl: "pkg:npm/jquery@3.5.1",
+        type: "framework",
+        hashes: [{ alg: "SHA-512", content: "abc123" }],
+        properties: [{ name: "SrcFile", value: "package-lock.json" }],
+      },
+    ];
+    const result = trimComponents(components);
+    assert.strictEqual(result.length, 1);
+    assert.deepStrictEqual(result[0].hashes, [
+      { alg: "SHA-512", content: "abc123" },
+    ]);
+  });
+
+  it("merges and deduplicates hashes from duplicate components", () => {
+    const components = [
+      {
+        name: "jquery",
+        version: "3.5.1",
+        purl: "pkg:npm/jquery@3.5.1",
+        type: "library",
+        hashes: [{ alg: "SHA-512", content: "abc123" }],
+        properties: [{ name: "SrcFile", value: "Scripts/jquery.min.js" }],
+      },
+      {
+        name: "jquery",
+        version: "3.5.1",
+        purl: "pkg:npm/jquery@3.5.1",
+        type: "framework",
+        hashes: [
+          { alg: "SHA-512", content: "abc123" },
+          { alg: "SHA-256", content: "def456" },
+        ],
+        properties: [{ name: "SrcFile", value: "package-lock.json" }],
+      },
+    ];
+    const result = trimComponents(components);
+    assert.strictEqual(result.length, 1);
+    assert.deepStrictEqual(result[0].hashes, [
+      { alg: "SHA-512", content: "abc123" },
+      { alg: "SHA-256", content: "def456" },
+    ]);
+  });
+});