copyleftdev/patchy
GitHub: copyleftdev/patchy
将ProjectDiscovery安全工具链封装为MCP服务，使LLM智能体能够在策略约束下安全执行子域名枚举、端口扫描、漏洞探测等侦察任务。
Stars: 0 | Forks: 0
# PATCHY
一个将 [ProjectDiscovery](https://projectdiscovery.io/) 安全工具箱封装为 LLM 智能体可用的强类型、策略执行工具的 MCP 服务器。
PATCHY 将 **subfinder**、**dnsx**、**httpx**、**naabu**、**katana** 和 **nuclei** 作为结构化的 [Model Context Protocol](https://modelcontextprotocol.io/) 工具进行暴露，并提供作用域强制执行、沙盒执行以及标准化的 JSON 输出。
## 快速开始
```
# 构建
make build
# 设置目标 scope 并运行
PATCHY_SCOPE=example.com ./bin/patchy
# 或使用 config file
./bin/patchy --config patchy.yaml
```
### 首次运行 —— 未安装任何组件
PATCHY 可以自我引导启动。连接到服务器并调用：
```
pd.ecosystem.setup
```
这将自动安装 pdtm、所有 PD 工具以及 nuclei 模板。
或者运行 doctor 来查看缺少什么：
```
PATCHY_SCOPE=example.com ./bin/patchy --doctor
```
### MCP Host 配置
**Claude Desktop / Claude Code:**
```
{
"mcpServers": {
"patchy": {
"command": "/path/to/patchy",
"env": {
"PATCHY_SCOPE": "example.com"
}
}
}
}
```
**SSE 传输:**
```
PATCHY_SCOPE=example.com PATCHY_TRANSPORT=sse PATCHY_LISTEN=127.0.0.1:8080 ./bin/patchy
```
## 工具
### 原语
| 工具 | 描述 |
|------|-------------|
| `pd.subfinder.enumerate` | 被动子域名枚举 |
| `pd.dnsx.resolve` | DNS 解析 (A, AAAA, CNAME, MX 等) |
| `pd.httpx.probe` | HTTP 探测与技术检测 |
| `pd.naabu.scan` | TCP 端口扫描 |
| `pd.katana.crawl` | Web 爬取与端点发现 |
| `pd.nuclei.scan` | 基于模板的漏洞扫描 |
### 生态
| 工具 | 描述 |
|------|-------------|
| `pd.ecosystem.manifest` | 已安装工具的版本与健康状态 |
| `pd.ecosystem.doctor` | 健康检查与可操作建议 |
| `pd.ecosystem.update` | 更新所有工具和模板 |
| `pd.ecosystem.setup` | 从零开始引导构建完整的 PD 工具链 |
所有原语均支持 **异步任务执行** —— 客户端可以同步调用（默认）或作为后台任务提交并进行轮询。
## 作用域强制执行
PATCHY 默认为 **拒绝策略**。在配置作用域之前，任何工具都不会针对任何目标执行。
**通过环境变量：**
```
PATCHY_SCOPE="example.com,*.example.com,10.0.0.0/24"
```
包含 `/` 且解析为 CIDR 的值将归入 IP 白名单；其他所有值均被视为域名模式。
**通过配置文件：**
```
policy:
scope:
allow_domains:
- example.com
- "*.example.com"
allow_cidrs:
- 10.0.0.0/24
deny_domains:
- internal.example.com
```
## 配置
配置文件搜索顺序：
1. `--config ` 标志
2. `./patchy.yaml`
3. `~/.config/patchy/patchy.yaml`
4. `~/.patchy/patchy.yaml`
完整 Schema 请参阅 [docs/configuration.md](docs/configuration.md)。
**环境变量覆盖** —— 任何设置都可以使用 `PATCHY_` 前缀进行覆盖：
| 变量 | 作用 |
|----------|--------|
| `PATCHY_SCOPE` | 逗号分隔的允许目标 |
| `PATCHY_TRANSPORT` | `stdio` 或 `sse` |
| `PATCHY_LISTEN` | SSE 绑定地址 |
| `PATCHY_LOG_LEVEL` | `debug`, `info`, `warn`, `error` |
| `PATCHY_BASE_DIR` | 产物存储目录 |
| `PATCHY_BINARY_PATH` | PD 工具二进制文件搜索路径 |
## 输出格式
每个工具返回一个 `RunResult` 封装：
```
{
"schema_version": "1",
"run_id": "550e8400-...",
"tool": "pd.subfinder.enumerate",
"status": "success",
"timing": { "start": "...", "end": "...", "duration_ms": 4230 },
"result": {
"record_type": "SubfinderRecord",
"count": 42,
"records": [ ... ]
}
}
```
状态值：`success`, `error`, `timeout`, `cancelled`, `policy_denied`。
错误包含可操作的 `hint` 字段：
```
{
"error": {
"code": "BINARY_NOT_FOUND",
"message": "subfinder not found",
"hint": "Install: pdtm -install subfinder, or call pd.ecosystem.setup"
}
}
```
## 构建与测试
```
make build # Build binary
make test # Unit tests (fast, no binaries needed)
make vet # Static analysis
make doctor # Health check
# Integration tests（需要 PD binaries + 网络）
go test -tags integration -v -timeout 10m ./test/integration/
```
## 架构
```
MCP Client
| JSON-RPC (stdio/SSE)
MCPServer (mcpbridge)
|
Tool Handlers ── Policy Engine ── Runner ── PD Binary
| |
| BoundedBuffer
v |
RunResult envelope JSONL parser
|
Artifact Store
```
**关键约束：**
- 无 Shell 执行 —— 直接使用 `exec.Command`，绝不使用 `sh -c`
- 二进制白名单 —— 仅已注册的二进制文件可执行
- 作用域强制执行 —— 执行前检查每个目标
- 限制输出 —— stdout/stderr 设有上限以防止 OOM
- 无静默失败 —— 所有错误均通过代码和提示展示
## 项目结构
```
cmd/patchy/ Entry point, CLI flags, transport dispatch
internal/
config/ YAML config loading, env overrides, defaults
mcpbridge/ MCP SDK abstraction (only package importing mcp-go)
observability/ Structured slog logger, in-process metrics
pipeline/ Multi-tool pipeline composition
policy/ Scope, rate limits, concurrency, flag blocklists
registry/ Binary discovery, health checks, manifest
runner/ Sandboxed process execution, BoundedBuffer
store/ Filesystem artifact store
tools/ MCP tool handlers (one file per tool)
update/ pdtm update state machine
pkg/schema/ Public types: RunResult, per-tool record structs
test/integration/ Full lifecycle integration tests
docs/ Configuration reference, architecture, setup guides
```
## 文档
- [设置指南](docs/setup.md) —— 安装，配置 Claude Code / Windsurf / Cursor / Claude Desktop
- [配置参考](docs/configuration.md) —— 完整 YAML Schema，环境变量，策略默认值
- [工具参考](docs/tools.md) —— 全部 10 个工具的参数、输出类型与示例
- [架构](docs/architecture.md) —— 数据流，包边界，安全模型
## 许可证
MIT —— 详见 [LICENSE](LICENSE) 文件。
标签：AI安全, Chat Copilot, Claude, CVE检测, DLL 劫持, DNS解析, EVTX分析, EVTX分析, FTP漏洞扫描, GitHub, Google, Go语言, Httpx, Lerna, LLM Agent, MCP, Model Context Protocol, Nuclei, ProjectDiscovery, 大语言模型, 子域名枚举, 安全编排, 实时处理, 密码管理, 开源项目, 插件系统, 数据保护, 数据统计, 日志审计, 程序破解, 端口扫描, 策略执行, 类型安全, 系统安全, 网络安全, 自动化安全工具, 隐私保护