cbom-tools 0.2.3 → 0.2.5

package/README.md

@@ -3,15 +3,27 @@
 **Cryptographic Bill of Materials — scan, diff, report.**
 
 Scan a directory tree for cryptographic assets, emit a
-[CycloneDX 1.6](https://cyclonedx.org/) CBOM, and diff two CBOMs to
-detect algorithm additions, removals, and metadata changes.
+[CycloneDX 1.7](https://cyclonedx.org/specification/overview/) CBOM, and diff two
+CBOMs to detect algorithm additions, removals, and metadata changes.
+1.6 output is still available with `--spec 1.6` for consumers that have not
+moved yet.
 
 Zero external dependencies. Pure Node.js.
 
+## What this tool does not do
+
+Three things that are easy to misread:
+
+- **It does not find vulnerabilities.** No CVE lookup, no taint analysis, no judgement about whether an algorithm choice is sound. It reports *where cryptographic APIs are called*, and says nothing about whether they are called well.
+- **It does not guarantee a complete inventory.** Detection is pattern-based per language and library. A clean scan means "no match against the patterns this version knows" — not "there is no cryptography here". Dynamic loading, generated code, native bindings and vendored binaries can all be missed. The CBOM is evidence of what was found, not a certificate of what exists.
+- **It does not execute the code it scans.** Files are read and parsed. Nothing in the scanned tree is run.
+
+A CBOM is an inventory to review. It is not a compliance conclusion, and it cannot replace an audit.
+
 ## Try it without installing
 
 ```
-npx cbom-tools scan --dir ./my-project --out cbom.json
+npx cbom-tools scan --dir ./my-project --out cbom.json --spec 1.7
 npx cbom-tools diff cbom-before.json cbom-after.json
 ```
 
@@ -26,18 +38,32 @@ npm install -g cbom-tools
 ### 1. Scan a project
 
 ```
-npx cbom-tools scan --dir ./my-project --out cbom.json
+npx cbom-tools scan --dir ./my-project --out cbom.json --spec 1.7
 ```
 
 `cbom-scan` is still installed as a standalone alias.
 
+### Spec version
+
+`--spec` accepts `1.7` (default) and `1.6`. Both forms work:
+`--spec 1.7` and `--spec=1.7`. Anything else is a usage error (exit 2)
+rather than a silent fallback — a BOM that claims a version it does not
+conform to is worse than no BOM.
+
+The schema is the contract, so CI validates the emitted document against the
+official `bom-1.7.schema.json` (and, for `--spec 1.6`, against
+`bom-1.6.schema.json`). The two differ in the declared version and in which
+documented fields are permitted; the findings themselves are identical, and a
+test asserts exactly that.
+
 Scans:
 - `package.json` dependencies (declarative rule table)
 - Source files (`.js/.cjs/.mjs/.ts/.tsx/.jsx`) via regex patterns
 
-Output: a CycloneDX 1.6 JSON with `cryptoProperties` (asset type,
+Output: a CycloneDX 1.7 JSON with `cryptoProperties` (asset type,
 primitive, quantum security level) and `evidence.occurrences` (file
 paths + line numbers, capped at 50 per algorithm, deduplicated).
+Pass `--spec 1.6` to emit the previous schema version instead.
 
 ### 2. Diff two CBOMs
 
@@ -59,11 +85,18 @@ Exit codes:
 npm test
 ```
 
-17 CLI contract tests (Node built-in `node:test`, zero dependencies):
-both binaries are spawned as child processes and checked against edge
-inputs — empty directory, dependencies-only, source-only, an 800-file
-tree (occurrence cap, `node_modules` / `.git` / dotfile skipping),
-unreachable directories, missing argument values, and malformed JSON.
+68 tests (Node built-in `node:test`, zero dependencies). Both binaries are
+spawned as child processes and checked against edge inputs — empty directory,
+dependencies-only, source-only, an 800-file tree (occurrence cap,
+`node_modules` / `.git` / dotfile skipping), unreachable directories, missing
+argument values, and malformed JSON.
+
+`test/spec-version.test.cjs` covers the `--spec` contract: the default is
+1.7, both `--spec 1.7` and `--spec=1.7` are parsed, an unknown version exits
+2 with the allowed list, the emitted document validates against the vendored
+official schema for the version it claims, and switching versions does not
+change the findings. Schemas are vendored under `test/fixtures`, so the suite
+runs offline.
 
 ## Example (real output)
 
@@ -71,10 +104,10 @@ Scanning a repository before and after a PQC migration:
 
 ```
 $ cbom-scan --dir ./repo-before --out before.json
-cbom-scan: wrote 11 algorithms to before.json
+cbom-scan: wrote 11 algorithms to before.json (CycloneDX 1.7)
 
-$ cbom-scan --dir ./repo-after --out after.json
-cbom-scan: wrote 13 algorithms to after.json
+$ cbom-scan --dir ./repo-after --out after.json --spec 1.6
+cbom-scan: wrote 13 algorithms to after.json (CycloneDX 1.6)
 
 $ cbom-diff before.json after.json
 ## CBOM Diff
@@ -114,9 +147,9 @@ only — no cryptographic computation is performed.
 
 ## Standards
 
-Implements the [CycloneDX 1.6](https://cyclonedx.org/specification/overview/)
-CBOM specification, maintained by [OWASP](https://owasp.org/) under
-Apache-2.0.
+Emits the [CycloneDX 1.7](https://cyclonedx.org/specification/overview/) CBOM
+format by default, with 1.6 available via `--spec 1.6`. The specification is
+maintained by [OWASP](https://owasp.org/) under Apache-2.0.
 
 ## License
 

package/cbom-scan.cjs

@@ -3,7 +3,7 @@
 // Copyright (c) 2026 刘天赫
 //
 // cbom-scan.cjs — scan a directory tree for cryptographic assets,
-// emit CycloneDX 1.6 CBOM with provenance-aware merge policy.
+// emit a CycloneDX 1.6 or 1.7 CBOM with provenance-aware merge policy.
 
 'use strict';
 
@@ -333,10 +333,10 @@ function mergeEvidence(fromDeps, fromSource) {
 
 // ── Output ──────────────────────────────────────────────────────────
 
-function toCycloneDX(components) {
+function toCycloneDX(components, specVersion) {
   return {
     bomFormat: 'CycloneDX',
-    specVersion: '1.6',
+    specVersion,
     version: 1,
     metadata: {
       timestamp: new Date().toISOString(),
@@ -348,31 +348,68 @@ function toCycloneDX(components) {
 
 // ── Entry point ─────────────────────────────────────────────────────
 
+const SPEC_VERSIONS = ['1.6', '1.7'];
+const DEFAULT_SPEC = '1.7';
+const USAGE = 'usage: cbom-scan [--dir <path>] [--out <file>] [--spec 1.6|1.7]';
+
+/**
+ * Read `--flag value` or `--flag=value`.
+ *
+ * The equals form used to be invisible to the parser: `--dir=./x` left the
+ * directory at process.cwd() and scanned the wrong tree without complaining.
+ * A flag that is silently ignored is worse than a flag that errors.
+ */
+function readFlag(args, name) {
+  const eqPrefix = name + '=';
+  let value = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === name) {
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('--')) return { error: name + ' needs a value' };
+      value = next;
+    } else if (args[i].startsWith(eqPrefix)) {
+      value = args[i].slice(eqPrefix.length);
+    }
+  }
+  if (value === '') return { error: name + ' needs a value' };
+  return { value };
+}
+
+function fail(message) {
+  console.error(USAGE);
+  console.error('  ' + message);
+  process.exit(2);
+}
+
 function main() {
   const args = process.argv.slice(2);
-  const dirFlag = args.indexOf('--dir');
-  let dir = process.cwd();
-  if (dirFlag !== -1) {
-    const v = args[dirFlag + 1];
-    if (!v || v.startsWith('--')) {
-      console.error('usage: cbom-scan [--dir <path>] [--out <file>]');
-      process.exit(2);
-    }
-    dir = v;
+
+  const dirFlag = readFlag(args, '--dir');
+  if (dirFlag.error) fail(dirFlag.error);
+  const dir = dirFlag.value === null ? process.cwd() : dirFlag.value;
+
+  const outFlag = readFlag(args, '--out');
+  if (outFlag.error) fail(outFlag.error);
+  const outPath = outFlag.value;
+
+  const specFlag = readFlag(args, '--spec');
+  if (specFlag.error) fail(specFlag.error);
+  const specVersion = specFlag.value === null ? DEFAULT_SPEC : specFlag.value;
+  if (!SPEC_VERSIONS.includes(specVersion)) {
+    fail('--spec must be one of ' + SPEC_VERSIONS.join(', ') + ' (got "' + specVersion + '")');
   }
-  const outPath = args.includes('--out') ? args[args.indexOf('--out') + 1] : null;
 
   const deps = loadPackageDeps(dir);
   const fromDeps = matchDeps(deps, DEFAULT_RULES);
   const rawSource = scanSource(dir, DEFAULT_RULES);
   const fromSource = deduplicateOccurrences(rawSource);
   const components = mergeEvidence(fromDeps, fromSource);
-  const bom = toCycloneDX(components);
+  const bom = toCycloneDX(components, specVersion);
 
   const output = JSON.stringify(bom, null, 2);
   if (outPath) {
     fs.writeFileSync(outPath, output, 'utf-8');
-    console.error(`cbom-scan: wrote ${components.length} algorithms to ${outPath}`);
+    console.error(`cbom-scan: wrote ${components.length} algorithms to ${outPath} (CycloneDX ${specVersion})`);
   } else {
     console.log(output);
   }

package/cli.cjs

@@ -9,7 +9,7 @@
  * with "could not determine executable to run". A package whose name is not a
  * command is a package nobody tries twice.
  *
- *   npx cbom-tools scan --dir ./project --out cbom.json
+ *   npx cbom-tools scan --dir ./project --out cbom.json --spec 1.7
  *   npx cbom-tools diff cbom-before.json cbom-after.json
  *
  * The old bin names still work; this is an addition, not a rename.
@@ -27,7 +27,8 @@ function usage() {
   console.log(`cbom-tools — Cryptographic Bill of Materials
 
 Usage:
-  cbom-tools scan [--dir <path>] [--out <file>]   scan a tree, emit CycloneDX CBOM
+  cbom-tools scan [--dir <path>] [--out <file>] [--spec 1.6|1.7]
+                                                  scan a tree, emit a CBOM (default 1.7)
   cbom-tools diff <old.json> <new.json> [--json]  diff two CBOMs
   cbom-tools --version
   cbom-tools --help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbom-tools",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Crypto Bill of Materials — scan, diff, report (CycloneDX 1.6 CBOM)",
   "license": "Apache-2.0",
   "author": "刘天赫 <research@fibemate.net>",
@@ -24,7 +24,8 @@
     "sbom",
     "cryptography",
     "post-quantum",
-    "compliance"
+    "compliance",
+    "cyclonedx-1.7"
   ],
   "engines": {
     "node": ">=18"