cbom-tools 0.2.5 → 0.2.7-rc.1

package/README.md

@@ -77,7 +77,22 @@ Exit codes:
 - `0` — no changes
 - `1` — informational changes (algorithm properties moved)
 - `2` — warnings (algorithm removed, new classical reference), or file/parse error
-- `3` — (reserved) quantum-vulnerable/weak algorithm detection
+- `3` — a quantum-vulnerable algorithm was newly introduced (requires both CBOMs)
+
+Exit 3 follows the definition agreed in [#43](https://github.com/Lennonhaha/fibemate-tools/issues/43):
+an algorithm whose `fibemate:quantumSecurity:level` is `vulnerable` appears in the
+after CBOM but not in the before CBOM. Two consequences are deliberate:
+
+- An algorithm that was already vulnerable and stays vulnerable is not a
+  regression, so it never turns the build red.
+- A single-CBOM scan has no baseline to compare against, so it stays at exit 1.
+  Otherwise the first scan of a legacy codebase would light up every historical
+  finding at once.
+
+The level is read from `component.properties` (`fibemate:quantumSecurity:level`),
+which is where `cbom-scan` writes it; `cryptoProperties.quantumSecurity.level` is
+accepted as a fallback for hand-written CBOMs. A missing or malformed level stays
+unknown — it is never inferred from the algorithm name.
 
 ## Testing
 
@@ -85,7 +100,7 @@ Exit codes:
 npm test
 ```
 
-68 tests (Node built-in `node:test`, zero dependencies). Both binaries are
+76 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

package/cbom-diff.js

@@ -17,7 +17,7 @@
  *   0 — 无变更
  *   1 — 有信息性变更（算法属性升级等）
  *   2 — 有警告性变更（算法删除、新经典算法引用等）
- *   3 — (reserved) 量子脆弱/弱算法引入检测（0.2.0 规划）
+ *   3 — 加密材料依赖引入了量子脆弱算法（仅在同时提供 before 与 after 时判定）
  */
 
 const { execSync } = require('child_process');
@@ -164,7 +164,7 @@ if (oldCBOM && newCBOM) {
         ref,
         name: c.name,
         type: assetType,
-        risk: classifyRisk(crypto),
+        risk: classifyRisk(crypto, quantumLevel(c)),
       });
     }
   });
@@ -196,8 +196,10 @@ if (oldCBOM && newCBOM) {
     ref: c['bom-ref'],
     name: c.name,
     type: (c.cryptoProperties || {}).assetType || c.type,
-    risk: 'info',
-  }));
+      // No baseline: every component is "present", but none is "newly
+      // introduced", so the exit-3 regression signal stays off here.
+      risk: 'info',
+    }));
 }
 
 // --- 依赖关系比较 ---
@@ -226,6 +228,8 @@ if (oldCBOM && newCBOM) {
 }
 
 // --- 严重性判定 ---
+// Exit 3 fires only when an added component is quantum-vulnerable and a
+// baseline exists to compare against (see the single-CBOM branch).
 const hasCriticalAdd = diff.components.added.some(c => c.risk === 'critical');
 const hasWarningAdd = diff.components.added.some(c => c.risk === 'warning');
 const hasRemoval = diff.components.removed.length > 0;
@@ -249,7 +253,30 @@ if (hasCriticalAdd) {
 // ════════════════════════════
 // 算法风险分类
 // ════════════════════════════
-function classifyRisk(cryptoProps) {
+// Quantum level lives in `component.properties` as a name/value pair:
+// cbom-scan emits `fibemate:quantumSecurity:level`. Hand-written CBOMs may
+// instead put it under `cryptoProperties.quantumSecurity.level`, so accept
+// both, properties first. Never guess a level from the algorithm name: an
+// unknown level must stay unknown, otherwise exit 3 becomes a name-match.
+function quantumLevel(component) {
+  const props = component && Array.isArray(component.properties) ? component.properties : [];
+  // Literal, not a module-level const: the diff runs at the top of this script,
+  // long before this line is evaluated, so a module-level binding would still be
+  // in its temporal dead zone when quantumLevel() is first called.
+  const fromProps = props.find((entry) => entry && entry.name === 'fibemate:quantumSecurity:level');
+  if (fromProps && typeof fromProps.value === 'string') return fromProps.value;
+  const cryptoProps = (component && component.cryptoProperties) || {};
+  const fromCrypto = cryptoProps.quantumSecurity && cryptoProps.quantumSecurity.level;
+  return typeof fromCrypto === 'string' ? fromCrypto : null;
+}
+
+// Risk of a component that is *added* by this diff. Definition 2 from #43:
+// exit 3 means "a quantum-vulnerable algorithm was newly introduced", and the
+// caller only classifies added components, so "present here and absent before"
+// is already established by the time we get here. A vulnerable algorithm that
+// merely stays present is not a regression and must not turn the build red.
+function classifyRisk(cryptoProps, quantum) {
+  if (quantum === 'vulnerable') return 'critical';
   const type = ((cryptoProps && cryptoProps.assetType) || '').toLowerCase();
   // PQC algorithms: safe additions
   if (/kem|sign|signature|post.quantum|pqc|mlkem|mldsa|slh/i.test(type)) return 'info';
@@ -259,8 +286,6 @@ function classifyRisk(cryptoProps) {
   if (/ecc|ecdh|p-256|sm2|curve/i.test(type)) return 'warning';
   // Classic symmetric: info (still safe with large keys)
   if (/sym|sm4|aes|gcm/i.test(type)) return 'info';
-  // TODO(v0.2.0): add 'critical' exit code for quantum-vulnerable algorithms
-  // using cryptoProps.quantumSecurity?.level
   // Unknown: treat as warning
   return 'warning';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbom-tools",
-  "version": "0.2.5",
+  "version": "0.2.7-rc.1",
   "description": "Crypto Bill of Materials — scan, diff, report (CycloneDX 1.6 CBOM)",
   "license": "Apache-2.0",
   "author": "刘天赫 <research@fibemate.net>",