cbom-tools 0.2.1 → 0.2.2

package/README.md

@@ -8,7 +8,14 @@ detect algorithm additions, removals, and metadata changes.
 
 Zero external dependencies. Pure Node.js.
 
-## Install
+## Try it without installing
+
+```
+npx cbom-tools scan --dir ./my-project --out cbom.json
+npx cbom-tools diff cbom-before.json cbom-after.json
+```
+
+Global install (optional):
 
 ```
 npm install -g cbom-tools
@@ -19,9 +26,11 @@ npm install -g cbom-tools
 ### 1. Scan a project
 
 ```
-cbom-scan --dir ./my-project --out cbom.json
+npx cbom-tools scan --dir ./my-project --out cbom.json
 ```
 
+`cbom-scan` is still installed as a standalone alias.
+
 Scans:
 - `package.json` dependencies (declarative rule table)
 - Source files (`.js/.cjs/.mjs/.ts/.tsx/.jsx`) via regex patterns
@@ -33,14 +42,16 @@ paths + line numbers, capped at 50 per algorithm, deduplicated).
 ### 2. Diff two CBOMs
 
 ```
-cbom-diff cbom-before.json cbom-after.json
+npx cbom-tools diff cbom-before.json cbom-after.json
 ```
 
+`cbom-diff` is still installed as a standalone alias.
+
 Exit codes:
 - `0` — no changes
-- `1` — changes detected
-- `2` — file not found or parse error
-- `3` — (reserved) quantum-vulnerable/weak algorithm detection (planned for 0.2.0)
+- `1` — informational changes (algorithm properties moved)
+- `2` — warnings (algorithm removed, new classical reference), or file/parse error
+- `3` — (reserved) quantum-vulnerable/weak algorithm detection
 
 ## Testing
 

package/algo-metadata.json

@@ -222,7 +222,7 @@
   "Keccak": {
     "assetType": "algorithm",
     "algorithmProperties": {
-      "primitive": "other"
+      "primitive": "hash"
     },
     "implementationPlatform": "javascript",
     "certificationLevel": "known-answer-tested",

package/cbom-diff.js

@@ -92,8 +92,43 @@ const newCBOM = loadCBOM(newHash);
 // ════════════════════════════
 // 比较逻辑
 // ════════════════════════════
-const OLD = oldCBOM ? oldCBOM.version || 0 : 0;
-const NEW = newCBOM ? newCBOM.version || 0 : 0;
+// CycloneDX `bom.version` is optional with `minimum: 1, default: 1`. An absent
+// field therefore means "the default version", not 0 and not "no version".
+// Coercing absence to 0 made one side omitted look like a version change
+// (false "bumped") or a rollback (false "downgraded").
+const BOM_VERSION_DEFAULT = 1;
+
+function readBomVersion(bom) {
+  const raw = bom ? bom.version : undefined;
+  if (raw === undefined || raw === null) {
+    return { value: BOM_VERSION_DEFAULT, explicit: false, valid: true };
+  }
+  if (!Number.isInteger(raw) || raw < 1) {
+    return { value: raw, explicit: true, valid: false };
+  }
+  return { value: raw, explicit: true, valid: true };
+}
+
+function compareBomVersion(older, newer) {
+  // A schema-invalid value is reported, never silently ordered.
+  if (!older.valid || !newer.valid) return 'unknown';
+  if (newer.value > older.value) return 'bumped';
+  if (newer.value < older.value) return 'downgraded';
+  return 'same';
+}
+
+const OLD_VERSION = readBomVersion(oldCBOM);
+const NEW_VERSION = readBomVersion(newCBOM);
+const OLD = OLD_VERSION.value;
+const NEW = NEW_VERSION.value;
+
+const versionNotes = [];
+if (!OLD_VERSION.valid) {
+  versionNotes.push(`old: version ${JSON.stringify(OLD_VERSION.value)} is not a valid BOM version (integer >= 1)`);
+}
+if (!NEW_VERSION.valid) {
+  versionNotes.push(`new: version ${JSON.stringify(NEW_VERSION.value)} is not a valid BOM version (integer >= 1)`);
+}
 
 const diff = {
   meta: {
@@ -101,9 +136,12 @@ const diff = {
     newHash: newHash,
     oldVersion: OLD,
     newVersion: NEW,
+    oldVersionExplicit: OLD_VERSION.explicit,
+    newVersionExplicit: NEW_VERSION.explicit,
+    versionNotes: versionNotes,
     date: new Date().toISOString(),
   },
-  version: NEW > OLD ? 'bumped' : (NEW < OLD ? 'downgraded' : 'same'),
+  version: compareBomVersion(OLD_VERSION, NEW_VERSION),
   components: { added: [], removed: [], changed: [], unchanged: 0 },
   dependencies: { added: [], removed: [] },
   severity: 'none', // 'none' | 'info' | 'warning' | 'critical'
@@ -277,8 +315,10 @@ if (format === 'json') {
   lines.push('');
   lines.push(`| 属性 | 值 |`);
   lines.push(`|------|-----|`);
-  lines.push(`| 旧版本 | ${OLD} |`);
-  lines.push(`| 新版本 | ${NEW} |`);
+  const oldLabel = OLD_VERSION.explicit ? `${OLD}` : `${OLD} (default)`;
+  const newLabel = NEW_VERSION.explicit ? `${NEW}` : `${NEW} (default)`;
+  lines.push(`| 旧版本 | ${oldLabel} |`);
+  lines.push(`| 新版本 | ${newLabel} |`);
   lines.push(`| 版本 | ${diff.version} |`);
   lines.push(`| 严重性 | **${diff.severity}** (exit=${diff.exitCode}) |`);
   lines.push('');

package/cbom-scan.cjs

@@ -3,215 +3,382 @@
 // Copyright (c) 2026 刘天赫
 //
 // cbom-scan.cjs — scan a directory tree for cryptographic assets,
-// emit CycloneDX 1.6 CBOM.
+// emit CycloneDX 1.6 CBOM with provenance-aware merge policy.
 
 'use strict';
 
 const fs = require('fs');
 const path = require('path');
 
+const { HIERARCHY, lookup: algoLookup } = require('./algorithm-hierarchy.cjs');
+
 const ALGO_META = JSON.parse(fs.readFileSync(path.join(__dirname, 'algo-metadata.json'), 'utf-8'));
 const PKG = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf-8'));
 
 const NAME_ALIASES = {
- 'ML-KEM-768': 'ML-KEM',
- 'ML-KEM-512': 'ML-KEM',
- 'ML-KEM-1024': 'ML-KEM',
- 'ML-DSA': 'ML-DSA/fml-dsa',
- 'ML-DSA-44': 'ML-DSA/fml-dsa',
- 'ML-DSA-65': 'ML-DSA/fml-dsa',
- 'ML-DSA-87': 'ML-DSA/fml-dsa',
- 'Keccak-256': 'Keccak',
+  'ML-KEM-768': 'ML-KEM',
+  'ML-KEM-512': 'ML-KEM',
+  'ML-KEM-1024': 'ML-KEM',
+  'ML-DSA': 'ML-DSA/fml-dsa',
+  'ML-DSA-44': 'ML-DSA/fml-dsa',
+  'ML-DSA-65': 'ML-DSA/fml-dsa',
+  'ML-DSA-87': 'ML-DSA/fml-dsa',
+  'Keccak-256': 'Keccak',
 };
 
 function lookupMeta(name) {
- if (ALGO_META[name]) return ALGO_META[name];
- const alias = NAME_ALIASES[name];
- if (alias && ALGO_META[alias]) return ALGO_META[alias];
- return null;
+  if (ALGO_META[name]) return ALGO_META[name];
+  const alias = NAME_ALIASES[name];
+  if (alias && ALGO_META[alias]) return ALGO_META[alias];
+  return null;
 }
 
+// Package-level rules declare algorithm availability without
+// source-level call sites. A component may exist with zero
+// occurrences — this is informational, not a scan miss.
+// See Issue #55 for the granularity decision.
 const DEFAULT_RULES = {
- packages: {
- '@noble/post-quantum': ['ML-KEM-768', 'ML-DSA-65', 'SLH-DSA'],
- '@noble/hashes': ['SHA3-256', 'SHA3-512', 'Keccak-256'],
- 'sm-crypto': ['SM2', 'SM3', 'SM4'],
- 'sm2-crypto': ['SM2'],
- jsbn: ['RSA'],
- '@fibemate/sm2-crypto': ['SM2'],
- '@fibemate/keccak': ['Keccak-256', 'SHA3-256'],
- },
- sourcePatterns: [
- { re: /require\(['"]sm-crypto['"]\)/g, algs: ['SM2', 'SM3', 'SM4'] },
- { re: /crypto\.createHash\(['"]sha3-(\d+)['"]\)/g, algs: ['SHA3-$1'] },
- { re: /crypto\.createHash\(['"]sha-?256['"]\)/g, algs: ['SHA-256'] },
- { re: /crypto\.createHash\(['"]sha-?512['"]\)/g, algs: ['SHA-512'] },
- { re: /noble.*post-?quantum/gi, algs: ['ML-KEM', 'ML-DSA'] },
- { re: /\bml[-_]?kem\b/gi, algs: ['ML-KEM'] },
- { re: /\bml[-_]?dsa\b/gi, algs: ['ML-DSA'] },
- { re: /\bslh[-_]?dsa\b/gi, algs: ['SLH-DSA'] },
- { re: /\bkeccak\b/gi, algs: ['Keccak'] },
- { re: /\bsm2\b/gi, algs: ['SM2'] },
- { re: /\bsm3\b/gi, algs: ['SM3'] },
- { re: /\bsm4\b/gi, algs: ['SM4'] },
- // === C/C++ 编译库（monocypher）===
- { re: /\bcrypto_lock\b/g, algs: ['ChaCha20-Poly1305'] },
- { re: /\bcrypto_unlock\b/g, algs: ['ChaCha20-Poly1305'] },
- { re: /\bcrypto_x25519/g, algs: ['X25519'] },
- { re: /\bcrypto_sign/g, algs: ['Ed25519'] },
- { re: /\bcrypto_check\b/g, algs: ['Ed25519'] },
- { re: /\bcrypto_blake2b/g, algs: ['Blake2b'] },
- { re: /\bcrypto_argon2i\b/g, algs: ['Argon2i'] },
- { re: /\bcrypto_key_exchange\b/g, algs: ['X25519'] },
- // === C/C++ 通用（mbedtls）===
- { re: /\bmbedtls_sha256/g, algs: ['SHA-256'] },
- { re: /\bmbedtls_sha512/g, algs: ['SHA-512'] },
- { re: /\bmbedtls_aes/g, algs: ['AES'] },
- { re: /\bmbedtls_gcm/g, algs: ['AES-GCM'] },
- { re: /\bmbedtls_ecdh/g, algs: ['ECDH'] },
- { re: /\bmbedtls_rsa/g, algs: ['RSA'] },
-
- // Python hashlib (MAVLink2 signing, pymavlink sample)
- { re: /import\s+hashlib/g, algs: ['SHA-256'] },
- { re: /hashlib\.sha256\(/g, algs: ['SHA-256'] },
- { re: /hashlib\.new\(\s*["']sha256["']/gi, algs: ['SHA-256'] },
-],
+  packages: {
+    // Multi-parameter packages → family-level inference per José Q2 ruling
+    '@noble/post-quantum': ['ML-DSA', 'ML-KEM', 'SLH-DSA'],
+    // @noble/hashes is multi-family — conservative: single-family inference
+    '@noble/hashes': ['Keccak'],
+    // Genuinely single-target packages → specific inference
+    'keccak256': ['Keccak-256'],
+    // Existing entries (unchanged)
+    'sm-crypto': ['SM2', 'SM3', 'SM4'],
+    'sm2-crypto': ['SM2'],
+    jsbn: ['RSA'],
+    '@fibemate/sm2-crypto': ['SM2'],
+    '@fibemate/keccak': ['Keccak-256', 'SHA3-256'],
+  },
+  sourcePatterns: [
+    // ── PQC specific (run first; dedup clears generic for same pos) ──
+    { re: /\bml[-_]?dsa[-_]?44\b/gi, algs: ['ML-DSA-44'] },
+    { re: /\bml[-_]?dsa[-_]?65\b/gi, algs: ['ML-DSA-65'] },
+    { re: /\bml[-_]?dsa[-_]?87\b/gi, algs: ['ML-DSA-87'] },
+    { re: /\bml[-_]?kem[-_]?512\b/gi, algs: ['ML-KEM-512'] },
+    { re: /\bml[-_]?kem[-_]?768\b/gi, algs: ['ML-KEM-768'] },
+    { re: /\bml[-_]?kem[-_]?1024\b/gi, algs: ['ML-KEM-1024'] },
+    { re: /\bkeccak[-_]?224\b/gi, algs: ['Keccak-224'] },
+    { re: /\bkeccak[-_]?256\b/gi, algs: ['Keccak-256'] },
+    { re: /\bkeccak[-_]?384\b/gi, algs: ['Keccak-384'] },
+    { re: /\bkeccak[-_]?512\b/gi, algs: ['Keccak-512'] },
+    // ── PQC generic (dedup removes overlap with specific above) ──
+    { re: /\bml[-_]?kem\b/gi, algs: ['ML-KEM'] },
+    { re: /\bml[-_]?dsa\b/gi, algs: ['ML-DSA'] },
+    { re: /\bslh[-_]?dsa\b/gi, algs: ['SLH-DSA'] },
+    { re: /\bkeccak\b/gi, algs: ['Keccak'] },
+    // ── SM / legacy ──
+    { re: /require\(['"]sm-crypto['"]\)/g, algs: ['SM2', 'SM3', 'SM4'] },
+    { re: /noble.*post-?quantum/gi, algs: ['ML-KEM', 'ML-DSA'] },
+    { re: /crypto\.createHash\(['"]sha3-(\d+)['"]\)/g, algs: ['SHA3-$1'] },
+    { re: /crypto\.createHash\(['"]sha-?256['"]\)/g, algs: ['SHA-256'] },
+    { re: /crypto\.createHash\(['"]sha-?512['"]\)/g, algs: ['SHA-512'] },
+    { re: /\bsm2\b/gi, algs: ['SM2'] },
+    { re: /\bsm3\b/gi, algs: ['SM3'] },
+    { re: /\bsm4\b/gi, algs: ['SM4'] },
+    // ── C/C++ (monocypher) ──
+    { re: /\bcrypto_lock\b/g, algs: ['ChaCha20-Poly1305'] },
+    { re: /\bcrypto_unlock\b/g, algs: ['ChaCha20-Poly1305'] },
+    { re: /\bcrypto_x25519/g, algs: ['X25519'] },
+    { re: /\bcrypto_sign/g, algs: ['Ed25519'] },
+    { re: /\bcrypto_check\b/g, algs: ['Ed25519'] },
+    { re: /\bcrypto_blake2b/g, algs: ['Blake2b'] },
+    { re: /\bcrypto_argon2i\b/g, algs: ['Argon2i'] },
+    { re: /\bcrypto_key_exchange\b/g, algs: ['X25519'] },
+    // ── C/C++ (mbedtls) ──
+    { re: /\bmbedtls_sha256/g, algs: ['SHA-256'] },
+    { re: /\bmbedtls_sha512/g, algs: ['SHA-512'] },
+    { re: /\bmbedtls_aes/g, algs: ['AES'] },
+    { re: /\bmbedtls_gcm/g, algs: ['AES-GCM'] },
+    { re: /\bmbedtls_ecdh/g, algs: ['ECDH'] },
+    { re: /\bmbedtls_rsa/g, algs: ['RSA'] },
+    // ── Python hashlib ──
+    { re: /import\s+hashlib/g, algs: ['SHA-256'] },
+    { re: /hashlib\.sha256\(/g, algs: ['SHA-256'] },
+    { re: /hashlib\.new\(\s*["']sha256["']/gi, algs: ['SHA-256'] },
+  ],
 };
 
 const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage', '.git', '.cache']);
 const SCAN_EXT = /\.(cjs|mjs|js|ts|tsx|jsx|cpp|c|h|hpp|py)$/;
 const MAX_OCC_PER_ALGO = 50;
 
+// ── Dependency inference ────────────────────────────────────────────
+
 function loadPackageDeps(dir) {
- const pkgPath = path.join(dir, 'package.json');
- if (!fs.existsSync(pkgPath)) return {};
- try {
- const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
- return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
- } catch {
- return {};
- }
+  const pkgPath = path.join(dir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return {};
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  } catch {
+    return {};
+  }
 }
 
+/**
+ * Match manifest dependencies against rules.
+ * @returns {Map<string, {pkgName: string, confidence: number}>}
+ */
 function matchDeps(deps, rules) {
- const found = new Set();
- for (const name of Object.keys(deps)) {
- if (rules.packages[name]) rules.packages[name].forEach(a => found.add(a));
- }
- return found;
+  /** @type {Map<string, {origins: Array<{pkgName:string, confidence:number}>}>} */
+  const found = new Map();
+  for (const [pkgName, _v] of Object.entries(deps || {})) {
+    const algos = rules.packages[pkgName];
+    if (!algos) continue;
+    for (const algo of algos) {
+      if (!found.has(algo)) found.set(algo, { origins: [] });
+      found.get(algo).origins.push({ pkgName, confidence: 0.7 });
+    }
+  }
+  return found;
 }
 
+// ── Source scanning ─────────────────────────────────────────────────
+
 function scanSource(root, rules) {
- const found = new Map();
-
- function addOcc(name, file, line) {
- let arr = found.get(name);
- if (!arr) { arr = []; found.set(name, arr); }
- if (arr.length >= MAX_OCC_PER_ALGO) return;
- const loc = path.relative(root, file).replace(/\\/g, '/');
- if (arr.some(o => o.location === loc && o.line === line)) return;
- arr.push({ location: loc, line });
- }
-
- function walk(d) {
- let entries;
- try { entries = fs.readdirSync(d, { withFileTypes: true }); }
- catch { return; }
- for (const entry of entries) {
- if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
- const full = path.join(d, entry.name);
- if (entry.isDirectory()) walk(full);
- else if (SCAN_EXT.test(entry.name)) {
- let content;
- try { content = fs.readFileSync(full, 'utf-8'); }
- catch { continue; }
- for (const { re, algs } of rules.sourcePatterns) {
- re.lastIndex = 0;
- let m;
- while ((m = re.exec(content)) !== null) {
- const line = content.slice(0, m.index).split('\n').length;
- for (const a of algs) {
- const name = a.replace(/\$(\d+)/g, (_, i) => m[i]);
- addOcc(name, full, line);
- }
- }
- }
- }
- }
- }
- walk(root);
- return found;
+  /** @type {Map<string, Array<{location:string, line:number, symbol:string}>>} */
+  const result = new Map();
+
+  function addOcc(algoName, file, line, symbol, span) {
+    if (!result.has(algoName)) result.set(algoName, []);
+    const arr = result.get(algoName);
+    if (arr.length >= MAX_OCC_PER_ALGO) return;
+    const loc = path.relative(root, file).replace(/\\/g, '/');
+    if (arr.some(o => o.location === loc && o.line === line && o.span.start === span.start && o.span.end === span.end)) return;
+    arr.push({ location: loc, line, symbol, span });
+  }
+
+  function walk(d) {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); }
+    catch { return; }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
+      const full = path.join(d, entry.name);
+      if (entry.isDirectory()) { walk(full); continue; }
+      if (!SCAN_EXT.test(entry.name)) continue;
+      let content;
+      try { content = fs.readFileSync(full, 'utf-8'); }
+      catch { continue; }
+      for (const { re, algs } of rules.sourcePatterns) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+          const line = content.slice(0, m.index).split('\n').length;
+          const span = { start: m.index, end: m.index + m[0].length };
+          for (const a of algs) {
+            const name = a.replace(/\$(\d+)/g, (_, i) => m[i]);
+            addOcc(name, full, line, m[0], span);
+          }
+        }
+      }
+    }
+  }
+  walk(root);
+  return result;
 }
 
-function toCycloneDX(algorithms) {
- return {
- bomFormat: 'CycloneDX',
- specVersion: '1.6',
- version: 1,
- metadata: {
- timestamp: new Date().toISOString(),
- tools: [{ name: 'cbom-scan', version: PKG.version, vendor: 'FIBEMATE' }],
- },
- components: [...algorithms.keys()].sort().map(name => {
- const meta = lookupMeta(name);
- const comp = {
- type: 'cryptographic-asset',
- name,
- 'bom-ref': `crypto:${name}`,
- };
- if (meta) {
-    comp.cryptoProperties = {
-      assetType: meta.assetType,
-      algorithmProperties: meta.algorithmProperties,
+// ── Occurrence deduplication ────────────────────────────────────────
+
+/**
+ * For each (file,line) position, if a family has both a specific match
+ * (with params) and a generic match (without params), drop the generic.
+ * Prevents e.g. "ml-dsa-65" from producing both ML-DSA-65 and ML-DSA.
+ */
+function deduplicateOccurrences(source) {
+  // 1. Flatten occurrences with span → [{algoName, family, params, location, line, start, end}]
+  const flat = [];
+  for (const [algoName, occs] of source) {
+    const h = HIERARCHY[algoName];
+    if (!h) continue;
+    for (const o of occs) {
+      flat.push({
+        algoName, family: h.family, params: h.params,
+        location: o.location, line: o.line,
+        start: o.span.start, end: o.span.end,
+      });
+    }
+  }
+
+  // 2. Collect spans of all specific matches
+  const specificSpans = flat
+    .filter(e => e.params !== null)
+    .map(e => ({ location: e.location, line: e.line, start: e.start, end: e.end }));
+
+  function covers(outer, inner) {
+    return outer.location === inner.location
+      && outer.line === inner.line
+      && outer.start <= inner.start
+      && outer.end >= inner.end;
+  }
+
+  // 3. Drop generic occurrences whose span is covered by a specific match
+  const drop = new Set(); // "algoName@location:line:start:end"
+  for (const e of flat) {
+    if (e.params !== null) continue; // keep all specifics
+    const absorbed = specificSpans.some(s => covers(s, e));
+    if (absorbed) drop.add(`${e.algoName}@${e.location}:${e.line}:${e.start}:${e.end}`);
+  }
+
+  // 4. Rebuild
+  const out = new Map();
+  for (const [algoName, occs] of source) {
+    const kept = occs.filter(o => !drop.has(`${algoName}@${o.location}:${o.line}:${o.span.start}:${o.span.end}`));
+    if (kept.length) out.set(algoName, kept);
+  }
+  return out;
+}
+
+// ── Provenance merge ────────────────────────────────────────────────
+
+/**
+ * Merge dependency and source results into components with provenance evidence.
+ *
+ * Merge rule: exact-name match on both sides → one identity with two methods.
+ * Single source → one identity with one method.
+ * Different names → separate components (by union iteration).
+ *
+ * @param {Map<string, {pkgName:string, confidence:number}>} fromDeps
+ * @param {Map<string, Array<{location:string, line:number, symbol:string}>>} fromSource
+ * @returns {Array<object>} components
+ */
+function mergeEvidence(fromDeps, fromSource) {
+  const names = new Set([...fromDeps.keys(), ...fromSource.keys()]);
+  const components = [];
+
+  for (const name of names) {
+    const depInfo = fromDeps.get(name);
+    const srcOccs = fromSource.get(name) || [];
+    const methods = [];
+
+    // Bug 3 fix: one method per dependency origin
+    if (depInfo) {
+      for (const o of depInfo.origins) {
+        methods.push({
+          technique: 'manifest-analysis',
+          confidence: o.confidence,
+          value: o.pkgName,
+        });
+      }
+    }
+    if (srcOccs.length) {
+      const h = HIERARCHY[name];
+      const conf = (h && h.params !== null) ? 0.9 : 0.7;
+      methods.push({
+        technique: 'source-code-analysis',
+        confidence: conf,
+        value: srcOccs[0].symbol,
+      });
+    }
+
+    // Bug 1 fix: omit line for manifest occurrences (unknown real line)
+    const occurrences = [];
+    if (depInfo) {
+      for (const o of depInfo.origins) {
+        occurrences.push({ location: 'package.json', symbol: o.pkgName });
+      }
+    }
+    // Strip internal span fields from source occurrences before output
+    for (const src of srcOccs) {
+      const { span, ...clean } = src;
+      occurrences.push(clean);
+    }
+
+    const identityConf = methods.length
+      ? Math.max(...methods.map(m => m.confidence))
+      : 0.5;
+
+    const comp = {
+      type: 'cryptographic-asset',
+      name,
+      'bom-ref': `crypto:${name}`,
+      evidence: {
+        identity: [{
+          field: 'name',
+          confidence: identityConf,
+          concludedValue: name,
+          methods,
+        }],
+        occurrences,
+      },
     };
-    const props = [];
-    if (meta.implementationPlatform)
-      props.push({ name: 'fibemate:implementationLanguages', value: meta.implementationPlatform });
-    if (meta.certificationLevel)
-      props.push({ name: 'fibemate:testingStatus', value: meta.certificationLevel });
-    if (meta.quantumSecurity?.level)
-      props.push({ name: 'fibemate:quantumSecurity:level', value: meta.quantumSecurity.level });
-    if (props.length) comp.properties = props;
+
+    const meta = lookupMeta(name);
+    if (meta) {
+      comp.cryptoProperties = {
+        assetType: meta.assetType,
+        algorithmProperties: meta.algorithmProperties,
+      };
+      const props = [];
+      if (meta.implementationPlatform) {
+        props.push({ name: 'fibemate:implementationLanguages', value: meta.implementationPlatform });
+      }
+      if (meta.certificationLevel) {
+        props.push({ name: 'fibemate:testingStatus', value: meta.certificationLevel });
+      }
+      if (meta.quantumSecurity && meta.quantumSecurity.level) {
+        props.push({ name: 'fibemate:quantumSecurity:level', value: meta.quantumSecurity.level });
+      }
+      if (props.length) comp.properties = props;
+    }
+
+    components.push(comp);
   }
- const occ = algorithms.get(name);
- if (occ && occ.length) comp.evidence = { occurrences: occ };
- return comp;
- }),
- };
+
+  return components.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// ── Output ──────────────────────────────────────────────────────────
+
+function toCycloneDX(components) {
+  return {
+    bomFormat: 'CycloneDX',
+    specVersion: '1.6',
+    version: 1,
+    metadata: {
+      timestamp: new Date().toISOString(),
+      tools: [{ name: 'cbom-scan', version: PKG.version, vendor: 'FIBEMATE' }],
+    },
+    components,
+  };
+}
+
+// ── Entry point ─────────────────────────────────────────────────────
+
 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 outPath = args.includes('--out') ? args[args.indexOf('--out') + 1] : null;
-
- const deps = loadPackageDeps(dir);
- const fromDeps = matchDeps(deps, DEFAULT_RULES);
- const fromSource = scanSource(dir, DEFAULT_RULES);
-
- // Merge: union of both. Source occurrences override empty array from deps.
- const merged = new Map();
- for (const name of fromDeps) merged.set(name, []);
- for (const [name, occ] of fromSource) merged.set(name, occ);
-
- const cbom = toCycloneDX(merged);
- const output = JSON.stringify(cbom, null, 2);
- if (outPath) {
- fs.writeFileSync(outPath, output, 'utf-8');
- console.error(`cbom-scan: wrote ${merged.size} algorithms to ${outPath}`);
- } else {
- console.log(output);
- }
- process.exit(0);
+  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 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 output = JSON.stringify(bom, null, 2);
+  if (outPath) {
+    fs.writeFileSync(outPath, output, 'utf-8');
+    console.error(`cbom-scan: wrote ${components.length} algorithms to ${outPath}`);
+  } else {
+    console.log(output);
+  }
+  process.exit(0);
 }
 
-main();
+if (require.main === module) {
+  main();
+}

package/cli.cjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 刘天赫
+/**
+ * cbom-tools — one entry point for the two binaries.
+ *
+ * Why this exists: the package shipped `cbom-scan` and `cbom-diff` as separate
+ * bins, so `npx cbom-tools scan` — the thing a first-time reader types — failed
+ * 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 diff cbom-before.json cbom-after.json
+ *
+ * The old bin names still work; this is an addition, not a rename.
+ */
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const COMMANDS = {
+  scan: 'cbom-scan.cjs',
+  diff: 'cbom-diff.js',
+};
+
+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 diff <old.json> <new.json> [--json]  diff two CBOMs
+  cbom-tools --version
+  cbom-tools --help
+
+Aliases installed alongside: cbom-scan, cbom-diff.
+Zero external dependencies. Pure Node.js.`);
+}
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+
+if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+  usage();
+  process.exit(0);
+}
+
+if (sub === '--version' || sub === '-v' || sub === 'version') {
+  const pkg = require('./package.json');
+  console.log(`cbom-tools ${pkg.version}`);
+  process.exit(0);
+}
+
+const target = COMMANDS[sub];
+if (!target) {
+  console.error(`cbom-tools: unknown command "${sub}"`);
+  usage();
+  process.exit(2);
+}
+
+const result = spawnSync(process.execPath, [path.join(__dirname, target), ...argv.slice(1)], {
+  stdio: 'inherit',
+});
+
+if (result.error) {
+  console.error(`cbom-tools: failed to run ${target}: ${result.error.message}`);
+  process.exit(2);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -1,14 +1,36 @@
 {
   "name": "cbom-tools",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Crypto Bill of Materials — scan, diff, report (CycloneDX 1.6 CBOM)",
   "license": "Apache-2.0",
   "author": "刘天赫 <research@fibemate.net>",
   "bin": {
-    "cbom-scan": "./cbom-scan.cjs",
-    "cbom-diff": "./cbom-diff.js"
+    "cbom-tools": "cli.cjs",
+    "cbom-scan": "cbom-scan.cjs",
+    "cbom-diff": "cbom-diff.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lennonhaha/fibemate-tools.git",
+    "directory": "cbom-tools"
+  },
+  "homepage": "https://fibemate.net/tools/",
+  "bugs": {
+    "url": "https://github.com/Lennonhaha/fibemate-tools/issues"
+  },
+  "keywords": [
+    "cbom",
+    "cyclonedx",
+    "sbom",
+    "cryptography",
+    "post-quantum",
+    "compliance"
+  ],
+  "engines": {
+    "node": ">=18"
   },
   "files": [
+    "cli.cjs",
     "cbom-scan.cjs",
     "cbom-diff.js",
     "algo-metadata.json",