# 对抗性辩论
### AI 红队安全测试框架
**在攻击者之前找到安全漏洞。**
[](https://www.python.org/downloads/)
[](https://github.com/dr-gareth-roberts/adversarial-debate/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
[](https://bandit.readthedocs.io/)
[快速开始](#quickstart) •
[文档](docs/index.md) •
[示例](examples/) •
[贡献指南](CONTRIBUTING.md)
## 概述
Adversarial Debate 是一个**多智能体 AI 安全测试框架**。专门的智能体从不同角度分析您的代码，而 Arbiter 则通过置信度评分和优先修复建议来汇总发现。
```
ChaosOrchestrator
├─ ExploitAgent (security vulnerabilities)
├─ BreakAgent (logic bugs and edge cases)
├─ ChaosAgent (resilience and failure modes)
└─ CryptoAgent (crypto and auth-adjacent issues)
↓
Arbiter (deduplication + prioritisation + verdict)
```
## 核心功能
- **多智能体架构**，覆盖 OWASP Top 10、逻辑错误、弹性故障和加密弱点
- **置信度评分**，包含严重性和可利用性评估
- **强化沙箱**，用于安全执行不受信任的代码
- **基于事件溯源的审计追踪**，通过 bead 账本实现
- **确定性演示模式**，通过 mock provider 实现
## 快速开始
### 环境要求
- Python 3.11+
- Docker（强化沙箱所需）
- LLM provider API 密钥（`mock` 模式下不需要）
### 安装
```
# 使用 uv（推荐）
uv add adversarial-debate
# 使用 pip
pip install adversarial-debate
# 从源码
git clone https://github.com/dr-gareth-roberts/adversarial-debate.git
cd adversarial-debate
uv sync --extra dev
```
### 运行
```
# 分析单个文件的 exploit
adversarial-debate analyze exploit src/api/users.py
# 为目录创建协调攻击计划
adversarial-debate orchestrate src/
# 运行完整 pipeline（orchestrate + analyze + verdict）
adversarial-debate run src/api/ --output results/
```
### 确定性演示（无需 API 密钥）
```
LLM_PROVIDER=mock adversarial-debate analyze exploit examples/mini-app/app.py
LLM_PROVIDER=mock adversarial-debate run examples/mini-app/ --output output
```
## 输出
一次 pipeline 运行会生成以下文件：
- `attack_plan.json`
- `exploit_findings.json`
- `break_findings.json`
- `chaos_findings.json`
- `crypto_findings.json`
- `findings.json`
- `verdict.json`（除非使用 `--skip-verdict`）
- `bundle.json`（标准 bundle；使用 `--bundle-file` 覆盖）
如果交叉审查产生了有争议的发现，它将写入 `findings.debated.json`。
## Python API
```
import asyncio
from datetime import UTC, datetime
from adversarial_debate import (
AgentContext,
BeadStore,
ExploitAgent,
get_provider,
)
async def analyse_code(code: str, file_path: str):
provider = get_provider("anthropic") # or "mock" for a deterministic demo
store = BeadStore()
exploit = ExploitAgent(provider, store)
context = AgentContext(
run_id="analysis-001",
timestamp_iso=datetime.now(UTC).isoformat(),
policy={},
thread_id="analysis-001",
task_id="security-review",
inputs={
"code": code,
"file_path": file_path,
"language": "python",
},
)
return await exploit.run(context)
result = asyncio.run(
analyse_code(
"def get_user(id): return db.execute(f'SELECT * FROM users WHERE id={id}')",
"app.py",
)
)
```
## 强化沙箱
`SandboxExecutor` 以严格的限制运行不受信任的代码。
```
import asyncio
from adversarial_debate import SandboxConfig, SandboxExecutor
config = SandboxConfig(
timeout_seconds=30,
memory_limit="512m",
cpu_limit=0.5,
network_enabled=False,
docker_image="python:3.11-slim",
)
executor = SandboxExecutor(config)
async def run_in_sandbox() -> None:
result = await executor.execute_python("print('Hello from the sandbox')")
print(result.output)
asyncio.run(run_in_sandbox())
```
## 文档
从这里开始：[`docs/index.md`](docs/index.md)。
重点内容：
- 入门指南：[`docs/getting-started/quickstart.md`](docs/getting-started/quickstart.md)
- CLI 参考：[`docs/guides/cli-reference.md`](docs/guides/cli-reference.md)
- 配置：[`docs/guides/configuration.md`](docs/guides/configuration.md)
- 输出格式：[`docs/guides/output-formats.md`](docs/guides/output-formats.md)
- CI/CD 集成：[`docs/integration/ci-cd.md`](docs/integration/ci-cd.md)
- 开发者指南：[`docs/developers/`](docs/developers/)
## 开发
```
# 安装依赖
uv sync --extra dev
# Tests
make test
# Lint / format / type-check
make lint
make format
make typecheck
```
## 安全
请阅读 `SECURITY.md` 并通过安全策略报告漏洞。
## 许可证
本项目基于 MIT 许可证授权。详情请参阅 `LICENSE`。
## 链接
- 代码仓库：https://github.com/dr-gareth-roberts/adversarial-debate
- 问题反馈：https://github.com/dr-gareth-roberts/adversarial-debate/issues
- 讨论区：https://github.com/dr-gareth-roberts/adversarial-debate/discussions