precogs-cbom

v2.0.0

Published

2 months ago

Enterprise-grade Cryptographic Bill of Materials engine

0High
0Medium
0Low

abhisahani

cbom cyclonedx cryptography security post-quantum pqc compliance sbom fips-140 pci-dss

@precogs/cbom

Enterprise-Grade Cryptographic & Quantum Bill of Materials CLI JavaScript (Node.js) · CycloneDX 1.6 · CBOM + QBOM · Post-Quantum Ready

cbom performs comprehensive cryptographic discovery across source code, dependencies, container images, compiled binaries, PKI/keystores, key-management services, and live network endpoints, then emits both a CBOM (Cryptographic Bill of Materials) and a companion QBOM (Quantum Bill of Materials) in CycloneDX 1.6 — with risk scoring, post-quantum readiness analysis, and compliance evaluation against eight major frameworks.

Enterprise Capability Coverage

The five pillars of enterprise cryptographic discovery (as in IBM's CBOM/QBOM tooling):

| Pillar | Status | How | |--------|--------|-----| | 1. Source-code scanning (AST-level) | ✅ | Real syntax trees via web-tree-sitter (pure WASM) for JS/TS, Python, Java, Go, Ruby, PHP, C/C++, C#, Rust, Kotlin, Scala, Swift. Resolves import aliases, aliased objects, and propagated constants — catching what regex cannot (e.g. nodeCrypto.createCipheriv(ALGO,…)). Regex engine runs alongside as a fallback for every other language. | | 2. Container / binary / dependency | ✅ | Dependency manifests (11 ecosystems + CVE DB); Dockerfile/compose crypto packages & baked-in keys; OCI / docker save image tarball layer walking (cbom image); ELF/PE/Mach-O/JAR crypto-library soname & banner detection. | | 3. Certificate & PKI discovery | ✅ | X.509 PEM/DER/PKCS#12; JKS/keystore parsing; CA-bundle / trust-store analysis; per-file trust-chain validation (missing issuers); LDAP / Active Directory endpoint discovery. | | 4. Network / protocol scanning | ✅ | Active probing (cbom netscan): TLS 1.0–1.3 version enumeration, negotiated cipher suite, served certificate chain; SSH KEXINIT algorithm enumeration; LDAP/LDAPS; IPsec/IKE reachability. Pure Node — no external binaries. | | 5. Key & secret discovery (HSM/KMS/Vault) | ✅ | Provider-specific secret regexes + entropy; private-key files; PKCS#11 HSMs, AWS/Azure/GCP KMS, HashiCorp Vault / CyberArk, cloud HSMs, Java keystores. |

Installation

npm install -g @precogs/cbom

Or run locally:

git clone <repo>
cd cbom-engine
npm install
node ./bin/cbom.js scan ./your-project

Requires Node.js ≥ 18. No network calls during a scan — all CVE / PQC data is bundled.

Quick Start

# scan a project; emit JSON, Markdown, and HTML reports
cbom scan ./my-project --secrets-detect --pqc-check \
     --compliance pci-dss,fips-140,nist-pqc \
     --output cbom-report --fail-on critical

This produces:

cbom-report.json — CycloneDX 1.6 CBOM
cbom-report.qbom.json — CycloneDX 1.6 QBOM (quantum readiness) — suppress with --no-qbom
cbom-report.md — human-readable findings report
cbom-report.html — interactive dashboard (open in a browser)

# also actively probe live endpoints and fold results into the same CBOM/QBOM
cbom scan ./my-project --targets targets.yaml

# deep-scan a container image tarball (docker save my:tag -o image.tar)
cbom image image.tar

# probe network endpoints only
cbom netscan targets.yaml

CLI Flags

| Flag | Description | Default | |------|-------------|---------| | -o, --output <file> | Output base path (extension auto-added) | cbom-report | | -f, --format <fmt> | cyclonedx, markdown, html, or all | all | | -c, --compliance <list> | Comma-separated frameworks (see below) | none | | --pqc-check | Enable post-quantum analysis section | always on | | --secrets-detect | Enable hardcoded secret + entropy detection | off | | --targets <file> | Also actively probe endpoints in a YAML/JSON targets file (TLS/SSH/LDAP/IPsec) | off | | --no-qbom | Do not emit the companion QBOM alongside the CBOM | emit | | --exclude <patterns> | Comma-separated glob patterns to skip | node_modules,dist,.git | | --min-risk <level> | Lowest level to include: critical/high/medium/low/safe | low | | --fail-on <level> | Exit code 1 if findings at this level exist | critical | | --no-color | Disable colored CLI output | on | | --json-summary | Print a one-line JSON summary to stdout | off |

Additional commands:

cbom validate <cbom.json>            # validates a CycloneDX 1.6 CBOM or QBOM file
cbom diff <cbomA.json> <cbomB.json>  # shows added/removed components between scans
cbom tui <cbom.json>                 # open the interactive browser on a saved report
cbom netscan <targets.yaml>          # actively probe TLS/SSH/LDAP/IPsec endpoints → CBOM+QBOM
cbom image <image.tar>               # deep-scan an OCI / docker-save image tarball → CBOM+QBOM

Network targets file

--targets and cbom netscan accept a YAML or JSON file. type is inferred from the port when omitted:

targets:
  - host: api.jlr.example.com
    port: 443
    type: tls           # tls | ssh | ldap | ldaps | ipsec
  - host: git.internal
    port: 22
    type: ssh
  - "ldaps://dc01.corp.jlr.local:636"   # shorthand string form also works

Active probing is pure Node — it needs network reachability to the targets but no external tools (openssl, nmap, ssh are not required). TLS enumerates versions 1.0–1.3, the negotiated cipher, and the served certificate chain; SSH reads the cleartext KEXINIT to enumerate kex/host-key/cipher/MAC algorithms; IPsec/IKE is a UDP/500 responder reachability check.

Terminal UI (TUI)

When stdout is a TTY, cbom scan automatically launches a multi-panel live dashboard during the scan, then drops into an interactive findings browser when it completes.

| Key | Action | |-----|--------| | ↑ ↓ / j k | navigate findings | | a c h m l s | filter by severity (all/critical/high/medium/low/safe) | | t | cycle type filter (algorithm/cert/key/protocol/library/secret) | | / | search by file or identifier (Esc clears) | | o | open selected file in $EDITOR | | e | export current filtered set → cbom-tui-export.json | | ? | help | | q / Ctrl-C | quit |

Disable the TUI for CI / piped output with --no-tui. Disable just the post-scan browser with --no-browser (live dashboard still runs).

Project-level ignore is also supported: drop a .cbomignore (gitignore-style) in your project root.

Sample Output

cbom v1.0.0 — Cryptographic Bill of Materials Engine
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✔ Scan complete — 9 files analyzed
   ✔ Algorithm Scanner    — 8 findings  (5 critical)
   ✔ Certificate Scanner  — 3 findings  (2 critical)
   ✔ Key Scanner          — 1 findings  (1 critical)
   ✔ Protocol Scanner     — 9 findings  (6 critical)
   ✔ Library Scanner      — 5 findings  (1 critical)
   ✔ Secret Scanner       — 7 findings  (4 critical)
   ✔ PQC Scanner          — 5 vulnerable assets

╭───────────────────────────────────────────────────────────╮
│   OVERALL RISK SCORE: 0/100 F  🔴                         │
│     🔴 CRITICAL  20 findings                              │
│     🟠 HIGH      6 findings                               │
│     🟡 MEDIUM    4 findings                               │
│     🟢 LOW       2 findings                               │
│   ⚛️  POST-QUANTUM: 5 vulnerable assets (HIGH RISK)        │
│   Compliance:                                             │
│     FAIL  PCI DSS 4.0                                     │
│     FAIL  FIPS 140-3                                      │
╰───────────────────────────────────────────────────────────╯

Coverage Matrix

| Scanner | Detects | |---------|---------| | Algorithm (regex + AST) | AES variants & modes, DES/3DES/RC4/Blowfish/IDEA, RSA/DSA/ECC sizes, SHA family + MD5, HMAC variants, ChaCha20, Ed25519/X25519, PQC (ML-KEM, ML-DSA, SLH-DSA, FALCON). Regex across 10+ languages plus AST-level resolution (import aliases, aliased objects, constant propagation) via tree-sitter. | | Container | Dockerfile/compose crypto packages, keys/certs baked into layers; OCI / docker save image tarball layer walking → crypto sonames, embedded keys & certs. | | Binary | ELF / PE / Mach-O / JAR / .class / WASM — crypto library sonames & banners (OpenSSL/BoringSSL/GnuTLS/mbedTLS/wolfSSL/NSS/libsodium/BouncyCastle…) and weak-algorithm symbols. | | PKI | JKS/keystore parsing, CA-bundle & trust-store analysis, per-file trust-chain validation, LDAP/LDAPS & Active Directory endpoint discovery. | | KMS/HSM/Vault | PKCS#11 HSMs, AWS/Azure/GCP KMS, AWS Secrets Manager, HashiCorp Vault, CyberArk Conjur, cloud HSMs, Java keystores. | | Network (active) | Live TLS version + cipher + cert-chain enumeration, SSH KEXINIT algorithm enumeration, LDAP/LDAPS, IPsec/IKE reachability. | | Certificate | X.509 PEM/DER/P12 — expiry & 47-day mandate, self-signed, weak signatures (SHA-1/MD5), weak key sizes, SAN/EKU/CA flags. | | Key | Private key files (PEM, OpenSSH, PKCS#8, GPG), file permissions, encryption status, hardcoded keys in source. | | Protocol | TLS 1.0/1.1/SSLv2/SSLv3 detection in nginx/apache/IaC/source. Weak cipher suites (NULL, EXPORT, RC4, 3DES, anonymous). SSH algorithms (ssh-rsa, ssh-dss). HSTS configuration. | | Library | Crypto dependencies + bundled CVE history (node-forge, jsonwebtoken, crypto-js, cryptography, PyJWT, pycrypto, openssl, bouncycastle, phpseclib, ring, etc.). | | Secret | 25+ provider-specific token regexes (AWS, GitHub, Stripe, GCP, Slack, Twilio, etc.) plus Shannon-entropy detection on string literals. | | PQC | Cross-references all findings against NIST FIPS 203/204/205. Migration priority ranking. CNSA 2.0 timeline. |

Compliance Frameworks

--compliance pci-dss,fips-140,hipaa,nist-pqc,cnsa-2,iso-27001,soc2,fedramp

| ID | Standard | |----|----------| | pci-dss | PCI DSS 4.0 — Req 3.5.1, 4.2.1, 8.3.2, 6.4.3, 3.7 | | fips-140 | NIST FIPS 140-3 approved algorithm enforcement | | hipaa | HIPAA Security Rule 164.312, 164.308 | | nist-pqc | NIST FIPS 203 (ML-KEM), 204 (ML-DSA), 205 (SLH-DSA) | | cnsa-2 | NSA Commercial National Security Algorithm Suite 2.0 | | iso-27001 | ISO/IEC 27001:2022 — Annex A cryptographic controls | | soc2 | SOC 2 Trust Services Criteria (CC6.1, CC6.7, CC6.8, CC7.2) | | fedramp | FedRAMP SC-13, SC-8, SC-12, IA-5 |

CycloneDX 1.6 Output (snippet)

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:3ea6c70e-921f-44af-8879-fc9e78c6b359",
  "components": [
    {
      "type": "cryptographic-asset",
      "bom-ref": "algo-...",
      "name": "AES-128-ECB",
      "cryptoProperties": {
        "assetType": "algorithm",
        "algorithmProperties": {
          "primitive": "ae", "parameterSetIdentifier": "128",
          "mode": "ecb", "padding": "unknown",
          "cryptoFunctions": ["encrypt","decrypt"],
          "classicalSecurityLevel": 128, "nistQuantumSecurityLevel": null
        }
      },
      "evidence": { "occurrences": [{ "location": "auth.js", "line": 16 }] }
    }
  ],
  "vulnerabilities": [{ "id": "CWE-327", "ratings": [{ "severity": "high" }] }]
}

