allsmog/Kuzushi
GitHub: allsmog/Kuzushi
Kuzushi 是一款融合传统 SAST 与 AI Agent 的智能代码安全扫描器，通过 AI 深度分诊大幅降低误报率，并可自动生成 PoC 漏洞利用以证明漏洞的真实可利用性。
Stars: 1 | Forks: 0
# Kuzushi — AI 安全扫描器，只展示真实的漏洞
[](https://github.com/allsmog/Kuzushi/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/kuzushi)
[](LICENSE)
SAST 工具经常“狼来了”。Semgrep 在你的代码库中发现了 500 个问题。其中 480 个是误报。你花费数小时对这一堵噪音墙进行分诊，却依然错过了第 247 行真正的漏洞。
Kuzushi 运行相同的扫描器，然后发送一个 AI Agent 去调查每一个发现 —— 阅读实际的代码，追踪数据流，检查是否经过净化。它会告诉你哪些发现是真的，哪些是噪音，并可选地通过构造可工作的 PoC 来证明可利用性。
```
npx kuzushi /path/to/your/repo
```
无需安装。无需配置文件。只需指向一个代码仓库。
## 快速开始
前置条件：Node 22+，以及 API 密钥或 Claude Code OAuth 登录。
```
# 使用 Claude Code OAuth（无需 API key — 使用您的 Claude 登录）
npx kuzushi /path/to/your/repo
# 使用 Anthropic API key
export ANTHROPIC_API_KEY=sk-ant-...
npx kuzushi /path/to/your/repo
# 使用 OpenAI
export OPENAI_API_KEY=sk-...
npx kuzushi /path/to/repo --model openai:gpt-4o
# 使用 Google、Groq、Mistral 或 15+ 其他提供商
npx kuzushi /path/to/repo --model google:gemini-2.0-flash
```
如果你没有安装扫描器，Kuzushi 会自动下载 Opengrep。零依赖管理。
## 问题所在
**仅使用 SAST 扫描器** 召回率高但精确度极差 —— 它们标记所有*可能*是漏洞的东西，让你淹没在误报中。团队花费数小时进行分诊，产生告警疲劳，最终停止查看。
**仅使用 LLM** 能够推理代码，但在从头扫描时会产生幻觉 —— 当你问“在这个仓库中查找漏洞”时，误报率高达 95% 以上。
**Kuzushi 结合了两者。** SAST 信号缩小了搜索空间。AI 推理消除了误报。结果：在漏洞分类上接近人类研究人员的符合率。
## 你将获得什么
对于每一个发现，Kuzushi 会生成：
- **判定** — `true_positive`（真阳性），`false_positive`（假阳性），或 `needs_review`（需审查）
- **置信度** — 0.0 到 1.0
- **理由** — 为什么 Agent 得出该判定，引用特定的代码行
- **验证步骤** — 人工审查者可遵循的 2-6 个可操作步骤
- **修复建议** — 适用时的建议补丁
- **PoC 漏洞利用**（带 `--verify`）— 证明漏洞可被利用的具体概念验证 Payload
- **成本** — 每次发现分诊和验证的美元成本
终端报告首先显示真阳性，然后是需审查的项目。假阳性被计数但隐藏。你只看到重要的内容。
## 工作原理
```
┌─────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────┐ ┌──────────┐
│ Scanners │────▶│ AI Triage │────▶│ Verification │────▶│ Patch │────▶│ Report │
│ Semgrep │ │ Investigate │ │ Construct │ │ Generate │ │ TP only │
│ CodeQL │ │ each finding │ │ PoC exploits │ │ & verify │ │ + export │
│ Agentic │ │ with context │ │ (optional) │ │ (opt-in) │ │ + stream │
└─────────────┘ └──────────────┘ └──────────────┘ └─────────┘ └──────────┘
```
1. **上下文收集** — 自动检测你的技术栈、框架、认证模式、ORM 和净化库
2. **代码图** — 通过静态分析 + LLM 填充空白构建持久的入口点到汇点图，用于感知可达性的分诊
3. **威胁建模** — Randori PASTA 插件（作为 `@kuzushi/randori-plugin` 发布）执行 4 阶段威胁分析：业务目标、技术范围、DFD 分解，以及带有 ATT&CK/CAPEC/OWASP 映射和 5 因子概率评分的 STRIDE 威胁场景。所有威胁线索都会注入到每个检测器的提示词中。
4. **威胁知情狩猎** — 为每个 DFD 外部实体（用户、服务、攻击者）生成一个对抗性 Claude Agent，以 CTF 风格从每个参与者的角度搜寻漏洞
5. **扫描** — 并发运行 Semgrep、CodeQL 和/或 Agentic 扫描器；13+ 个专用检测器（SSRF、SQLi、XSS、命令注入、XXE、反序列化、NoSQL 注入、模板注入、原型污染、竞态条件、供应链、GraphQL、机密/加密、认证逻辑、边缘情况）；多策略模式对每个漏洞类别运行 2-4 种分析方法
6. **分类漏斗** — 廉价的单 Token 预过滤器在昂贵的分诊之前移除约 80% 的噪音
7. **去重** — 跨扫描器对等效发现进行指纹识别和合并
8. **增量跳过** — 在先前运行中已分诊的发现会被自动跳过
9. **AI 分诊** — 一个 Agent 调查每个发现，带有预加载的源上下文、代码图路径、证据链和特定 CWE 知识模块；批量丢弃的发现自动升级为单独分诊
10. **变体分析** — 确认的 TP 触发在代码库中自动搜索相似模式
11. **验证**（可选）— 为真阳性构造具体的 PoC 漏洞利用 Payload
12. **PoC Harness 生成**（可选）— 生成可运行的漏洞利用脚本，带有迭代执行反馈
13. **动态分析**（可选）— 在 Docker Sandbox 中执行 Harness 以确认可利用性
14. **自动补丁**（可选）— 在一次性 Git Worktree 中生成、验证和重新验证补丁
15. **报告** — 终端显示 + 导出为 SARIF、Markdown、JSON、CSV 或 JSONL；可选的 SSE 实时流
## CI 集成
### GitHub Actions
```
name: Security Scan
on: [push, pull_request]
jobs:
kuzushi:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npx kuzushi . --sarif results.sarif --quality-gate --fail-on-tp
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: results.sarif
```
### 质量门禁
```
kuzushi
--quality-gate # fail CI on threshold violations
kuzushi --fail-on-tp # fail if any high/critical TP is found
kuzushi --sarif results.sarif # export SARIF for GitHub Code Scanning
```
## 核心特性
**供应商无关的 LLM 运行时** — 支持 Anthropic、OpenAI、Google、Groq、Mistral 和其他 15+ 个提供商。使用 `--model provider:modelId` 在运行时切换模型。分诊使用更便宜的模型，验证使用高级模型。
**漏洞利用验证** — 超越分类。构造具体的 PoC Payload（SQL 注入字符串、XSS 向量等），证明一个发现是可利用的，而不仅仅是理论上可能的。
**加密行为测试** — 在 Docker Sandbox 中为加密误用发现生成并执行行为测试 Harness。检测时序侧信道、ECB 模式、弱哈希、弱 PRNG 等。
**IRIS 风格污点分析** — 受 IRIS 论文（ICLR 2025）启发的 LLM 驱动 CodeQL 污点分析。LLM 为项目选择相关的 CWE 类别，动态编写 CodeQL 提取查询（与语言、框架无关），标记候选项，生成 TaintTracking 配置，并在编译失败时迭代优化查询。无需模板，无硬编码框架检测。
**Randori PASTA 威胁建模** — 内置 `@kuzushi/randori-plugin` 作为依赖。通过 Claude Code 插件运行 4 阶段 PASTA 分析（目标、范围、DFD 分解、STRIDE 威胁）。威胁线索被注入到所有检测器提示词中以进行威胁知情扫描。包含 ATT&CK、CAPEC 和 OWASP 映射。
**威胁知情狩猎** — 为威胁模型识别的每个 DFD 外部实体生成对抗性 Claude Agent。每个 Agent 作为该参与者（最终用户、管理员、外部服务、LLM Agent）探索代码库，寻找可利用的路径。发现被去重并输入分诊/验证。
**自动规则生成** — 已验证的可利用发现自动生成自定义 Semgrep 规则。规则持久化到 `.kuzushi/custom-rules/` 并在后续扫描中自动加载，创建一个反馈循环，使扫描器随着时间的推移变得更聪明。规则会根据原始发现进行验证，如果不匹配则移除。
**差异感知污点分析** — 将分析范围缩小到自基础分支以来更改的文件。在 CI 中运行 `--taint-diff-base main`，仅分析 PR 中的新内容。
**可恢复运行** — 将管道状态保存到 SQLite。扫描被中断？`--resume` 从中断的地方准确继续。
**补丁合成** — `kuzushi patch --fingerprint ` 在一次性 Git Worktree 中生成并验证安全补丁，而不触碰你的工作副本。
**15+ 个专用检测器** — 用于命令注入、XXE、不安全反序列化、SSRF、NoSQL 注入、模板注入、原型污染、竞态条件、供应链、GraphQL 安全、机密/加密、代码配置、认证逻辑、边缘情况和加密行为测试的专用检测任务。每个都有特定漏洞类别的提示词、反幻觉约束和多视角分析。所有检测器都接收威胁模型线索以进行威胁知情扫描。
**分类漏斗** — 使用廉价模型的单 Token LLM 预过滤器在昂贵的分诊之前移除约 80% 的误报，大幅降低每次扫描成本。
**源代码预读** — 分诊 Agent 接收预加载的已标记源文件（发现周围 50 行），消除了冷启动工具调用并提高了推理准确性。
**LLM 代码图** — 构建一个持久的代码图，通过中间件、控制器、服务和数据访问层追踪入口点。来自导入分析的静态骨架 + 用于动态调度、DI 和回调模式的 LLM 辅助填充。将图上下文输入分诊以获得更好的推理。
**多策略分析** — 对每个漏洞类别运行 2-4 种不同的分析方法（语法模式匹配、数据流追踪、第一性原理推理、基于执行的证明），并在策略一致时合并结果并提升置信度。从确认的多策略发现中自动生成可重用的 Semgrep 规则。
**13 个 CWE 知识模块** — SQL 注入、XSS、SSRF、命令注入、路径遍历、认证绕过、反序列化、竞态条件、加密、XXE、文件上传、IDOR 和 NoSQL 注入的领域特定知识 —— 包括危险模式、安全模式、绕过技术和修复示例。
**增量扫描** — 跨运行跳过未更改发现的重新分诊。跟踪上次扫描的提交，计算文件差异，并通过导入图的依赖感知失效来扩展重新扫描范围。
**带有闭环验证的自动补丁** — 确认漏洞后，在一次性 Git Worktree 中自动生成补丁，验证它（应用、构建、测试），然后在修补后的代码上重新运行扫描器以确认漏洞已消失。
**实时流** — SSE 服务器实时流式传输管道事件（`--stream`）。使用 `curl`、`EventSource` 或任何 SSE 客户端连接，以在发现被分诊时查看它们。
**审计日志** — 可选的 JSONL 审计跟踪，记录每个 Agent 决策，用于调试、问责和合规记录。
## 扫描器插件
| Scanner | Description | Auto-download |
|---------|-------------|---------------|
| `semgrep` (默认) | 通过 Opengrep/Semgrep 的传统 SAST | Yes |
| `codeql` | 通过 GitHub CodeQL CLI 的语义数据流/污点分析 | No (opt-in) |
| `agentic` | AI 驱动扫描器 — 带有只读代码仓库工具的 LLM | N/A |
| `taint-analysis` | IRIS 风格 LLM 驱动 CodeQL 污点分析 — 动态 CWE 选择、LLM 生成的查询、迭代优化 | No (opt-in) |
```
kuzushi --scanners semgrep,codeql # run multiple scanners
kuzushi --scanners agentic # AI-only scan
```
所有命令
### Scan（扫描，默认）
```
kuzushi # scan with defaults
kuzushi --scanners codeql
kuzushi --scanners semgrep,codeql
kuzushi --scanners semgrep,agentic
kuzushi --severity ERROR # only ERROR-level findings
kuzushi --max 20 # triage top 20 findings only
kuzushi --model anthropic:claude-sonnet-4-6 # use a different model
kuzushi --triage-model openai:gpt-4o # separate model for triage
kuzushi --triage-max-turns 15 # triage agent turn budget
kuzushi --api-key sk-ant-... --base-url https://api.example.com/ # custom API endpoint
kuzushi --fresh # clear prior results, re-triage everything
kuzushi --db ./my.sqlite3 # custom database path
kuzushi --resume # resume the most recent interrupted run
kuzushi --resume # resume a specific run by ID
```
### Verification（验证）
```
kuzushi --verify # enable exploit verification for TPs
kuzushi --verify --verify-model openai:gpt-4o-mini # cheaper model for verification
kuzushi --verify --verify-max-turns 20
kuzushi --verify --verify-concurrency 3
kuzushi --verify --verify-min-confidence 0.7 # skip low-confidence TPs
```
### PoC Harness Generation（PoC Harness 生成）
```
kuzushi --verify --poc-harness # generate exploit scripts for verified findings
kuzushi --verify --poc-harness --poc-harness-model openai:gpt-4o-mini
kuzushi --verify --poc-harness --poc-harness-max-turns 25
kuzushi --verify --poc-harness --poc-harness-concurrency 2
```
### Dynamic Analysis（动态分析）
```
kuzushi --verify --poc-harness --dynamic-analysis # execute harnesses to confirm/reject findings
kuzushi --verify --dynamic-analysis --dynamic-max-candidates 10
kuzushi --verify --dynamic-analysis --dynamic-min-score 8
```
### Patch Synthesis（补丁合成）
```
kuzushi patch --fingerprint # synthesize and validate a patch
kuzushi patch --fingerprint --build-cmd "npm run build"
kuzushi patch --fingerprint --test-cmd "npm test" --max-iterations 5
```
### Code Graph（代码图）
```
kuzushi --code-graph # enable LLM-powered code graph (entry-point-to-sink tracing)
```
### Multi-Strategy Analysis（多策略分析）
```
kuzushi --multi-strategy # adaptive mode: run cheapest strategy first, exit early if confident
kuzushi --multi-strategy-full # run all strategies in parallel for maximum coverage
kuzushi --multi-strategy-budget 3.0 # per-finding budget across all strategies (USD)
kuzushi --multi-strategy-auto-rules # generate Semgrep rules from confirmed multi-strategy findings
```
### Auto-Patch (Closed-Loop)（自动补丁-闭环）
```
kuzushi --verify --auto-patch # patch exploitable findings, re-verify
kuzushi --verify --auto-patch --auto-patch-after triage # patch any TP (broadest trigger)
kuzushi --verify --auto-patch --auto-patch-after poc # patch only after PoC proves it
kuzushi --auto-patch --patch-verify-depth triage # re-run scanner + triage on patched code
kuzushi --auto-patch --patch-verify-depth full # full pipeline re-verify (most thorough)
kuzushi --auto-patch --patch-concurrency 3 # parallel patch synthesis tasks
```
### Streaming（流式传输）
```
kuzushi --stream # start SSE server on auto-assigned port
kuzushi --stream --stream-port 3001 # start SSE server on specific port
# 然后在另一个终端中：
curl -N http://localhost:3001/events # watch live pipeline events
```
### Crypto Behavioral Testing（加密行为测试）
```
kuzushi --crypto-behavioral-test # generate & run behavioral tests for crypto misuse findings
```
### Diff-Aware Taint（差异感知污点分析）
```
kuzushi --taint-diff-base main # only taint-analyze files changed since main
kuzushi --taint-diff-base main --taint-diff-mode delta # emit only findings intersecting the diff
kuzushi --taint-diff-base main --taint-diff-mode baseline # merge cached + rerun for full baseline
```
### Output & Observability（输出与可观测性）
```
kuzushi --output report.md # export markdown report
kuzushi --sarif results.sarif # export SARIF v2.1.0
kuzushi --json results.json # export JSON report
kuzushi --csv results.csv # export CSV report
kuzushi --jsonl results.jsonl # export JSONL report
kuzushi --audit-log # write agent activity to .kuzushi/runs/{runId}/
kuzushi --verbose # show debug-level runtime diagnostics
kuzushi --no-context # disable repo context gathering
```
### Retry（重试）
```
kuzushi --max-triage-retries 3 # retry failed triage calls (default: 2)
kuzushi --max-verify-retries 3 # retry failed verification calls (default: 2)
kuzushi --retry-backoff-ms 10000 # initial backoff delay (default: 5000)
```
### Config（配置）
```
kuzushi config get # show all config
kuzushi config get model # show one key
kuzushi config set model anthropic:claude-sonnet-4-6
kuzushi config set scanners semgrep,agentic
kuzushi config set scannerConfig.codeql.dbPath ./codeql-db
kuzushi config set scannerConfig.codeql.suite javascript-security-extended
kuzushi config set scannerConfig.semgrep.binary opengrep
kuzushi config set scannerConfig.semgrep.configFlag auto
kuzushi config set scannerConfig.agentic.model anthropic:claude-sonnet-4-6
kuzushi config set scannerConfig.agentic.maxFindings 25
kuzushi config set severity ERROR,WARNING,INFO
kuzushi config set verify true
kuzushi config set verifyMinConfidence 0.7
kuzushi config set auditLog true
kuzushi config validate --repo . # validate the effective config for this repo
kuzushi config unset model # reset to default
kuzushi config path # print config file location
```
全局配置位于 `~/.kuzushi/config.json`。可选的项目覆盖可以位于 `/.kuzushi/config.json`。CLI 标志覆盖配置值。
**仓库本地配置沙箱：** 默认情况下，项目级配置文件（`/.kuzushi/config.json`）是沙箱化的 —— 可能执行代码或访问外部系统的键（例如 `hooks`、`externalTasks`、`pocExecute`、扫描器二进制路径）会被静默剥离。这可以防止克隆的代码库更改你的运行时行为。当你信任代码仓库时，传递 `--trust-repo-config` 以选择加入完整的项目配置。
安全说明：`agentRuntimeConfig.apiKey` 以明文形式存储在配置文件中。对于一次性运行，建议使用 `--api-key`，或从你的 Shell/Secrets Manager 中使用 `ANTHROPIC_API_KEY`。
配置参考
| Key | Default | Description |
| --- | --- | --- |
| `model` | `anthropic:claude-sonnet-4-6` | 用于器和默认分诊模型的 LLM 模型 |
| `triageModel` | _(uses `model`)_ | 覆盖分诊 Agent 使用的模型 |
| `triageBatchModel` | `anthropic:claude-haiku-4-5` | 用于批量分诊的模型（回退到 `triageModel`，然后是 `model`） |
| `triageMaxTurns` | `null` (uses runtime default: `10`) | 每次分诊调用的最大 Agentic 轮次 |
| `scanners` | `["semgrep"]` | 要运行的扫描器插件，按顺序 |
| `severity` | `["ERROR","WARNING"]` | Semgrep 严重性过滤器 |
| `excludePatterns` | `["test","tests","node_modules",...]` | 要跳过的目录/Glob |
| `scannerConfig` | `{ semgrep: {...}, agentic: {...}, codeql: {...} }` | 按扫描器 ID 键入的每个扫描器配置块 |
| `busBackend` | `"in-process"` | 消息总线传输（`in-process`） |
| `triageConcurrency` | `5` | 并行 LLM 分诊调用 |
| `scanMode` | `"concurrent"` | 扫描器执行模式（`sequential` 或 `concurrent`） |
| `enabledTasks` | `["context-gatherer", "context-enricher", "app-model-build", "threat-scenario-build", "secrets-crypto-detect", "crypto-behavioral-test", "code-config-detect", ...]` | 除了扫描器之外要启用的 Agent 任务 |
| `agentRuntimeBackend` | `"claude"` | Agent 运行时后端（`claude` 或 `pi-ai`） |
| `verify` | `false` | 启用可利用性验证 |
| `verifyModel` | _(uses `triageModel` or `model`)_ | 覆盖验证 Agent 的模型 |
| `verifyMaxTurns` | `15` | 验证 Agent 的最大轮次 |
| `verifyConcurrency` | `3` | 并行验证调用 |
| `verifyVerdicts` | `["tp"]` | 要验证的分诊判定 |
| `verifyMinConfidence` | `0` | 触发验证的最小分诊置信度 (0-1) |
| `pocHarness` | `false` | 启用验证后的 PoC Harness 生成（需要 `--verify`） |
| `pocHarnessModel` | _(uses `triageModel` or `model`)_ | 覆盖 PoC Harness Agent 的模型 |
| `pocHarnessMaxTurns` | `20` | PoC Harness Agent 的最大轮次 |
| `pocHarnessConcurrency` | `2` | 并行 PoC Harness 生成调用 |
| `cryptoBehavioralTestEnabled` | `false` | 为加密误用发现启用加密行为测试 |
| `cryptoBehavioralMaxFindings` | `10` | 每次运行为其生成行为测试的最大发现数 |
| `cryptoBehavioralTimeoutMs` | `120000` | 每个 Harness 的执行超时（毫秒） |
| `cryptoBehavioralPerFindingBudgetUsd` | `1` | 每个 Harness 发现生成的成本预算（美元） |
| `codeGraphEnabled` | `true` | 启用 LLM 驱动的代码图构建和丰富 |
| `multiStrategyMode` | `"off"` | 多策略分析模式（`off`、`adaptive`、`full`） |
| `multiStrategyBudgetUsd` | `2.0` | 跨所有策略的每个发现预算（USD） |
| `autoPatchEnabled` | `false` | 在管道中启用自动补丁生成 |
| `autoPatchAfter` | `"verify"` | 自动补丁的触发阈值（`verify`、`poc`、`triage`） |
| `patchVerifyDepth` | `"scanner"` | 打补丁后的重新验证深度（`scanner`、`triage`、`full`） |
| `patchConcurrency` | `2` | 最大并发补丁合成任务 |
| `incrementalCache` | `true` | 启用增量扫描（跨运行跳过未更改的发现） |
| `incrementalDepTracking` | `true` | 在重新扫描范围中包含已更改文件的导入者 |
| `streamingEnabled` | `false` | 为实时管道事件启用 SSE 流式服务器 |
| `streamingPort` | `0` (auto) | SSE 流式服务器的端口 |
| `enableContextGathering` | `true` | 在分诊前运行代码仓库上下文分析 |
| `auditLog` | `false` | 将 Agent 活动写入 JSONL 审计文件 |
| `reportOutput` | _(unset)_ | 将 Markdown 报告输出写入此路径 |
| `sarifOutput` | _(unset)_ | 将 SARIF v2.1.0 输出写入此路径 |
| `jsonOutput` | _(unset)_ | 将 JSON 报告写入此路径 |
| `csvOutput` | _(unset)_ | 将 CSV 报告写入此路径 |
| `jsonlOutput` | _(unset)_ | 将 JSONL 报告写入此路径 |
| `maxTriageRetries` | `2` | 重试失败的分诊调用 |
| `maxVerifyRetries` | `2` | 重试失败的验证调用 |
| `maxPocHarnessRetries` | `2` | 重试失败的 PoC Harness 生成调用 |
| `retryBackoffMs` | `5000` | 初始重试退避延迟（毫秒） |
| `retryBackoffMultiplier` | `2` | 指数退避乘数 |
配置示例：
```
{
"scanners": ["semgrep", "codeql", "agentic"],
"scanMode": "concurrent",
"triageConcurrency": 3,
"verify": true,
"verifyMinConfidence": 0.7,
"auditLog": true,
"cryptoBehavioralTestEnabled": false,
"enabledTasks": ["context-gatherer", "context-enricher", "app-model-build", "threat-scenario-build", "secrets-crypto-detect", "crypto-behavioral-test", "code-config-detect"],
"scannerConfig": {
"codeql": { "dbPath": "./codeql-db", "suite": "javascript-security-extended" },
"semgrep": { "binary": "opengrep", "configFlag": "auto" },
"agentic": { "model": "anthropic:claude-sonnet-4-6", "maxFindings": 20 }
}
}
```
### 环境变量
| Variable | Required | Description |
| --- | --- | --- |
| `ANTHROPIC_API_KEY` | 当使用 `anthropic:*` 模型时 | 用于 pi-ai 后端的 Anthropic API 密钥 |
| `OPENAI_API_KEY` | 当使用 `openai:*` 模型时 | 用于 pi-ai 后端的 OpenAI API 密钥 |
| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | 当使用 `google:*` 模型时 | 用于 pi-ai 后端的 Google API 密钥 |
CodeQL 设置
`codeql` 扫描器需要单独安装 [CodeQL CLI](https://github.com/github/codeql-cli-binaries/releases)。与 Semgrep 不同，它**不会自动下载**（CLI 约 500 MB，且需要接受 GitHub 的许可）。
安装它：
```
# 通过 GitHub CLI（推荐）：
gh extension install github/gh-codeql && gh codeql install-stub
# 或直接从以下地址下载：
# https://github.com/github/codeql-cli-binaries/releases
```
Kuzushi 按以下顺序查找 CodeQL 二进制文件：
1. 你 PATH 上的 `codeql`
2. 之前放置在 `~/.kuzushi/bin/codeql` 的二进制文件
3. 如果未找到，则失败并显示安装说明
CodeQL 是**可选的** —— 默认扫描器列表是 `["semgrep"]`。要启用它：
```
kuzushi --scanners codeql # CodeQL only
kuzushi --scanners semgrep,codeql # both scanners
kuzushi config set scanners semgrep,codeql # persist as default
```
CodeQL 在运行查询之前从你的源代码构建数据库。你可以通过指向预构建的数据库来跳过此步骤：
```
kuzushi config set scannerConfig.codeql.dbPath ./codeql-db
```
污点分析设置
`taint-analysis` 扫描器是一个基于 CodeQL 的多通道管道，使用 LLM 辅助分类来标记源、汇、净化器和摘要。它需要：
1. **CodeQL CLI** — 与 `codeql` 扫描器的要求相同
2. **Python 3** — 污点分析脚本用于查询生成
污点分析模板、引用和脚本作为 [`@kuzushi/augur`](https://www.npmjs.com/package/@kuzushi/augur) npm 包捆绑，并随 `pnpm install` 自动安装。无需手动克隆或 `TAINT_ANALYSIS_PATH` 设置。
```
kuzushi --scanners taint-analysis
kuzushi config set scannerConfig["taint-analysis"].labelingModel anthropic:claude-sonnet-4-6
kuzushi config set scannerConfig["taint-analysis"].passes "[1,2,3,4,5,6]"
```
要覆盖捆绑的污点分析资产（例如，用于本地开发），设置 `TAINT_ANALYSIS_PATH` 或 `scannerConfig["taint-analysis"].taintAnalysisPath`：
```
export TAINT_ANALYSIS_PATH=/path/to/local/taint-analysis
kuzushi config set scannerConfig["taint-analysis"].taintAnalysisPath /path/to/local/taint-analysis
```
污点分析按 DAG 顺序运行三个阶段：**预检**（数据库创建、候选项提取）、**标记**（LLM 分类）和**分析**（库生成、查询执行、发现提取）。
### 污点分析 TI + 产物输出
每次污点分析运行都会在工作空间（`scannerConfig["taint-analysis"].workspaceDir`，默认 `./iris`）和运行目录下发出互操作性产物：
- `iris/exploration/TI_PRIOR.md` 和 `iris/exploration/ti_prior.json` — 实时 TI 先验（CISA KEV + NVD），带有获取失败时的降级模式元数据
- `iris/labels/TAINT_MODEL.json` — 每个 CWE 的污点模型（`sources/sinks/sanitizers/propagators`），带有 TI 加权基础
- `iris/results/findings.raw.json` — 来自污点分析通道 SARIF 输出的规范化原始发现聚合
- `.kuzushi/runs//findings.triaged.json` — 分诊后的发现导出，包括可选的污点分析源/汇分诊详细信息
相关的 `scannerConfig["taint-analysis"]` 选项：
- `tiMode`: `"live-required"` (默认)
- `tiFailurePolicy`: `"continue_without_ti"` (默认)
- `tiTimeoutMs`: 实时 TI 获取超时（毫秒）
- `refinementEnabled`: 启用一次分诊后优化循环（默认 `false`）
- `refinementIterations`: 启用时的最大优化轮次（默认 `1`）
- `refinementDeltaOnly`: 优化后仅对更改的发现进行分诊（默认 `true`）
- `refinementModel`: 用于优化阶段连接的可选模型覆盖
Agent 运行时后端
Kuzushi 支持两种 Agent 运行时后端：
**Claude（默认）** — 使用 `@anthropic-ai/claude-agent-sdk` 生成带有内置工具实现（Read、Glob、Grep、Bash 等）的 Claude Code 子进程。支持会话重用：批量操作通过 SDK 的流式输入 API 在多个轮次中保持单个子进程存活，将子进程生成减少约 99%。需要 `ANTHROPIC_API_KEY`。
**Pi-AI** — 使用 `@mariozechner/pi-ai` 提供供应商无关的 LLM 访问。它通过单一接口支持 15+ 个提供商（Anthropic、OpenAI、Google、Groq、Mistral 等）。所有 LLM 调用都在进程内运行（无子进程）。
Kuzushi 在 pi-ai 之上实现了一个内部 Agentic 循环：
1. **工具调用循环** — 调用模型，解析工具调用，执行工具，反馈结果，重复直到停止或达到最大轮次
2. **本地工具实现** — Read（带行号的文件读取器），Glob（Node 22+ `globSync`），Grep（跨文件正则搜索）
3. **结构化输出** — 系统提示词注入 + 从围栏代码块或原始文本中进行事后 JSON 提取
4. **安全控制** — 最大轮次、预算强制、中止信号、通过 `canUseTool` 的权限门控
```
# 配合任何支持的 provider 使用：
OPENAI_API_KEY=... kuzushi --model openai:gpt-4o
GEMINI_API_KEY=... kuzushi --model google:gemini-2.0-flash
ANTHROPIC_API_KEY=... kuzushi --model anthropic:claude-sonnet-4-6
```
架构
Kuzushi 构建在三个核心抽象之上：
**消息总线** — 一个传输无关的 `MessageBus` 接口（`publish`、`subscribe`、`waitFor`），用于解耦管道阶段。当前稳定版本支持进程内 `EventEmitter` 传输。
**AgentTask + DAG** — 每个工作单元（上下文收集器、扫描器、未来的威胁建模器等）都实现了 `AgentTask` 接口：一个 `id`、`dependsOn` 列表、`outputKind` 和一个 `run()` 方法。`TaskRegistry` 将启用的任务解析为 DAG，将它们分组为并行阶段，检测循环，并将执行移交给 `PipelineOrchestrator`。上游任务输出会自动转发给依赖项。
**管道阶段** — DAG 完成后，编排器驱动顺序阶段：分诊（分类发现）、验证（构造 PoC 漏洞利用）、补丁合成（自动生成并重新验证修复）和报告（显示结果 + 可选的 SSE 流）。每个阶段都有自己的并发控制、成本跟踪和检查点支持。
**策略框架** — 多策略系统用多种分析方法（语法、数据流、推理、执行）包装检测任务，这些方法并行或自适应运行，并通过基于确证的置信度提升合并结果。
**代码图** — 一个由 SQLite 支持的持久代码路径图，从入口点到汇点，由静态导入分析和 LLM 辅助追踪构建。注入到分诊提示词中，以进行关于可达性和净化的更深入推理。
**会话重用** — Claude 运行时使用 Agent SDK 的 `AsyncIterable` 提示，在多个轮次中保持单个子进程存活。批量操作（污点标记、分诊、验证、重新评分、PoC 生成、补丁合成）将每批数据写入 `.kuzushi/batches/`件，并向子进程发送提示以 `Read` 每个文件。这将每次管道运行的最坏情况子进程生成从约 3,100 个减少到约 24 个。不支持 `createSession` 的运行时（pi-ai）会自动回退到每次调用一个子进程。
现有的 `ScannerPlugin` 实现（Semgrep、Agentic）通过 `adaptScannerPlugin()` 适配为 `AgentTask`，因此扫描器插件 API 保持稳定。
有关添加新 Agent 任务的完整开发人员指南，请参见 [AGENTS.md](AGENTS.md)。
### 包表面
Kuzushi 作为 CLI 优先的包发布。支持的 npm 表面是可执行文件加上根包导出；`dist/*` 和 `src/*` 下的内部模块不是稳定的 API 契约，可能会在版本之间更改。
发布构建预期来自对 `dist/` 的干净编译。`pnpm build` 现在首先清理 `dist/`，`prepack` 自动重建，`pnpm verify:pack` 运行 `npm pack --dry-run`，因此不会发布过时的产物。
## 输出
结果存储在 `/.kuzushi/findings.sqlite3` 的 SQLite 中。导出为任何格式：
```
kuzushi --output report.md # Markdown
kuzushi --sarif results.sarif # SARIF v2.1.0 (GitHub Code Scanning compatible)
kuzushi --json results.json # JSON
kuzushi --csv results.csv # CSV
kuzushi --jsonl results.jsonl # JSONL
```
## 开发
```
pnpm install # install deps
pnpm dev -- /path/to/repo # run in dev mode
pnpm check:types # typecheck app + benchmark tooling
pnpm typecheck # type check
pnpm test # run tests
pnpm test:e2e # deterministic smoke scan against fixture app
pnpm test:coverage # tests + coverage (70% threshold)
pnpm build # compile to dist/
pnpm verify:pack # verify published tarball contents
pnpm benchmark # run benchmark suite against govwa dataset
pnpm benchmark:freeze # freeze current benchmark results as baseline
pnpm benchmark:diff # diff current results against frozen baseline
pnpm benchmark:regression # CI regression check against baseline
```
## 故障排除
- **"Error: missing API credentials for selected model provider(s)."**: 为你选择的模型设置提供商环境变量（例如 `ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 或 `GEMINI_API_KEY`）
- **"No findings from scanner. Code looks clean."**: 你的代码是干净的，或者尝试 `--severity ERROR,WARNING,INFO` 以包含较低严重性的规则
- **Scan interrupted**: 重新运行相同的命令（已分诊的发现会被跳过），或使用 `--resume` 从确切的检查点继续
- **Wrong model**: `kuzushi config set model anthropic:claude-sonnet-4-6` 或每次扫描传递 `--model`
- **Scanner download fails**: 手动安装 Opengrep 或 Semgrep，确保它在你的 PATH 上
- **High triage cost**: 使用 `--triage-model openai:gpt-4o-mini` 进行更便宜的分诊，或使用 `--max 10` 限制发现
- **Verification too expensive**: 使用 `--verify-min-confidence 0.8` 仅验证高置信度的 TP，或使用 `--verify-model openai:gpt-4o-mini`
- **pi-ai model not found**: 确保模型字符串使用 `provider:modelId` 格式（例如 `openai:gpt-4o`，而不仅仅是 `gpt-4o`）
## 贡献
有关开发设置和指南，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE)标签：AI 代理, Claude, CVE检测, DevSecOps, DLL 劫持, GNU通用公共许可证, LNA, Maven, MITM代理, Node.js, OpenAI, Opengrep, PoC 生成, SAST, Semgrep, WordPress安全扫描, 上游代理, 代码安全, 内存规避, 大语言模型, 漏洞枚举, 漏洞验证, 盲注攻击, 自动分类, 自动化攻击, 误报过滤, 请求拦截, 软件供应链安全, 远程方法调用, 错误基检测, 静态代码分析