feat(tools): cluster_variants — CVE variant clustering across 3 dimensions + CLI subcommand

[manus-use]

Summary

Implements the cluster_variants tool and manus-agent cluster-variants CLI subcommand — both documented in the README but previously unimplemented (zero code existed).

What it does

Groups CVEs related to an input CVE across three cluster dimensions:

1. Same Component/Vendor — finds other CVEs affecting the same software (via NVD CPE configurations)
2. Same CWE Weakness Class — finds CVEs sharing the same weakness type (e.g., all CWE-502 deserialization vulns)
3. Same Researcher/Disclosure Domain — finds CVEs sharing reference/advisory sources (useful for tracking prolific researchers or coordinated disclosures)

This is useful for finding the full attack surface when one CVE is confirmed exploited — you get immediate visibility into related vulnerabilities in the same component, same weakness class, and same disclosure ecosystem.

Usage

manus-agent cluster-variants CVE-2021-44228
manus-agent cluster-variants CVE-2021-44228 --output json | jq .clusters

Design decisions

• Zero new dependencies — uses only requests (already in deps)
• Retry/back-off on all NVD HTTP calls (configurable via NVD_MAX_RETRIES, NVD_RETRY_BASE_DELAY env vars)
• NVD_API_KEY support — optional API key for higher rate limits
• Cross-dimension deduplication — a CVE appearing in multiple cluster dimensions is only reported once
• Graceful degradation — if one dimension fails (network error), others still return results
• Strands TOOL_SPEC interface — follows the existing module-based tool pattern exactly
• Capped queries — limits to 2 vendor:product pairs, 2 CWEs, and 2 reference domains to avoid excessive NVD API calls

Files changed

• src/manus_agent/tools/cluster_variants.py (new) — tool implementation
• src/manus_agent/cli.py — added cluster-variants to _SUBCOMMANDS, parser, runner, and dispatch
• tests/test_cluster_variants.py (new) — 75 fully-mocked tests

Test results

1233 passed, 3 deselected, 3 warnings in 24.46s

(Baseline 1158 + 75 new tests, 0 failures)

Test categories (75 tests)

• TOOL_SPEC contract (4)
• Input validation (5)
• HTTP retry/back-off (5)
• CPE vendor/product extraction (7)
• CWE extraction (7)
• Reference domain extraction (7)
• CVE summarization (5)
• Search by CPE (4)
• Search by CWE (3)
• Search by reference domain (4)
• Build clusters integration (4)
• Text formatting (5)
• Tool handler (5)
• CLI subcommand (5)
• Edge cases (5)

Duplicate check

Checked all 50 open PRs (#137–#186) and 30 most recent merged PRs. No existing open or merged PR implements cluster-variants. Closest PRs checked:

• feat: add cve-neighbors tool and CLI subcommand (+51 tests) #180 (open, cve-neighbors) — finds neighbors by CVSS similarity, NOT by component/CWE/researcher clustering
• feat: add cve-enrich tool and CLI subcommand for multi-source CVE enrichment #170 (open, cve-enrich) — enrichment aggregator, different scope
• feat(tools): classify-refs — NVD reference URL classifier with 89 tests #166 (open, classify-refs) — classifies reference URLs, doesn't cluster CVEs
• feat(tools): OSV.dev affected-package resolver — get_osv_data tool + manus-agent osv CLI #97 (merged, get_osv_data) — single CVE OSV fetch, no clustering