@cdxgen/cdxgen 13.0.1 → 13.1.0

package/README.md

@@ -32,15 +32,16 @@ Supported output document formats:
 
 ## Choose your path
 
-| Persona               | What cdxgen helps you do                                                                                             | First command                                                              | Read next                                                                                                 |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| **Developers**        | Generate a CycloneDX BOM from a local repo, git URL, purl, or container image                                        | `cdxgen -o bom.json .`                                                     | [CLI Usage][docs-cli], [Supported Project Types][docs-project-types]                                      |
-| **AI platform teams** | Generate AI/ML BOMs, catalog prompt/model/MCP surfaces, and run AI-BOM governance                                    | `aibom .`                                                                  | [AI-BOM Guide](docs/AI_BOM.md), [AI-BOM lesson](docs/LESSON15.md)                                         |
-| **Hardware teams**    | Generate an HBOM or merged HBOM+OBOM host view for the current host                                                  | `hbom -o hbom.json`                                                        | [HBOM guide](docs/HBOM.md), [HBOM lesson](docs/LESSON13.md)                                               |
-| **AppSec**            | Enrich BOMs with evidence, run BOM audit rules, and feed downstream security workflows                               | `cdxgen -o bom.json --profile appsec --evidence --bom-audit .`             | [BOM Audit](docs/BOM_AUDIT.md), [Threat Model](docs/THREAT_MODEL.md)                                      |
-| **SOC analysts**      | Build OBOM inventories for live hosts and triage runtime posture issues                                              | `obom -o obom.json --deep --bom-audit --bom-audit-categories obom-runtime` | [OBOM lessons](docs/OBOM_LESSONS.md), [Server Usage][docs-server]                                         |
-| **Compliance teams**  | Validate BOM quality, check SCVS/CRA posture, and export SPDX deliverables                                           | `cdx-validate -i bom.json --benchmark scvs-l2,cra`                         | [cdx-validate](docs/CDX_VALIDATE.md), [cdx-convert](docs/CDX_CONVERT.md), [Permissions][docs-permissions] |
-| **Security Teams**    | Dynamically trace executions to capture cryptographic activities, CBOM properties, software components, and services | `tracebom --cbom-output cbom.json -- npm test`                             | [Threat Model](docs/THREAT_MODEL.md)                                                                      |
+| Persona               | What cdxgen helps you do                                                                                             | First command                                                              | Read next                                                                                                       |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **Developers**        | Generate a CycloneDX BOM from a local repo, git URL, purl, or container image                                        | `cdxgen -o bom.json .`                                                     | [CLI Usage][docs-cli], [Supported Project Types][docs-project-types]                                            |
+| **AI platform teams** | Generate AI/ML BOMs, catalog prompt/model/MCP surfaces, and run AI-BOM governance                                    | `aibom .`                                                                  | [AI-BOM Guide](docs/AI_BOM.md), [AI-BOM lesson](docs/LESSON15.md)                                               |
+| **Hardware teams**    | Generate an HBOM or merged HBOM+OBOM host view for the current host                                                  | `hbom -o hbom.json`                                                        | [HBOM guide](docs/HBOM.md), [HBOM lesson](docs/LESSON13.md)                                                     |
+| **AppSec**            | Enrich BOMs with evidence, run BOM audit rules, and feed downstream security workflows                               | `cdxgen -o bom.json --profile appsec --evidence --bom-audit .`             | [BOM Audit](docs/BOM_AUDIT.md), [Threat Model](docs/THREAT_MODEL.md)                                            |
+| **Build engineers**   | Grade how completely the SBOM captured the project, and get ranked fixes when the build environment degraded it      | `cdxgen --profile introspect --introspect-fail-below 70 -o bom.json .`     | [Build Introspection](docs/INTROSPECTION.md), [Fidelity loop skill](.agents/skills/sbom-fidelity-loop/SKILL.md) |
+| **SOC analysts**      | Build OBOM inventories for live hosts and triage runtime posture issues                                              | `obom -o obom.json --deep --bom-audit --bom-audit-categories obom-runtime` | [OBOM lessons](docs/OBOM_LESSONS.md), [Server Usage][docs-server]                                               |
+| **Compliance teams**  | Validate BOM quality, check SCVS/CRA posture, and export SPDX deliverables                                           | `cdx-validate -i bom.json --benchmark scvs-l2,cra`                         | [cdx-validate](docs/CDX_VALIDATE.md), [cdx-convert](docs/CDX_CONVERT.md), [Permissions][docs-permissions]       |
+| **Security Teams**    | Dynamically trace executions to capture cryptographic activities, CBOM properties, software components, and services | `tracebom --cbom-output cbom.json -- npm test`                             | [Threat Model](docs/THREAT_MODEL.md)                                                                            |
 
 ### Role-based quick starts
 