QBOM — Quantum Bill of Materials

Every CBOM scan also emits a companion QBOM (*.qbom.json) — the same CycloneDX 1.6 format viewed through the post-quantum lens. Each cryptographic asset is annotated with:

qbom:quantumThreat — shor (public-key, fully broken), grover (symmetric/hash, halved), or none
qbom:harvestNowDecryptLater — whether data protected today is exposed to future decryption
qbom:migrateTo / qbom:migrationStandard — concrete target (ML-KEM / FIPS 203, ML-DSA / FIPS 204, SLH-DSA / FIPS 205)
nistQuantumSecurityLevel and classicalSecurityLevel per algorithm

The QBOM metadata carries a quantum-readiness score/grade, per-family migration priority, a FIPS 203/204/205 mapping, and the CNSA 2.0 (2035) deadline reference.

// *.qbom.json (excerpt)
"metadata": { "properties": [
  { "name": "cbom:bomType", "value": "QBOM" },
  { "name": "qbom:quantumReadinessScore", "value": "8" },
  { "name": "qbom:shorVulnerableInstances", "value": "12" },
  { "name": "qbom:cnsa2Deadline", "value": "2035 (NSA CNSA 2.0)" }
]}

Quality, Testing & Supply Chain

Built to withstand enterprise security review:

