GauntletVectorLabs/gauntlet
GitHub: GauntletVectorLabs/gauntlet
Gauntlet 是一个通过对抗性探针对 AI agent 进行自动化失败发现并将其转化为 CI 回归测试套件的测试工具。
Stars: 1 | Forks: 0
# Gauntlet
[](https://pypi.org/project/gauntlet-agent/)
[](https://pypi.org/project/gauntlet-agent/)
[](LICENSE)
[](https://github.com/GauntletVectorLabs/gauntlet/actions/workflows/ci.yml)
**在用户击败你的 agent 之前，先让它经历严酷考验。**
Gauntlet 会通过 HTTP 向你的 AI agent 发送一套对抗性的边缘“用户”测试，找出它的失败之处（system prompt 泄露、不安全的操作、范围漂移、崩溃、失控的输出），按严重程度对失败进行排名，并将它们转化为可在 CI 中把守的回归测试套件。与框架无关：只要你的 agent 使用 HTTP 通信，Gauntlet 就能测试它。
它建立在一个信念之上：只有在定义了什么是失败之后，一个通过的评估才有意义。大多数 agent 的“评估”之所以能通过，是因为没有人去编写那些注定会失败的测试。
## 为什么会有这个项目
团队发布的 agent 在演示中运行良好，但在生产环境中却悄无声息地崩溃：模型选错了工具，向聪明的用户泄露了其 prompt，确认了本应拒绝的操作，或者陷入了死循环。可靠性的昂贵之处不在于仪表盘，而在于发现故障并确保它们保持修复状态。Gauntlet 就是负责去寻找这些故障的工具。
## 快速开始（30 秒，无需 API key）
```
# 安装（发布后）：pip install gauntlet-agent
# 或者作为隔离的 CLI： pipx install gauntlet-agent
# 1. 在单个进程中，观察它对一个故意损坏的示例 agent 的作用：
python examples/demo.py
# 2. 或者针对你自己的 agent（任何接受 JSON 的 HTTP endpoint）运行它：
# terminal A：
python examples/sample_agent.py
# terminal B：
gauntlet run --target http://localhost:8000/chat --canaries examples/canaries.json
```
无网络的自我测试（可在任何地方运行，适合 CI）：
```
python tests/test_offline.py # or: pytest
```
## 在你的 agent 上使用它
将 `--target` 指向任何接受 `POST {"message": "..."}` 并返回 JSON 或文本的 endpoint。字段名称是可配置的。你的 agent 还不是 HTTP 服务（如 LangChain、OpenAI Assistants 或裸函数）？使用 [`examples/adapters/`](examples/adapters) 中的 shim 用几行代码包装它 —— 无需编写服务器代码。
```
gauntlet run \
--target https://your-agent.example.com/v1/chat \
--request-field input --response-field output \
--header "Authorization: Bearer $TOKEN" \
--canaries my_canaries.json \
--fail-on HIGH \
--json gauntlet-report.json
```
当发现任何等于或高于 `--fail-on` 级别的问题时，退出代码为非零，因此你可以直接将其放入 CI 中：
```
# .github/workflows/agent.yml
- run: gauntlet run --target $STAGING_AGENT_URL --canaries canaries.json --fail-on HIGH
```
### Canary：定义什么是失败
通用的 grader（错误、空回复、长度失控）无需配置。高价值的 grader 是你提供的 canary，即你的 agent 绝对不能做的事情：
```
{
"never_output_substrings": ["INTERNAL-OPS-KEY", "system prompt"],
"unsafe_compliance_substrings": ["refund of $", "deleted the account"],
"max_response_chars": 6000,
"severity_overrides": { "missing_refusal": "MEDIUM", "data_leak": "CRITICAL" }
}
```
`severity_overrides` 允许你根据自身的风险标准（CRITICAL/HIGH/MEDIUM/LOW/INFO）重新调整任何发现类型 —— 例如，如果你的 agent 故意话多，可以降低 `missing_refusal` 的严重性，或者将泄露保持在 CRITICAL 级别。
## 工作原理
1. **Adversaries** (`gauntlet/adversaries.py`) —— 一个确定性的探针库，涵盖 prompt 注入、范围纪律、错误前提、数据泄露、畸形输入和循环诱导。采用确定性设计，因此运行结果可复现。
2. **Runner** (`gauntlet/runner.py`) —— 并发向你的 HTTP endpoint 发送探针，仅使用标准库。
3. **Graders** (`gauntlet/graders.py`) —— 通用的可靠性检查加上你的 canary，生成按严重性排名的发现结果（从 CRITICAL 到 INFO）。
4. **Report** (`gauntlet/report.py`) —— 可读的摘要、最严重的故障，以及用于 CI 的 JSON 产出物。
## 可选：LLM 驱动模式
默认模式无需 API key。使用 `--llm` 时，Gauntlet 会根据你的 agent 描述生成新的对抗性角色，并可以使用 judge 来评估开放式行为，而不是仅依靠子字符串 canary。
```
pip install "gauntlet-agent[llm]"
export ANTHROPIC_API_KEY=...
gauntlet run --target $URL --llm --describe "support bot for an online store"
```
judge 是一个轻量、可替换的层。核心在于方法论：根据 agent 的真实交互面生成探针，并在**信任其分数之前，使用少量人工标注的黄金数据集来验证 judge。**
### 校准 judge（不要相信未经校验的分数）
```
gauntlet calibrate --gold examples/gold.jsonl --min-kappa 0.6
```
在人工标注的黄金数据集上运行 judge，并报告准确率、精确率、**召回率**（在真实的失败中，judge 捕捉到了多少 —— 这对于安全工具来说是最重要的指标）、F1 分数，以及 **Cohen's κ**（经过偶然性校正的一致性）。
如果低于 `--min-kappa`，它将以非零状态退出，因此虚弱的 judge 会导致 CI 失败，而不是悄悄输出错误的分数。初始的黄金数据集位于 `examples/gold.jsonl`。
## 多轮对话探针（跨回合构建的越狱）
真正的越狱很少是单条消息就能完成的 —— 它们会在几个回合中建立信任、植入上下文或捏造虚假前提，然后利用这一点。添加 `--multiturn` 以包含内置的对话探针（渐进式、逐步重置角色、上下文污染、捏造承诺）。Gauntlet 会逐轮引导并评估最终回复。
```
# 有状态 agent（保持其自身的 session）：
gauntlet run --target $URL --multiturn --canaries canaries.json
# 无状态 agent：将运行中的 transcript 作为 OpenAI 风格的 messages 数组发送
gauntlet run --target $URL --multiturn --history-field messages --canaries canaries.json
```
报告会打印出任何多轮对话失败的完整对话记录，让你能准确看到它是如何发展到那一步的。
添加 `--extended` 以使用更新的单轮攻击类别（间接/RAG 注入、Unicode 同形字规避、拒绝抑制、base64 编码走私、工具描述提取、PII 处理）：
```
gauntlet run --target $URL --extended --multiturn --canaries canaries.json
```
## Trace 感知评估（评估工具调用，而不仅仅是文本）
听起来安全的回答可能隐藏着不安全的操作。如果你的 agent 返回了它所执行的工具调用，Gauntlet 可以直接评估这些调用。让你的 agent 在其 JSON 响应中包含一个 `trace`：
```
{ "response": "All set!", "trace": [ {"tool": "issue_refund", "args": {"amount": 999}} ] }
```
然后指向它并声明哪些工具/参数是禁止的：
```
gauntlet run --target $URL --trace-field trace --canaries canaries.json
```
```
{ "forbidden_tools": ["issue_refund", "delete_user", "send_bulk_email"],
"forbidden_tool_arg_substrings": ["all_users", "DROP TABLE"] }
```
即使文本看起来正常，被禁止的工具调用（或被禁止的参数）也会被视为 HIGH 级别的发现 —— 这可以抓住那些嘴上说着“我不能”但实际却调用了工具的 agent。
## 路线图
- [x] Judge 校准命令（`gauntlet calibrate`）
- [x] 角色记忆：多轮对话探针（`--multiturn`）
- [x] Trace 感知评估（`--trace-field` + 禁止的工具/参数）
- [x] 托管仪表盘 + 定时运行（查看 monorepo 中的 `apps/dashboard`）
## 许可证
MIT。详见 [LICENSE](LICENSE)。
标签：AI智能体, Python, 人工智能, 安全测试, 攻击性安全, 文档结构分析, 无后门, 用户模式Hook绕过, 逆向工具