@@ -120,6 +121,7 @@ Sections include:
 - [MCP Inventory](docs/MCP.md)
 - [REPL Guide](docs/REPL.md)
 - [Custom Properties](docs/CUSTOM_PROPERTIES.md)
+- [Claude Code Plugin](claude-plugin/README.md)
 - [Deprecations](docs/DEPRECATIONS.md)
 - [Security Policy](SECURITY.md)
 - [Threat Model](docs/THREAT_MODEL.md)
@@ -214,7 +216,7 @@ Common asset names:
 #### Linux
 
 ```bash
-VERSION="v13.0.1"
+VERSION="v13.1.0"
 ASSET="cdx-audit-linux-amd64"
 BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
 
@@ -228,7 +230,7 @@ chmod +x "${ASSET}"
 #### macOS
 
 ```bash
-VERSION="v13.0.1"
+VERSION="v13.1.0"
 ASSET="cdx-audit-darwin-arm64"
 BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
 
@@ -242,7 +244,7 @@ chmod +x "${ASSET}"
 #### Windows (PowerShell)
 
 ```powershell
-$Version = "v13.0.1"
+$Version = "v13.1.0"
 $Asset = "cdx-audit-windows-amd64.exe"
 $BaseUrl = "https://github.com/cdxgen/cdxgen/releases/download/$Version"
 
@@ -267,7 +269,7 @@ steps:
     env:
       GH_TOKEN: ${{ github.token }}
     run: |
-      gh release download v13.0.1 \
+      gh release download v13.1.0 \
         --repo cdxgen/cdxgen \
         --pattern 'cdx-audit-linux-amd64' \
         --pattern 'cdx-audit-linux-amd64.sha256'
@@ -620,6 +622,17 @@ cdxgen can retain the dependency tree under the `dependencies` attribute for a s
 pnpm dlx @cdxgen/cdxgen-plugins-bin
 ```
 
+## Claude Code plugin
+
+The cdxgen toolkit is also packaged as a [Claude Code](https://claude.com/claude-code) plugin, so agents drive the correct command and flags — including the dry-run-first and no-auto-install safety constraints — instead of guessing.
+
+```shell
+claude plugin marketplace add cdxgen/cdxgen
+claude plugin install cdxgen@cdxgen-plugins
+```
+
+It ships skills covering SBOM generation, container and rootfs scans, OBOM/HBOM, CBOM, AI-BOM and MCP inventory, BOM auditing, signing, validation, conversion, evidence enrichment, runtime tracing, and Dependency-Track publishing. See [claude-plugin/README.md](claude-plugin/README.md).
+
 ## Rust accelerator (cdxrs)
 
 cdxgen ships with an optional Rust accelerator binary, `cdxrs`, which speeds up hot paths such as registry metadata lookups where available. Use the `--rust` and `--no-rust` arguments to toggle it, or set the environment variable `CDXGEN_RS_DISABLE=all` to force the JavaScript path. See the [cdxrs protocol](./docs/CDXRS_PROTOCOL.md) document for implementation details.

package/bin/audit.js

@@ -132,6 +132,11 @@ const args = yargs(hideBin(process.argv))
       "Path to a license compliance policy YAML file. Evaluates every component license in the BOM(s) and reports prohibited and warning-level violations as a separate table. Error-level (prohibited) violations cause a non-zero exit.",
     type: "string",
   })