| Concern | How it's addressed | |---------|--------------------| | Standards conformance | CBOM + QBOM validated against the official CycloneDX 1.6 JSON schema (bundled in schemas/), not a self-attested check. cbom validate <file> runs the real schema. | | Detection accuracy | Labelled corpus + npm run bench computes precision / recall / F1 per category against ground truth, with a CI regression gate. Negative controls guard against false positives. | | Unit tests | npm test (Node's built-in test runner) — algorithm classification, PQC rules, AST resolution, aggregation, JKS parsing, network target parsing, and schema-valid output. | | CI integration | --format sarif emits SARIF 2.1.0 for GitHub code-scanning / any SARIF consumer. | | Supply-chain | Dependencies pinned to exact versions; production surface is 0 critical / 0 high (npm audit --omit=optional); the TUI is an optional dependency so servers/CI carry no TUI-transitive advisories. Self-SBOM via npm run sbom. See SECURITY.md. |

npm test          # unit tests
npm run bench     # detection accuracy (precision/recall/F1)
npm run sbom      # generate sbom.json (self-SBOM, schema-validated)
npm run audit     # dependency audit

Accuracy note: the bundled benchmark is a curated corpus proving the methodology and gating regressions — it is not a claim of a fixed real-world accuracy figure. Run npm run bench against your own labelled corpus to measure precision/recall on your codebase before relying on the numbers in a contract.

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   CLI        │ ──▶ │   Engine     │ ──▶ │  Aggregator  │
│ commander    │     │  scanner.js  │     │  dedupe+rank │
└──────────────┘     └──────┬───────┘     └──────┬───────┘
                            │                     │
                ┌───────────┴────────────┐        │
                │                        │        ▼
        ┌───────▼─────────┐      ┌──────▼─────┐  ┌──────────────┐
        │  7 Scanners     │      │  Risk      │  │  Output      │
        │ algorithm/cert/ │      │  Scorer +  │  │  CycloneDX/  │
        │ key/proto/lib/  │      │  PQC rules │  │  MD/HTML     │
        │ secret/pqc      │      └────────────┘  └──────────────┘
        └─────────────────┘
                │
        ┌───────▼────────────────┐
        │  data/*.json           │
        │  weak algos · PQC ·    │
        │  secret regexes · CVEs │
        └────────────────────────┘

Exit Codes

| Code | Meaning | |------|---------| | 0 | Scan succeeded; no findings at or above --fail-on level | | 1 | Scan succeeded; findings present at the configured fail threshold | | 2 | Scan error (bad path, parse failure, etc.) |

Contributing

Contributions welcome — see agent.md for the full design spec and roadmap. PRs should:

Add new findings to the appropriate data/*.json rather than hardcoding rules in scanners.
Include a test fixture under test/fixtures/ exercising the new detection.
Document any new CLI flags in this README.