muaddib-scanner 2.11.36 → 2.11.38

package/bin/muaddib.js

@@ -44,6 +44,7 @@ let target = '.';
 let jsonOutput = false;
 let htmlOutput = null;
 let sarifOutput = null;
+let cyclonedxOutput = null;
 let explainMode = false;
 let failLevel = 'high';
 let webhookUrl = null;
@@ -56,6 +57,7 @@ let temporalPublishMode = false;
 let temporalMaintainerMode = false;
 let temporalFullMode = false;
 let breakdownMode = false;
+let domainFilter = null;  // P0a: --domain malware,author → filter output by risk domain
 let noDeobfuscate = false;
 let noModuleGraph = false;
 let noReachability = false;
@@ -87,6 +89,16 @@ for (let i = 0; i < options.length; i++) {
     }
     sarifOutput = sarifPath;
     i++;
+  } else if (options[i] === '--cyclonedx') {
+    // P1b: CycloneDX 1.5 SBOM export (https://cyclonedx.org)
+    const bomPath = options[i + 1] || 'muaddib-bom.cdx.json';
+    // CLI-001: Block path traversal
+    if (bomPath.includes('..')) {
+      console.error('[ERROR] --cyclonedx path must not contain path traversal (..)');
+      process.exit(1);
+    }
+    cyclonedxOutput = bomPath;
+    i++;
   } else if (options[i] === '--explain') {
     explainMode = true;
   } else if (options[i] === '--fail-on') {
@@ -146,6 +158,24 @@ for (let i = 0; i < options.length; i++) {
     temporalMaintainerMode = true;
   } else if (options[i] === '--breakdown') {
     breakdownMode = true;
+  } else if (options[i] === '--domain') {
+    // P0a: comma-separated list of risk domains to DISPLAY (filter only, not
+    // a score modifier). Valid values: malware, author, engineering,
+    // vulnerability, license, unknown. Example: --domain malware,author
+    const val = options[i + 1];
+    if (!val || val.startsWith('-')) {
+      console.error('[ERROR] --domain requires a comma-separated list (e.g. malware,author)');
+      process.exit(1);
+    }
+    const VALID = new Set(['malware', 'author', 'engineering', 'vulnerability', 'license', 'unknown']);
+    const parts = val.split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+    const invalid = parts.filter(p => !VALID.has(p));
+    if (invalid.length > 0) {
+      console.error('[ERROR] --domain invalid value(s): ' + invalid.join(',') + ' (valid: ' + Array.from(VALID).join('|') + ')');
+      process.exit(1);
+    }
+    domainFilter = parts;
+    i++;
   } else if (options[i] === '--no-deobfuscate') {
     noDeobfuscate = true;
   } else if (options[i] === '--no-module-graph') {
@@ -254,6 +284,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
     json: jsonOutput,
     html: htmlOutput,
     sarif: sarifOutput,
+    cyclonedx: cyclonedxOutput,
     explain: explainMode,
     failLevel: failLevel,
     webhook: webhookUrl,
@@ -265,6 +296,7 @@ if (command === 'version' || command === '--version' || command === '-v') {
     exclude: excludeDirs,
     entropyThreshold: entropyThreshold,
     breakdown: breakdownMode,
+    domainFilter: domainFilter,
     noDeobfuscate: noDeobfuscate,
     noModuleGraph: noModuleGraph,
     noReachability: noReachability,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muaddib-scanner",
-  "version": "2.11.36",
+  "version": "2.11.38",
   "description": "Supply-chain threat detection & response for npm & PyPI/Python",
   "main": "src/index.js",
   "bin": {

package/{self-scan-v2.11.36.json → self-scan-v2.11.38.json}

@@ -1,6 +1,6 @@
 {
   "target": "node_modules",
-  "timestamp": "2026-05-24T21:02:11.478Z",
+  "timestamp": "2026-05-24T22:20:18.999Z",
   "threats": [
     {
       "type": "string_mutation_obfuscation",
@@ -14,6 +14,7 @@
       "rule_id": "MUADDIB-AST-074",
       "rule_name": "String Mutation Obfuscation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/",
         "https://attack.mitre.org/techniques/T1140/"
@@ -34,6 +35,7 @@
       "rule_id": "MUADDIB-AST-074",
       "rule_name": "String Mutation Obfuscation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/",
         "https://attack.mitre.org/techniques/T1140/"
@@ -54,6 +56,7 @@
       "rule_id": "MUADDIB-AST-074",
       "rule_name": "String Mutation Obfuscation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/",
         "https://attack.mitre.org/techniques/T1140/"
@@ -74,6 +77,7 @@
       "rule_id": "MUADDIB-AST-074",
       "rule_name": "String Mutation Obfuscation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/",
         "https://attack.mitre.org/techniques/T1140/"
@@ -94,6 +98,7 @@
       "rule_id": "MUADDIB-AST-074",
       "rule_name": "String Mutation Obfuscation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/",
         "https://attack.mitre.org/techniques/T1140/"
@@ -114,6 +119,7 @@
       "rule_id": "MUADDIB-AST-074",
       "rule_name": "String Mutation Obfuscation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/",
         "https://attack.mitre.org/techniques/T1140/"
@@ -134,6 +140,7 @@
       "rule_id": "MUADDIB-AST-074",
       "rule_name": "String Mutation Obfuscation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/",
         "https://attack.mitre.org/techniques/T1140/"
@@ -154,6 +161,7 @@
       "rule_id": "MUADDIB-AST-075",
       "rule_name": "Module Internals Hijack",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://nodejs.org/api/modules.html",
         "https://attack.mitre.org/techniques/T1574.006/"
@@ -174,6 +182,7 @@
       "rule_id": "MUADDIB-AST-006",
       "rule_name": "Dynamic Require with Concatenation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -193,6 +202,7 @@
       "rule_id": "MUADDIB-AST-002",
       "rule_name": "Sensitive Environment Variable Access",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://blog.phylum.io/shai-hulud-npm-worm",
         "https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions"
@@ -213,6 +223,7 @@
       "rule_id": "MUADDIB-AST-006",
       "rule_name": "Dynamic Require with Concatenation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -232,6 +243,7 @@
       "rule_id": "MUADDIB-AST-006",
       "rule_name": "Dynamic Require with Concatenation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -251,6 +263,7 @@
       "rule_id": "MUADDIB-AST-019",
       "rule_name": "Require Cache Poisoning",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1574/006/"
       ],
@@ -270,6 +283,7 @@
       "rule_id": "MUADDIB-AST-006",
       "rule_name": "Dynamic Require with Concatenation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -289,6 +303,7 @@
       "rule_id": "MUADDIB-AST-008",
       "rule_name": "Dynamic import() of Dangerous Module",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -308,6 +323,7 @@
       "rule_id": "MUADDIB-AST-005",
       "rule_name": "new Function() Constructor",
       "confidence": "high",
+      "domain": "vulnerability",
       "references": [
         "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/Function"
       ],
@@ -327,6 +343,7 @@
       "rule_id": "MUADDIB-AST-074",
       "rule_name": "String Mutation Obfuscation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/",
         "https://attack.mitre.org/techniques/T1140/"
@@ -347,6 +364,7 @@
       "rule_id": "MUADDIB-AST-074",
       "rule_name": "String Mutation Obfuscation",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/",
         "https://attack.mitre.org/techniques/T1140/"
@@ -367,6 +385,7 @@
       "rule_id": "MUADDIB-AST-008",
       "rule_name": "Dynamic import() of Dangerous Module",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -386,6 +405,7 @@
       "rule_id": "MUADDIB-AST-019",
       "rule_name": "Require Cache Poisoning",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1574/006/"
       ],
@@ -405,6 +425,7 @@
       "rule_id": "MUADDIB-AST-008",
       "rule_name": "Dynamic import() of Dangerous Module",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -424,6 +445,7 @@
       "rule_id": "MUADDIB-AST-008",
       "rule_name": "Dynamic import() of Dangerous Module",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -443,6 +465,7 @@
       "rule_id": "MUADDIB-AST-070",
       "rule_name": "Shared Memory IPC",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer",
         "https://attack.mitre.org/techniques/T1559/"
@@ -465,6 +488,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -486,6 +510,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -507,6 +532,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -528,6 +554,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -549,6 +576,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -570,6 +598,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -591,6 +620,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -612,6 +642,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -633,6 +664,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -654,6 +686,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -675,6 +708,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -696,6 +730,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -717,6 +752,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -738,6 +774,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -759,6 +796,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -780,6 +818,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -801,6 +840,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -822,6 +862,7 @@
       "rule_id": "MUADDIB-AST-007",
       "rule_name": "Dangerous Shell Command Execution",
       "confidence": "high",
+      "domain": "malware",
       "references": [
         "https://owasp.org/www-community/attacks/Command_Injection"
       ],
@@ -847,6 +888,7 @@
       "rule_id": "MUADDIB-ENTROPY-001",
       "rule_name": "High Entropy String",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -872,6 +914,7 @@
       "rule_id": "MUADDIB-ENTROPY-001",
       "rule_name": "High Entropy String",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -897,6 +940,7 @@
       "rule_id": "MUADDIB-ENTROPY-001",
       "rule_name": "High Entropy String",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -922,6 +966,7 @@
       "rule_id": "MUADDIB-ENTROPY-001",
       "rule_name": "High Entropy String",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -947,6 +992,7 @@
       "rule_id": "MUADDIB-ENTROPY-001",
       "rule_name": "High Entropy String",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -972,6 +1018,7 @@
       "rule_id": "MUADDIB-ENTROPY-001",
       "rule_name": "High Entropy String",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -997,6 +1044,7 @@
       "rule_id": "MUADDIB-ENTROPY-001",
       "rule_name": "High Entropy String",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -1022,6 +1070,7 @@
       "rule_id": "MUADDIB-ENTROPY-001",
       "rule_name": "High Entropy String",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],
@@ -1047,6 +1096,7 @@
       "rule_id": "MUADDIB-ENTROPY-001",
       "rule_name": "High Entropy String",
       "confidence": "medium",
+      "domain": "malware",
       "references": [
         "https://attack.mitre.org/techniques/T1027/"
       ],

package/src/output/cyclonedx.js

@@ -0,0 +1,204 @@
+// P1b — CycloneDX 1.5 SBOM export.
+//
+// Maps muaddib scan results to CycloneDX vulnerabilities affecting the scanned
+// package (root component). Consumed by SBOM-oriented pipelines: Dependency-
+// Track, Anchore, Snyk, Trivy, GitHub Security, etc.
+//
+// Spec : https://cyclonedx.org/docs/1.5/json/
+// Why 1.5 and not 1.6 : v1.5 has universal consumer support; v1.6 adds
+// features (mldata, evidence) we don't use.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { getRuleDomain } = require('../rules/index.js');
+
+const SPEC_VERSION = '1.5';
+const TOOL_NAME = 'muaddib';
+const TOOL_VENDOR = 'muaddib';
+const TOOL_URL = 'https://github.com/DNSZLSK/muad-dib';
+const ROOT_BOM_REF = 'scanned-package';
+
+const _muaddibVersion = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+})();
+
+/**
+ * Map muaddib severity (uppercase) → CycloneDX severity (lowercase).
+ * Unknown values fall to "info" (CycloneDX's mildest level).
+ */
+function severityToCycloneDX(severity) {
+  switch (severity) {
+    case 'CRITICAL': return 'critical';
+    case 'HIGH': return 'high';
+    case 'MEDIUM': return 'medium';
+    case 'LOW': return 'low';
+    default: return 'info';
+  }
+}
+
+/**
+ * Build a package URL (purl) for the scanned component.
+ * https://github.com/package-url/purl-spec
+ *  - npm scoped:    pkg:npm/%40scope%2Fname@version
+ *  - npm unscoped:  pkg:npm/name@version
+ *  - generic fall:  pkg:generic/dirname@0.0.0
+ *
+ * When `hasPackageJson` is true we assume npm. PyPI / other ecosystems would
+ * need a separate detector (out of scope for v1).
+ */
+function buildPurl(name, version, hasPackageJson) {
+  const safeVersion = version || '0.0.0';
+  if (!hasPackageJson) {
+    return 'pkg:generic/' + encodeURIComponent(name || 'unknown') + '@' + encodeURIComponent(safeVersion);
+  }
+  if (name && name.startsWith('@') && name.includes('/')) {
+    const slashIdx = name.indexOf('/');
+    const scope = name.slice(0, slashIdx);
+    const rest = name.slice(slashIdx + 1);
+    return 'pkg:npm/' + encodeURIComponent(scope) + '/' + encodeURIComponent(rest) + '@' + encodeURIComponent(safeVersion);
+  }
+  return 'pkg:npm/' + encodeURIComponent(name || 'unknown') + '@' + encodeURIComponent(safeVersion);
+}
+
+/**
+ * Read the scanned target's package.json (if present) to derive root identity.
+ * Returns { name, version, hasPackageJson }.
+ */
+function resolveRootComponent(targetPath) {
+  let name = null;
+  let version = null;
+  let hasPackageJson = false;
+  if (targetPath && typeof targetPath === 'string') {
+    try {
+      const pkgPath = path.join(targetPath, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        const data = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        if (typeof data.name === 'string' && data.name.length > 0) name = data.name;
+        if (typeof data.version === 'string' && data.version.length > 0) version = data.version;
+        hasPackageJson = true;
+      }
+    } catch {
+      // ignore — fallback to dirname below
+    }
+  }
+  if (!name) {
+    // Last-resort fallback: dirname of the target
+    try {
+      name = targetPath ? path.basename(path.resolve(targetPath)) : 'unknown';
+    } catch {
+      name = 'unknown';
+    }
+  }
+  if (!version) version = '0.0.0';
+  return { name, version, hasPackageJson };
+}
+
+/**
+ * Build the properties array for a vulnerability — exposes muaddib-specific
+ * data (risk_domain, confidence, mitre, type, file, line) using a namespaced
+ * key convention so consumers can filter/group on them without collisions.
+ */
+function vulnerabilityProperties(threat) {
+  const props = [];
+  const domain = threat.domain || getRuleDomain(threat.type);
+  if (domain) props.push({ name: 'muaddib:risk_domain', value: String(domain) });
+  if (threat.type) props.push({ name: 'muaddib:type', value: String(threat.type) });
+  if (threat.confidence) props.push({ name: 'muaddib:confidence', value: String(threat.confidence) });
+  if (threat.mitre) props.push({ name: 'muaddib:mitre', value: String(threat.mitre) });
+  if (threat.file) props.push({ name: 'muaddib:file', value: String(threat.file) });
+  if (threat.line) props.push({ name: 'muaddib:line', value: String(threat.line) });
+  if (typeof threat.points === 'number') props.push({ name: 'muaddib:points', value: String(threat.points) });
+  return props;
+}
+
+function vulnerabilityFromThreat(threat, idx) {
+  const sev = severityToCycloneDX(threat.severity);
+  const score = (typeof threat.points === 'number') ? threat.points : 0;
+  return {
+    'bom-ref': 'muaddib-vuln-' + idx,
+    id: threat.rule_id || threat.type || ('MUADDIB-UNK-' + idx),
+    source: { name: 'MUADDIB', url: TOOL_URL },
+    description: threat.message || (threat.type || 'muaddib threat'),
+    ratings: [
+      {
+        source: { name: 'MUADDIB' },
+        severity: sev,
+        method: 'other',
+        score,
+        vector: 'muaddib-confidence:' + (threat.confidence || 'medium')
+      }
+    ],
+    affects: [{ ref: ROOT_BOM_REF }],
+    properties: vulnerabilityProperties(threat)
+  };
+}
+
+/**
+ * Generate a CycloneDX 1.5 BOM document from a muaddib scan result.
+ * @param {object} results - scan result object (must contain `threats`, `target`, optionally `timestamp`)
+ * @returns {object} CycloneDX BOM ready to JSON.stringify
+ */
+function generateCycloneDX(results) {
+  const target = (results && results.target) || '.';
+  const timestamp = (results && results.timestamp) || new Date().toISOString();
+  const root = resolveRootComponent(target);
+  const purl = buildPurl(root.name, root.version, root.hasPackageJson);
+
+  const threats = Array.isArray(results && results.threats) ? results.threats : [];
+  const vulnerabilities = threats.map((t, i) => vulnerabilityFromThreat(t, i + 1));
+
+  return {
+    bomFormat: 'CycloneDX',
+    specVersion: SPEC_VERSION,
+    serialNumber: 'urn:uuid:' + crypto.randomUUID(),
+    version: 1,
+    metadata: {
+      timestamp,
+      tools: [
+        {
+          vendor: TOOL_VENDOR,
+          name: TOOL_NAME,
+          version: _muaddibVersion
+        }
+      ],
+      component: {
+        'bom-ref': ROOT_BOM_REF,
+        type: 'library',
+        name: root.name,
+        version: root.version,
+        purl
+      }
+    },
+    vulnerabilities
+  };
+}
+
+/**
+ * Write the generated BOM to disk. Mirrors saveSARIF semantics.
+ */
+function saveCycloneDX(results, outputPath) {
+  if (!outputPath || typeof outputPath !== 'string') {
+    throw new Error('Invalid output path for CycloneDX report');
+  }
+  const bom = generateCycloneDX(results);
+  try {
+    fs.writeFileSync(outputPath, JSON.stringify(bom, null, 2));
+  } catch (e) {
+    throw new Error('Failed to write CycloneDX report to ' + outputPath + ': ' + e.message);
+  }
+  return outputPath;
+}
+
+module.exports = {
+  generateCycloneDX,
+  saveCycloneDX,
+  severityToCycloneDX,
+  buildPurl,
+  resolveRootComponent,
+  SPEC_VERSION
+};