+  .option("introspect", {
+    description:
+      "Include a build-fidelity introspection verdict for each audited BOM. The BOM was not generated by this run, so the verdict rests on BOM structure alone.",
+    type: "boolean",
+  })
   .check((argv) => {
     if (!argv.bom && !argv.bomDir) {
       throw new Error("Specify --bom or --bom-dir.");
@@ -204,6 +209,7 @@ function writeOrPrint(output, outputPath) {
       categories: splitCsv(args.categories),
       directBomAudit: args.directBomAudit,
       failSeverity: args.failSeverity,
+      introspect: args.introspect === true,
       licensePolicy: args.licensePolicy,
       maxTargets: args.maxTargets,
       minSeverity: args.minSeverity,

package/bin/cdxgen.js

@@ -4,6 +4,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import http from "node:http";
 import https from "node:https";
+import { tmpdir } from "node:os";
 import {
   basename,
   dirname,
@@ -25,6 +26,12 @@ import {
   validateSpecVersion,
 } from "../lib/cli/cliOptions.js";
 import { createBom, submitBom } from "../lib/cli/index.js";
+import { closeLedger } from "../lib/core/buildLedger.js";
+import {
+  getDeferredFailures,
+  INTROSPECTION_FAILURE_EXIT_CODE,
+  isDeferredFailOnError,
+} from "../lib/core/deferredExit.js";
 import { TRACE_MODE, thoughtEnd, thoughtLog } from "../lib/core/logger.js";
 import {
   PROJECT_CONFIG_FILENAMES,
@@ -57,6 +64,7 @@ import {
   retrieveCdxgenVersion,
   safeExistsSync,
   safeMkdirSync,
+  safeRmSync,
   safeSpawnSync,
   safeWriteSync,
   setActivityContext,
@@ -486,8 +494,33 @@ const args = _yargs
       "deep-learning",
       "ml-deep",
       "ml-tiny",
+      "introspect",
     ],
   })
+  .option("introspect", {
+    type: "boolean",
+    description:
+      "Reflect on how the build environment limited BOM completeness and write an introspection report. Enabled by --profile introspect or CDXGEN_INTROSPECT=true. Pass --no-introspect to keep it off.",
+  })
+  .option("introspect-report", {
+    description:
+      "Path for the markdown introspection report. Defaults to <output>.introspection.md; '-' writes the report to stderr.",
+  })
+  .option("introspect-json", {
+    description:
+      "Path for the JSON introspection report consumed by remediation loops. Defaults to <output>.introspection.json.",
+  })
+  .option("introspect-fail-below", {
+    type: "number",
+    description:
+      "CI gate: exit with status 4 after the BOM is written when the overall introspection score is below this 0-100 threshold. Absent means the gate never fails.",
+  })
+  .option("introspect-annotate", {
+    type: "boolean",
+    default: true,
+    description:
+      "Carry the introspection verdict inside the BOM as metadata properties and annotations. Enabled with --introspect; pass --no-introspect-annotate to keep the BOM untouched.",
+  })
   .option("lifecycle", {
     description: "Product lifecycle for the generated BOM.",
     hidden: true,
@@ -602,6 +635,7 @@ const args = _yargs
       "suggest-build-tools",
       "ruby-docker-install",
       "resolve-gradle-distribution",
+      "jvm-tool-setup",
     ],
   })
   .option("min-confidence", {
@@ -1010,6 +1044,29 @@ const { options, warnings: phase3Warnings } = buildOptionsFromArgs(args, {
   isDryRun,
   isSecureMode,
 });
+// Exit status reserved for the introspection CI gate: the BOM was generated
+// and written, but its introspection score missed the configured threshold.
+// Distinct from 1 so CI can tell a generation failure from a not-good-enough
+// SBOM.
+const INTROSPECTION_GATE_EXIT_CODE = 4;
+// The ledger recorder resolves its environment lazily, so the parsed flag is
+// bridged into the environment it reads: a run started with --introspect
+// records the same events as one started with CDXGEN_INTROSPECT=true. Without
+// an explicitly configured sidecar, an automatic temp sidecar captures
+// worker-thread events the main thread never sees; it is removed once the
+// reports are written. Dry-run creates no files, so it keeps an in-memory
+// ledger only.
+let autoLedgerSidecar;
+if (options.introspect) {
+  process.env.CDXGEN_INTROSPECT = "true";
+  if (!isDryRun && !readEnvironmentVariable("CDXGEN_INTROSPECT_LEDGER")) {
+    autoLedgerSidecar = join(
+      tmpdir(),
+      `cdxgen-introspect-ledger-${process.pid}.jsonl`,
+    );
+    process.env.CDXGEN_INTROSPECT_LEDGER = autoLedgerSidecar;
+  }
+}
 const cliActivityProjectType = Array.isArray(options.projectType)
   ? options.projectType.join(",")
   : options.projectType;
@@ -1683,8 +1740,14 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
       prepareEnv(srcDir, options);
       prepPhase.succeed("");
     } catch (err) {
-      prepPhase.fail(err);
-      throw err;
+      if (isDeferredFailOnError(err)) {
+        // A deep-mode provisioning failure under --fail-on-error: the scan
+        // continues so the run still produces the verdict that explains it.
+        prepPhase.fail("environment preparation failed");
+      } else {
+        prepPhase.fail(err);
+        throw err;
+      }
     }
   }
   thoughtLog("Getting ready to generate the BOM ⚡️.");
@@ -1756,7 +1819,7 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
   {
     const postPhase = defaultUi.phase("Post-processing BOM");
     try {
-      bomNSData = postProcess(
+      bomNSData = await postProcess(
         bomNSData,
         { ...options, executeOsQuery },
         srcDir,
@@ -2008,7 +2071,7 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
           dbObjMap,
           evinseOptions,
         );
-        const evinseJson = evinserModule.createEvinseFile(
+        const evinseJson = await evinserModule.createEvinseFile(
           sliceArtefacts,
           evinseOptions,
         );
@@ -2147,6 +2210,64 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
       console.log("Try running the command with -t <type> or -r argument");
     }
   }
+  // The reflection consumed the ledger while producing its reports, so an
+  // automatic sidecar can be released and removed. An explicitly configured
+  // sidecar belongs to the user and is left alone.
+  if (autoLedgerSidecar) {
+    closeLedger();
+    try {
+      safeRmSync(autoLedgerSidecar, { force: true });
+    } catch {
+      // Best-effort cleanup of our own temp file: a runtime whose permission
+      // model denies the removal must not fail a run whose BOM and reports
+      // are already written.
+    }
+  }
+  // A --fail-on-error extractor failure on an introspected run was deferred
+  // until the BOM and both reports existed; here it finally claims its
+  // non-zero exit. It outranks the fidelity gate because a failed toolchain is
+  // the more fundamental claim, and the report still carries the gate
+  // decision.
+  const deferredFailures = getDeferredFailures();
+  if (deferredFailures.length) {
+    const reported = new Set();
+    for (const failure of deferredFailures) {
+      const message = `fail-on-error: ${failure.detail} (tool: ${failure.tool}${failure.exitCode !== undefined ? `, exit ${failure.exitCode}` : ""}).`;
+      if (!reported.has(message)) {
+        reported.add(message);
+        console.error(message);
+      }
+    }
+    // Exit 5 is the promise that the outputs exist. A run that failed before
+    // producing any BOM never made that promise and keeps the historical
+    // exit 1, which is what "cdxgen failed to generate a BOM" has always
+    // meant.
+    const wroteBom = Boolean(bomNSData?.bomJson);
+    console.error(
+      wroteBom
+        ? `fail-on-error: ${reported.size} extractor failure(s) were deferred so the BOM and the introspection report could be written; exiting ${INTROSPECTION_FAILURE_EXIT_CODE}.`
+        : "fail-on-error: no BOM was produced, so there is no verdict to report; exiting 1.",
+    );
+    if (cleanup) {
+      cleanupSourceDir(srcDir);
+    }
+    process.exit(wroteBom ? INTROSPECTION_FAILURE_EXIT_CODE : 1);
+  }
+  // The introspection CI gate fires only after the BOM and the reports are
+  // written: a below-threshold score reports a not-good-enough SBOM, never a
+  // lost one.
+  if (
+    bomNSData?.introspectionGate &&
+    bomNSData.introspectionGate.passed === false
+  ) {
+    console.error(
+      `Build introspection: score ${bomNSData.introspectionGate.score} is below the --introspect-fail-below threshold ${bomNSData.introspectionGate.threshold}.`,
+    );
+    if (cleanup) {
+      cleanupSourceDir(srcDir);
+    }
+    process.exit(INTROSPECTION_GATE_EXIT_CODE);
+  }
   thoughtEnd();
   // Automatically submit the bom data
   // biome-ignore lint/suspicious/noDoubleEquals: yargs passes true for empty values

package/bin/evinse.js

@@ -338,7 +338,7 @@ ensureCycloneDxInput(args.input);
     // Analyze the project using atom. Convert package namespaces to purl using the db
     const sliceArtefacts = await analyzeProject(dbObjMap, args);
     // Create the SBOM with Evidence
-    const bomJson = createEvinseFile(sliceArtefacts, args);
+    const bomJson = await createEvinseFile(sliceArtefacts, args);
     // Validate our final SBOM
     if (!(await validateBom(bomJson))) {
       process.exit(1);

package/data/component-tags.json

@@ -119,7 +119,14 @@
       "projections",
       "performance",
       "plugins",
-      "non-block"
+      "non-block",
+      "http",
+      "grpc",
+      "graphql",
+      "wsgi",
+      "asgi",
+      "llm",
+      "mcp"
     ]
   },
   "properties": {

package/data/frameworks-list.json

@@ -76,6 +76,56 @@
     "pkg:pypi/langchain",
     "pkg:pypi/llama",
     "pkg:pypi/sqlalchemy",
+    "pkg:pypi/starlette",
+    "pkg:pypi/quart",
+    "pkg:pypi/litestar",
+    "pkg:pypi/blacksheep",
+    "pkg:pypi/robyn",
+    "pkg:pypi/connexion",
+    "pkg:pypi/werkzeug",
+    "pkg:pypi/asgiref",
+    "pkg:pypi/djangorestframework",
+    "pkg:pypi/scrapy",
+    "pkg:pypi/streamlit",
+    "pkg:pypi/gradio",
+    "pkg:pypi/dash",
+    "pkg:pypi/nicegui",
+    "pkg:pypi/reflex",
+    "pkg:pypi/pydantic",
+    "pkg:pypi/sqlmodel",
+    "pkg:pypi/tortoise-orm",
+    "pkg:pypi/peewee",
+    "pkg:pypi/mongoengine",
+    "pkg:pypi/beanie",
+    "pkg:pypi/marshmallow",
+    "pkg:pypi/strawberry-graphql",
+    "pkg:pypi/graphene",
+    "pkg:pypi/ariadne",
+    "pkg:pypi/grpcio",
+    "pkg:pypi/thrift",
+    "pkg:pypi/mcp",
+    "pkg:pypi/fastmcp",
+    "pkg:pypi/openai",
+    "pkg:pypi/anthropic",
+    "pkg:pypi/litellm",
+    "pkg:pypi/langgraph",
+    "pkg:pypi/haystack-ai",
+    "pkg:pypi/autogen",
+    "pkg:pypi/pyautogen",
+    "pkg:pypi/crewai",
+    "pkg:pypi/semantic-kernel",
+    "pkg:pypi/transformers",
+    "pkg:pypi/sentence-transformers",
+    "pkg:pypi/huggingface-hub",
+    "pkg:pypi/celery",
+    "pkg:pypi/kombu",
+    "pkg:pypi/dramatiq",
+    "pkg:pypi/huey",
+    "pkg:pypi/jinja2",
+    "pkg:pypi/mako",
+    "pkg:pypi/chameleon",
+    "pkg:pypi/genshi",
+    "pkg:pypi/twisted",
     "vibora",
     "koa",
     "-sdk",
@@ -214,6 +264,41 @@
     "pkg:gem/volt",
     "pkg:gem/trailblazer",
     "pkg:gem/ramaze",
-    "pkg:gem/scorched"
+    "pkg:gem/scorched",
+    "Grpc.AspNetCore",
+    "Microsoft.AspNetCore.SignalR",
+    "Microsoft.Azure.Functions.Worker",
+    "Microsoft.NET.Sdk.Functions",
+    "Amazon.Lambda.Core",
+    "MassTransit",
+    "NServiceBus",
+    "MediatR",
+    "Rebus",
+    "HotChocolate.AspNetCore",
+    "GraphQL",
+    "Microsoft.AspNetCore.OData",
+    "ModelContextProtocol",
+    "ModelContextProtocol.AspNetCore",
+    "Microsoft.SemanticKernel",
+    "Microsoft.Extensions.AI",
+    "OpenAI",
+    "Azure.AI.OpenAI",
+    "Anthropic.SDK",
+    "AWSSDK.BedrockRuntime",
+    "Hangfire.AspNetCore",
+    "Quartz",
+    "FastEndpoints",
+    "Carter",
+    "ServiceStack",
+    "Nancy",
+    "Microsoft.ML",
+    "Microsoft.ML.OnnxRuntime",
+    "TorchSharp",
+    "LLamaSharp",
+    "Qdrant.Client",
+    "Milvus.Client",
+    "Pinecone.NET",
+    "Dapr.AspNetCore",
+    "Confluent.Kafka"
   ]
 }