Lazarus-AI/clearwing
GitHub: Lazarus-AI/clearwing
一个基于 LangGraph 的双模式攻防工具，兼具网络渗透代理与源码安全猎手能力。
Stars: 1040 | Forks: 154
# Clearwing
作者：Eric Hartford, Lazarus AI
受 Anthropic 的 Glasswing 启发。
挑战：使用所有人都能访问的模型，产生与 Glasswing 类似的结果。
**自主漏洞扫描器和源代码猎手。** 基于
`genai-pyo3` 构建，这是一个由原生 Rust 支持的 LLM 运行时，支持对话所有主流的
提供商（Anthropic、OpenAI、OpenRouter、Ollama、LM Studio、Together、
Groq、DeepSeek、MiniMax、Gemini 以及任何兼容 OpenAI 的 endpoint）。
Clearwing 是一款双模式攻击性安全工具：
- **网络渗透测试 agent** —— 一个具备 63 个绑定工具的 ReAct 循环 agent，
可扫描活动目标，检测服务和漏洞，
运行沙箱化的 Kali 工具，尝试漏洞利用（通过
人工批准的护栏进行限制），并将报告写入持久化的
知识图谱。
- **源代码猎手** —— 一个文件并行的 agent 驱动
流水线，它会对源文件进行排名，展开逐文件搜寻的 hunter agent
（全 shell 或受限模式），使用 ASan/UBSan 崩溃作为事实依据，
通过一个 4 轴验证器（REAL /
TRIGGERABLE / IMPACTFUL / GENERAL）验证发现结果，在全新的
容器间运行 PoC 稳定性检查，可选择生成经过验证的补丁，
并输出带有明确证据级别的 SARIF/markdown/JSON 报告
（`suspicion → static_corroboration → crash_reproduced →
root_cause_explained → exploit_demonstrated → patch_validated`）。
具备三档预算提升、大文件的 entry-point 分片、跨子系统搜寻、带有
根因去重的共享发现池、多轮 agent 化漏洞利用开发，
以及人机协同的漏洞利用推敲等功能。
- **N-day 漏洞利用流水线** —— 给定 CVE ID，构建
漏洞版本，开发可用的漏洞利用程序，并针对
已修复的版本进行验证以确认修复情况。
- **逆向工程流水线** —— 通过 Ghidra 反编译闭源
ELF 二进制文件，利用 LLM 重构可能的源代码，
然后使用混合的源代码 + 二进制验证方法搜寻漏洞。
- ** Campaign 编排** —— 通过带有共享
预算、检查点/恢复以及汇总报告的单个 YAML 配置，在数十或数百个存储库中运行 sourcehunt。
- **负责任的漏洞披露** —— 带有 MITRE/HackerOne 模板生成、用于证明优先级的 SHA-3
加密承诺、时间线
跟踪以及批量披露的人机协同验证工作流。
- **基准测试与评估** —— 用于模型对比的 OSS-Fuzz 崩溃严重性
阶梯，以及用于衡量预处理是提升还是降低发现质量的 A/B 测试框架。
**仅供授权使用。** Clearwing 是一款双用途的攻击性安全
工具。仅针对您拥有或获得明确书面
测试授权的目标运行它。操作员需对测试范围、法律
授权和漏洞披露负责。请参阅 `SECURITY.md`。
## 安装
**最终用户** —— 直接从 GitHub 安装带标签的发行版：
```
git clone https://github.com/Lazarus-AI/clearwing.git
cd clearwing
# 推荐使用 uv sync，因为 Clearwing 通过
# pyproject.toml 中的 tool.uv.sources 固定了 genai-pyo3。
uv sync --all-extras
source .venv/bin/activate # fish: source .venv/bin/activate.fish
# 交互式设置向导 — 菜单驱动的 provider 选择、
# 凭证输入、可选的实时测试，并持久化到 ~/.clearwing/config.yaml
clearwing setup
# 环境检查 — 验证 Python、凭证、Docker daemon、
# 外部工具、可选的 extras 以及网络可达性
clearwing doctor
clearwing --version # 1.0.0
clearwing --help
```
或者跳过向导并直接进行配置：
```
# Anthropic direct
export ANTHROPIC_API_KEY=sk-ant-...
# 或任何兼容 OpenAI 的 endpoint — OpenRouter、Ollama、LM Studio、
# vLLM、Together、Groq、DeepSeek、OpenAI：
export CLEARWING_BASE_URL=https://openrouter.ai/api/v1
export CLEARWING_API_KEY=sk-or-...
export CLEARWING_MODEL=anthropic/claude-opus-4
```
有关特定于提供商的配置方法以及每个任务的分发策略，请参阅 [`docs/providers.md`](docs/providers.md)。
**开发者** —— 克隆并安装锁定版本的开发环境：
```
git clone https://github.com/Lazarus-AI/clearwing.git
cd clearwing
uv sync --all-extras
source .venv/bin/activate # fish: source .venv/bin/activate.fish
clearwing --help
```
要求：Python 3.10+，以及可选的 Docker（用于 Kali 容器
和 sanitizer-image 沙箱功能）。`genai-pyo3` 在 PyPI 上以预构建的
wheels 形式提供（支持 linux x86_64/aarch64、macOS universal2、windows x86_64、
Python 3.9–3.13），因此安装时不需要 Rust 工具链。
## 快速入门
```
# 扫描单个目标的网络扫描
clearwing scan 192.168.1.10 -p 22,80,443 --detect-services
# 针对 repo 的 Source-code 探索（标准深度 — 沙箱化的 LLM hunters、
# adversarial verifier、mechanism memory、variant loop）
clearwing sourcehunt https://github.com/example/project \
--depth standard
# N-day exploit pipeline — 构建并利用已知的 CVE
clearwing sourcehunt https://github.com/example/project \
--nday --cve-list CVE-2024-1234,CVE-2024-5678
# 逆向工程 — 在闭源 binaries 中寻找漏洞
clearwing sourcehunt /path/to/binary --reveng --arch x86_64
# 跨多个项目的 Campaign-scale 编排
clearwing campaign run campaign.yaml
# 负责任的披露工作流
clearwing disclose queue ./results/sourcehunt/sh-*/
clearwing disclose review
# OSS-Fuzz 崩溃严重性 benchmark
clearwing bench ossfuzz --corpus-dir ./oss-fuzz-projects --mode standard
# A/B 测试预处理是有益还是有害
clearwing eval preprocessing --project https://github.com/example/project \
--configs glasswing_minimal,sourcehunt_full --runs 3
# 使用全套工具集的交互式 ReAct 聊天
clearwing interactive
# 带有 SARIF 输出的非交互式 CI 模式，用于 GitHub Code Scanning
clearwing ci --config .clearwing.ci.yaml --sarif results.sarif
```
有关更详细的操作演练（包括凭证、会话恢复和任务模式操作），请参阅 [`docs/quickstart.md`](docs/quickstart.md)。
## 在本地存储库上运行 sourcehunt（FFmpeg 示例）
`clearwing sourcehunt ` CLI 会克隆远程 URL。要使用原生异步流水线和
自托管的兼容 OpenAI 的后端搜寻已克隆的代码树（例如 FFmpeg），请直接驱动 `SourceHuntRunner`：
```
# 1. Clone 目标一次
git clone https://github.com/FFmpeg/FFmpeg.git
# 2. 针对本地 checkout 运行 sourcehunt
uv run python -u - <<'PY'
import logging
from clearwing.llm.native import AsyncLLMClient
from clearwing.sourcehunt.runner import SourceHuntRunner
logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(name)s: %(message)s')
REPO = './FFmpeg'
RUN_DIR = './results/sourcehunt'
COMMON = dict(
provider_name='openai_resp', # or 'openai' for /v1/chat/completions
api_key='YOUR_KEY',
base_url='http://localhost:8183/v1', # any OpenAI-compatible endpoint
max_concurrency=15,
)
# 每个 stage 一个 client — 将每个 stage 路由到不同的 model
ranker_llm = AsyncLLMClient(model_name='gpt-5.4-mini', **COMMON)
hunter_llm = AsyncLLMClient(model_name='gpt-5.4', **COMMON)
verifier_llm = AsyncLLMClient(model_name='gpt-5.4-mini', **COMMON)
exploiter_llm = AsyncLLMClient(model_name='gpt-5.3-codex', **COMMON)
runner = SourceHuntRunner(
repo_url=REPO, local_path=REPO,
depth='standard',
budget_usd=1000.0,
max_parallel=15,
output_dir=RUN_DIR,
output_formats=['json', 'markdown'],
ranker_llm=ranker_llm,
hunter_llm=hunter_llm,
verifier_llm=verifier_llm,
exploiter_llm=exploiter_llm,
enable_patch_oracle=True,
)
print(runner.run()) # sync wrapper; internally drives SourceHuntRunner.arun()
PY
```
运行完成后，发现结果将作为 JSON +
markdown 保存在 `./results/sourcehunt/sh-/` 中。FFmpeg 大约有 1 万个源文件，因此预计大仓库排名器会预先筛选候选者，且 tier-A hunter 池将运行数小时。
如果您计划让进程在后台运行，请将 stdout/stderr 重定向到文件 —— 运行器自身的产出物只会在最后才写入。
`AsyncLLMClient` 接受 `provider_name` 值为 `openai_resp`（流式
`/v1/responses` 格式）或 `openai`（标准 `/v1/chat/completions`）；将
`base_url` 指向任何兼容 OpenAI 的服务器。有关托管提供商的路径，请参阅
[`docs/providers.md`](docs/providers.md)。
## 架构概览
```
┌──────────────────────┐ ┌────────────────────────────────┐
│ Network-pentest agent│ │ Source-code hunter │
│ clearwing.agent.graph│ │ clearwing.sourcehunt.runner │
│ (63 tools, ReAct) │ │ │
│ │ │ preprocess → rank → pool → │
│ │ │ hunter → verify → exploit → │
│ │ │ variant loop → auto-patch → │
│ │ │ report │
└─────────┬────────────┘ └────────┬───────────────────────┘
│ │
└───────────┬─────────────────┘
▼
┌───────────────────────────────────────────────────────────────┐
│ N-day pipeline │ Reveng pipeline │ Campaign orchestrator │
│ Disclosure workflow + SHA-3 commitments │
├───────────────────────────────────────────────────────────────┤
│ Shared substrate │
│ Finding dataclass │ capabilities probe │ sandbox layer │
│ knowledge graph │ episodic memory │ event bus │
│ telemetry │ guardrails + audit │ CVSS scoring │
│ artifact store │ behavior monitor │ seccomp │
├───────────────────────────────────────────────────────────────┤
│ Bench: OSS-Fuzz severity ladder │ Eval: preprocessing A/B │
└───────────────────────────────────────────────────────────────┘
```
深入解析位于 [`docs/`](docs/) 中：
| 文档 | 涵盖内容 |
|---|---|
| [`docs/index.md`](docs/index.md) | 首页 + 目录 |
| [`docs/quickstart.md`](docs/quickstart.md) | 完整的安装 + 首次运行演练 |
| [`docs/providers.md`](docs/providers.md) | OpenRouter / Ollama / LM Studio / vLLM / Together / Groq 配置指南、任务分发策略、环境变量优先级 |
| [`docs/architecture.md`](docs/architecture.md) | 两条流水线、底层基础、功能门控、工具布局 |
| [`docs/cli.md`](docs/cli.md) | 所有子命令标志，按工作流分组 |
| [`docs/api.md`](docs/api.md) | API 参考（由 mkdocstrings 自动生成） |
GitHub Pages 工作流发布后，文档将托管在
)。
有关范围、SLA 和安全 Harbor 条款，请参阅 [`SECURITY.md`](SECURITY.md)。
- **Clearwing *发现*的他人软件中的漏洞** →
该供应商的披露渠道。`clearwing sourcehunt
--export-disclosures` 会在
`evidence_level >= root_cause_explained` 时，为每个发现生成预填写的 MITRE CVE 请求和
HackerOne 模板。
## 许可证
MIT。请参阅 [`LICENSE`](LICENSE)。
作者：Eric Hartford, Lazarus AI
受 Anthropic 的 Glasswing 启发。
挑战：使用所有人都能访问的模型，产生与 Glasswing 类似的结果。
**自主漏洞扫描器和源代码猎手。** 基于
`genai-pyo3` 构建，这是一个由原生 Rust 支持的 LLM 运行时，支持对话所有主流的
提供商（Anthropic、OpenAI、OpenRouter、Ollama、LM Studio、Together、
Groq、DeepSeek、MiniMax、Gemini 以及任何兼容 OpenAI 的 endpoint）。
Clearwing 是一款双模式攻击性安全工具：
- **网络渗透测试 agent** —— 一个具备 63 个绑定工具的 ReAct 循环 agent，
可扫描活动目标，检测服务和漏洞，
运行沙箱化的 Kali 工具，尝试漏洞利用（通过
人工批准的护栏进行限制），并将报告写入持久化的
知识图谱。
- **源代码猎手** —— 一个文件并行的 agent 驱动
流水线，它会对源文件进行排名，展开逐文件搜寻的 hunter agent
（全 shell 或受限模式），使用 ASan/UBSan 崩溃作为事实依据，
通过一个 4 轴验证器（REAL /
TRIGGERABLE / IMPACTFUL / GENERAL）验证发现结果，在全新的
容器间运行 PoC 稳定性检查，可选择生成经过验证的补丁，
并输出带有明确证据级别的 SARIF/markdown/JSON 报告
（`suspicion → static_corroboration → crash_reproduced →
root_cause_explained → exploit_demonstrated → patch_validated`）。
具备三档预算提升、大文件的 entry-point 分片、跨子系统搜寻、带有
根因去重的共享发现池、多轮 agent 化漏洞利用开发，
以及人机协同的漏洞利用推敲等功能。
- **N-day 漏洞利用流水线** —— 给定 CVE ID，构建
漏洞版本，开发可用的漏洞利用程序，并针对
已修复的版本进行验证以确认修复情况。
- **逆向工程流水线** —— 通过 Ghidra 反编译闭源
ELF 二进制文件，利用 LLM 重构可能的源代码，
然后使用混合的源代码 + 二进制验证方法搜寻漏洞。
- ** Campaign 编排** —— 通过带有共享
预算、检查点/恢复以及汇总报告的单个 YAML 配置，在数十或数百个存储库中运行 sourcehunt。
- **负责任的漏洞披露** —— 带有 MITRE/HackerOne 模板生成、用于证明优先级的 SHA-3
加密承诺、时间线
跟踪以及批量披露的人机协同验证工作流。
- **基准测试与评估** —— 用于模型对比的 OSS-Fuzz 崩溃严重性
阶梯，以及用于衡量预处理是提升还是降低发现质量的 A/B 测试框架。
**仅供授权使用。** Clearwing 是一款双用途的攻击性安全
工具。仅针对您拥有或获得明确书面
测试授权的目标运行它。操作员需对测试范围、法律
授权和漏洞披露负责。请参阅 `SECURITY.md`。
## 安装
**最终用户** —— 直接从 GitHub 安装带标签的发行版：
```
git clone https://github.com/Lazarus-AI/clearwing.git
cd clearwing
# 推荐使用 uv sync，因为 Clearwing 通过
# pyproject.toml 中的 tool.uv.sources 固定了 genai-pyo3。
uv sync --all-extras
source .venv/bin/activate # fish: source .venv/bin/activate.fish
# 交互式设置向导 — 菜单驱动的 provider 选择、
# 凭证输入、可选的实时测试，并持久化到 ~/.clearwing/config.yaml
clearwing setup
# 环境检查 — 验证 Python、凭证、Docker daemon、
# 外部工具、可选的 extras 以及网络可达性
clearwing doctor
clearwing --version # 1.0.0
clearwing --help
```
或者跳过向导并直接进行配置：
```
# Anthropic direct
export ANTHROPIC_API_KEY=sk-ant-...
# 或任何兼容 OpenAI 的 endpoint — OpenRouter、Ollama、LM Studio、
# vLLM、Together、Groq、DeepSeek、OpenAI：
export CLEARWING_BASE_URL=https://openrouter.ai/api/v1
export CLEARWING_API_KEY=sk-or-...
export CLEARWING_MODEL=anthropic/claude-opus-4
```
有关特定于提供商的配置方法以及每个任务的分发策略，请参阅 [`docs/providers.md`](docs/providers.md)。
**开发者** —— 克隆并安装锁定版本的开发环境：
```
git clone https://github.com/Lazarus-AI/clearwing.git
cd clearwing
uv sync --all-extras
source .venv/bin/activate # fish: source .venv/bin/activate.fish
clearwing --help
```
要求：Python 3.10+，以及可选的 Docker（用于 Kali 容器
和 sanitizer-image 沙箱功能）。`genai-pyo3` 在 PyPI 上以预构建的
wheels 形式提供（支持 linux x86_64/aarch64、macOS universal2、windows x86_64、
Python 3.9–3.13），因此安装时不需要 Rust 工具链。
## 快速入门
```
# 扫描单个目标的网络扫描
clearwing scan 192.168.1.10 -p 22,80,443 --detect-services
# 针对 repo 的 Source-code 探索（标准深度 — 沙箱化的 LLM hunters、
# adversarial verifier、mechanism memory、variant loop）
clearwing sourcehunt https://github.com/example/project \
--depth standard
# N-day exploit pipeline — 构建并利用已知的 CVE
clearwing sourcehunt https://github.com/example/project \
--nday --cve-list CVE-2024-1234,CVE-2024-5678
# 逆向工程 — 在闭源 binaries 中寻找漏洞
clearwing sourcehunt /path/to/binary --reveng --arch x86_64
# 跨多个项目的 Campaign-scale 编排
clearwing campaign run campaign.yaml
# 负责任的披露工作流
clearwing disclose queue ./results/sourcehunt/sh-*/
clearwing disclose review
# OSS-Fuzz 崩溃严重性 benchmark
clearwing bench ossfuzz --corpus-dir ./oss-fuzz-projects --mode standard
# A/B 测试预处理是有益还是有害
clearwing eval preprocessing --project https://github.com/example/project \
--configs glasswing_minimal,sourcehunt_full --runs 3
# 使用全套工具集的交互式 ReAct 聊天
clearwing interactive
# 带有 SARIF 输出的非交互式 CI 模式，用于 GitHub Code Scanning
clearwing ci --config .clearwing.ci.yaml --sarif results.sarif
```
有关更详细的操作演练（包括凭证、会话恢复和任务模式操作），请参阅 [`docs/quickstart.md`](docs/quickstart.md)。
## 在本地存储库上运行 sourcehunt（FFmpeg 示例）
`clearwing sourcehunt 标签：CISA项目, DLL 劫持, Rust, XXE攻击, 人工智能, 大语言模型, 漏洞挖掘, 用户模式Hook绕过, 网络安全, 网络流量审计, 自动化渗透测试, 隐私保护