romansok/vuln-analyzer
GitHub: romansok/vuln-analyzer
面向 Claude Code 和 Cursor 的智能体驱动漏洞分析工具，通过 Grype 扫描结合多阶段 AI 代理为开发者生成可读的漏洞分诊报告。
Stars: 0 | Forks: 0
# vuln-analyzer
一款专为 Claude Code（及 Cursor）设计的智能体漏洞分析器。它对目标运行 Grype 扫描，根据 grype 的统一风险对发现的结果进行排序，在聊天中展示**前 5 名的表格**，并为**前 2 名**启动四阶段 agent 分析 pipeline —— 可达性、上下文分析、修复建议以及负责汇总的主 agent —— 进而为每个漏洞生成一份开发者易于阅读的报告。表格中的第 3 至 5 行仅列出以提高安全意识；如需对任何特定 ID 进行深度分析，请请求独立的 `vulnerability-analyzer` agent（例如 `analyze GHSA-…`）。
## 要求
- **OS：** macOS、Linux 或 Windows + WSL。不支持原生 Windows cmd / PowerShell —— 该技能使用 POSIX shell 工具。
- **工具：** `bash` (3.2+)、`date`、`python3` (3.8+) —— 所有这些在 macOS / Linux / WSL 上均已预装。强烈建议安装 `jq` (1.6+)；如果缺失，内置的纯 Python 标准库备选脚本 (`jq-fallback.py`) 将处理相同的操作，且输出字节完全一致。
- **客户端：** Claude Code 或 Cursor，且需配置 [grype MCP server](https://github.com/romansok/grype-mcp/)。
## 如何使用（安装后）
1. 在任意项目中打开 Claude Code（或 Cursor）。一旦以用户级别安装（参见 [INSTALL.md](INSTALL.md)），该技能和四个 agent 即可在任何工作目录下运行。
2. 用纯英文提问。以下任何一项都会触发该技能：
- *"Scan /Users/me/repo for vulnerabilities."*
- *"Audit dependencies in this project."*（使用您的当前工作目录）
- *"Run grype on /path/to/project."*
- *"Check the security of this codebase."*
该技能**仅扫描本地目录。** 如果您传入 image ref、SBOM、PURL 或 CPE，它将婉拒并提示您直接运行 grype。如需在不扫描的情况下分析特定的 advisory id，请直接请求 `vulnerability-analyzer` agent（参见下方的[独立分析器](#standalone-analyzer)）。
3. 要独立分析单个漏洞（不进行扫描）：
- *"Analyze CVE-2023-32314."*
- *"Tell me about GHSA-whpj-8f3w-67p5."*
- *"Explain https://github.com/advisories/GHSA-whpj-8f3w-67p5."*
## 您将获得什么
- **聊天中内联展示：**
- 扫描摘要行 —— 目标、总匹配数、独立漏洞数。
- 严重性统计 —— Critical / High / Medium / Low / Negligible（全五种，包括为零的情况）。
- **前 5 名 Markdown 表格** —— 按风险排序，列：`VulnID | Risk | Severity | CVSS | PURL(s) | Fix | Description`。
- **前 2 名发现中每项对应的一个综合信息块**，结构化设计以便于快速分类评估：
- **Bug 类别** —— CWE(s)。
- **攻击面** —— *谁* 可以利用此漏洞，*从哪里* 利用，*需要什么权限*（例如 `network (unauthenticated remote)`、`api (admin token required)`、`local (must execute on the host)`）。可直接复制粘贴到 Slack 消息中。
- **攻击者能获得什么** —— 具体的后果（在 worker 上实现 RCE、窃取 session cookie、对请求处理程序发起 DoS）—— 而不是机制。
- **在此 codebase 中可达吗？** —— 结论 + 找到时的 file:line 证据。
- **应对措施** —— 升级路径（升级 / 配置开关 / 无上游修复）。
- **变通方案（始终提供）** —— 当升级受阻（peer-dep 冲突、vendored fork、EOL 框架、等待 PR 审查）时，您**今天**就可以直接插入的一段具体的代码或配置片段。代码块带有语言标记，外加一句成本的描述。
- **为什么重要（10 秒解释）** —— 通用开发者能看懂的一行示例。
- **置信度** —— High / Medium / Low + 什么能提升置信度。
默认情况下，表格中的第 3 至 5 行不会被深入分析 —— 可按需向独立的 `vulnerability-analyzer` agent (`analyze `) 请求分析其中任何一项。
- **磁盘上（仅当总发现数 > 5 时）：**
- `vulnerabilites_report_.md` 将生成在您的调用 cwd 中。它**仅**包含每个匹配项的完整 Markdown 表格 —— 每个发现的所有 artifact 位置。聊天中会打印其绝对路径。
## 架构
```
SKILL.md (orchestrator)
├─ Scans with mcp__grype__scan (output_format=json)
├─ Caches JSON; reads it only via jq snippets
├─ Ranks, renders, writes the report file
└─ Dispatches 2 × Task(vulnerability-analyzer) IN PARALLEL — one for each of the top-2 vulns
│
▼
vulnerability-analyzer (lead) ×2 concurrent instances
1. Validates the input (CVE / GHSA / advisory URL).
2. Resolves vuln context (cache file, fetched URL, or self-gathered).
3. Extracts the vulnerable symbols (functions, classes, sinks,
config toggles) from the advisory — this is what reachability
needs to actually search for.
4. Fans out 3 Task calls IN PARALLEL:
• reachability-analyzer — receives the extracted symbols and decides how/where to grep.
• context-analyzer — explains the bug class in plain English (uses local CWE playbook).
• remediation-analyzer — primary fix + ranked workarounds, informed by the symbols.
5. Synthesizes one developer-readable block and returns it.
The SKILL collects both returned blocks, then emits them inline in the
risk-sorted order of the top-5 table — first the #1 row's synthesis,
then the #2 row's. Two-tier parallelism (2 leads × 3 sub-agents each
= 6 concurrent sub-agents) brings wall time down to roughly the
slowest single chain.
```
## 仓库结构
与工具无关的源代码 —— `install.sh` 脚本会根据您传入的标志，将这些内容复制到 `~/.claude/` 或 `~/.cursor/`（或项目本地等效目录）中。
```
.
├── install.sh Installs into Claude Code or Cursor.
├── README.md
├── INSTALL.md
├── LICENSE
├── agents/ The four agents (lead + three sub-agents).
│ ├── vulnerability-analyzer.md
│ ├── reachability-analyzer.md
│ ├── context-analyzer.md
│ └── remediation-analyzer.md
├── skills/
│ └── vuln-analyzer/
│ ├── SKILL.md Thin orchestrator. Highest authority.
│ └── references/ Read by the skill / agents on demand.
│ ├── jq-snippets.md Canonical jq commands.
│ ├── jq-fallback.py Python stdlib-only fallback for jq.
│ ├── output-templates.md Exact markdown for tables and synthesis blocks.
│ ├── grype-schema-cheatsheet.md Field map for the grype JSON.
│ └── cwe/ One file per seeded CWE + an index.
│ ├── index.md
│ └── CWE-20.md … CWE-1321.md
└── settings/
└── claude-permissions.json Optional. Claude-only. Pre-approves common Bash + WebFetch hosts.
```
安装后，agent 和技能将位于您的 AI 助手配置目录下：
- Claude Code：`~/.claude/agents/*.md` 和 `~/.claude/skills/vuln-analyzer/`
- Cursor： `~/.cursor/agents/*.md` 和 `~/.cursor/skills/vuln-analyzer/`
运行时 artifacts（`.cache/grype_scan_.json`、`.cache/vuln_.json`）会在扫描时写入已安装的技能目录下；`vulnerabilites_report_.md` 会写入用户的 cwd。这些均不属于此仓库。
## 排序顺序
发现结果将按以下优先级进行排序：
1. `vulnerability.risk` —— grype 的统一得分（融合了 CVSS、EPSS、KEV、修复可用性）。降序排列。
2. 最大 `cvss[].metrics.baseScore`。降序排列。
3. 严重性区间：Critical → High → Medium → Low → Negligible。
4. 漏洞 ID 字母顺序（在平局时保证完全确定性）。
前 5 名是去重后的漏洞 ID —— 同一 ID 出现在多个 PURL 上时，在内联表格中会合并为单行。报告文件会保留每个 artifact 的独立行。
## 独立分析器
主 agent (`vulnerability-analyzer`) 可以在**技能流程之外**工作 —— 您可以在任何时候直接调用它，以获得针对单个漏洞的开发者级分析，而无需先运行扫描。
它接受自然语言：
```
analyze CVE-2024-1234
what does GHSA-whpj-8f3w-67p5 mean for us?
explain RUSTSEC-2024-0001
look at https://github.com/advisories/GHSA-xxxx-xxxx-xxxx
analyze https://security-tracker.debian.org/tracker/CVE-2024-1234
```
验证顺序：**先 URL，后 ID。** 如果输入包含 URL，其主机必须在白名单中；该 URL 将成为唯一的真实来源。否则，输入必须看起来像一个 advisory id —— 即任何形如 `-` 的 token，其中 prefix 为大写字母。
支持的 ID prefix（agent 会识别 prefix 并选择正确的数据库）：
| Prefix | Source |
| --- | --- |
| `CVE-` | MITRE / NVD |
| `GHSA-` | GitHub Security Advisories |
| `OSV-` | OSV.dev |
| `SNYK-` | Snyk |
| `PYSEC-` | Python Packaging Advisory |
| `RUSTSEC-` | Rust Security Advisory |
| `GO-` | Go vuln DB |
| `DSA-`, `DLA-` | Debian Security / Long-Term |
| `RHSA-` | Red Hat Errata |
| `USN-` | Ubuntu Security Notice |
| `ALAS-` | Amazon Linux |
| `ELSA-` | Oracle Linux |
| `ALSA-` | AlmaLinux |
| (其他) | 回退至 OSV → WebSearch |
根据输入类型的不同行为：
- **纯 ID** → agent 会为该 prefix 选择规范的抓取 URL，收集上下文，提取易受攻击的 symbols，并调度三个子 agent。可达性分析会返回 `source-not-available`，因为没有可搜索的项目根目录 —— 但上下文分析和修复建议仍会产生有用的输出。
- **Advisory URL** → 该 URL 被视为**唯一**的真实来源。不进行其他查询。
- **无效 / 无法识别** → 一句拒绝语。不调度子 agent。
当由技能调用时（在扫描期间），同一个 agent 会接收到带有上下文文件路径和项目根目录的结构化提示 —— 它遵循相同的流程，但可达性分析有真实的源代码可供 grep。
## 注意事项与说明
- **跨平台。** 该技能使用 `jq`、`awk`、`bash` 和 `date` —— 这些 POSIX 工具在 macOS / Linux / WSL 上开箱即用。不支持原生 Windows；请使用 WSL 或 git-bash。有关安装程序命令，请参见 [INSTALL.md](INSTALL.md#1-prerequisites)。
- **JSON 不进入上下文。** 完整的 grype JSON 会写入已安装技能下的 `.cache/` 目录中，仅通过 Bash 的 `jq` 读取。模型永远不会加载它。
- **仅目录扫描。** 该技能专门针对本地目录 —— image refs、SBOM 文件、PURL 和 CPE 在第一阶段即被拒绝，并提示直接运行 grype。独立的 `vulnerability-analyzer` agent（在技能之外调用）是在不扫描的情况下分析特定 advisory id 的方法。
- **可达性分析返回 `source-not-available`** 仅发生在独立模式下（即在技能之外调用 agent 且没有项目根目录的情况下）。技能扫描始终具有真实的源代码树。
- **文件名拼写。** `vulnerabilites_report_.md` 保留了原始规范中的拼写（维护者知道 "vulnerabilities" 是标准拼写）。
- **Gitignore。** 如果此目录成为 git 仓库，请将 `.cache/` 和 `vulnerabilites_*.md` 添加到 `.gitignore` 中。
## 向剧本中添加新的 CWE
在此仓库中：
```
1. Copy the template from skills/vuln-analyzer/references/cwe/index.md (bottom).
2. Save as skills/vuln-analyzer/references/cwe/CWE-.md.
3. Add a row to skills/vuln-analyzer/references/cwe/index.md.
4. Re-run ./install.sh to publish the change to your installed location.
```
上下文分析器仅读取与每次扫描相关的文件，因此剧本可以无限增长，而不会增加每次运行的上下文负担。
标签：Angular, CISA项目, Claude, CVE检测, Grype, MCP, Web报告查看器, 人工智能代理, 代码安全审计, 依赖扫描, 应用安全, 模型提供商, 漏洞分析, 自动化攻击, 路径探测, 逆向工具