feat(tools): sbom_scan — CycloneDX/SPDX SBOM vulnerability scanner + CLI subcommand (+98 tests)

[manus-use]

Summary

Implements the sbom_scan tool and manus-agent sbom-scan CLI subcommand — a complete SBOM vulnerability scanner that was documented in the README but had zero implementation (no tool file, no CLI dispatch, no tests).

What it does

Parses CycloneDX (JSON) and SPDX (JSON) SBOM files, batch-queries OSV.dev for known vulnerabilities affecting each component, enriches findings with current EPSS exploitation probability scores and CISA KEV membership status, then ranks results by:

1. CISA KEV membership (actively exploited in the wild → first)
2. EPSS score (highest exploitation probability → next)
3. CVSS base score (highest severity → last tiebreak)

CLI Usage

manus-agent sbom-scan bom.json
manus-agent sbom-scan sbom.spdx.json --output json | jq .critical_count

Tool Features

• Format auto-detection: CycloneDX (bomFormat: "CycloneDX") and SPDX (spdxVersion field)
• Package URL (purl) parsing: Supports PyPI, npm, Maven, Go, Cargo, NuGet, RubyGems, Packagist, Pub, Hex, Debian, Alpine, and more
• OSV.dev batch queries: Efficient POST /v1/querybatch (chunked at 1000 per request)
• EPSS bulk enrichment: Batch FIRST.org API lookups (chunked at 100 CVEs per request)
• CISA KEV enrichment: Full catalog fetch + set membership check
• Retry/back-off: Configurable via SBOM_SCAN_MAX_RETRIES and SBOM_SCAN_RETRY_BASE_DELAY env vars
• Graceful degradation: If any enrichment source fails, scan continues with available data
• Deduplication: Same vulnerability reported for the same package+version is counted once
• Strands TOOL_SPEC interface: Compatible with agent tool registry

Tests

98 fully-mocked tests covering:

Category	Count
TOOL_SPEC contract	4
Input validation	5
Format detection	6
Purl parsing	10
CycloneDX extraction	7
SPDX extraction	4
parse_sbom integration	3
HTTP retry	5
OSV batch query	4
EPSS enrichment	4
CISA KEV enrichment	3
CVE extraction	4
CVSS extraction	5
Fix version extraction	4
Finding assembly & ranking	5
Text formatting	3
JSON formatting	3
Full scan integration	3
Tool handler	3
CLI subcommand	6
Edge cases	7

Test results: 1256 passed (baseline 1158 + 98 new), 0 failures.

Files Changed

• src/manus_agent/tools/sbom_scan.py — new tool implementation
• src/manus_agent/cli.py — added sbom-scan to _SUBCOMMANDS, parser, runner, dispatch
• tests/test_sbom_scan.py — 98 comprehensive tests

Design Decisions

• Zero new dependencies — uses only requests (already a project dependency)
• OSV.dev batch API — far more efficient than per-package queries for SBOM-scale workloads
• Ecosystem mapping via purl type — standard Package URL scheme provides reliable ecosystem identification
• Ranking by KEV → EPSS → CVSS — actionability-first ordering (known-exploited before theoretical severity)

Duplicate Check

Checked all 50 open PRs (#138–#187) and 30 merged PRs — no existing open or merged PR implements sbom-scan or an SBOM scanner. Closest PRs:

• feat(tools): OSV.dev affected-package resolver — get_osv_data tool + manus-agent osv CLI #97 (merged, get_osv_data) — single-CVE OSV lookup, not SBOM scanning
• feat(tools): export_sarif — SARIF v2.1.0 vulnerability report exporter + CLI subcommand #183 (open, export_sarif) — exports findings as SARIF, doesn't scan SBOMs
• feat(cli): add manus-agent watchlist subcommand for persistent CVE tracking with bulk EPSS + KEV status #179 (open, watchlist) — persistent CVE tracking, different purpose