glacien-technologies/agent-guardian
GitHub: glacien-technologies/agent-guardian
AgentGuardian是一款用于AI代理红队测试的开源框架。
Stars: 0 | Forks: 1
# AgentGuardian
**在攻击者之前对您的AI代理进行红队测试。**
为AI代理、RAG系统、MCP服务器以及使用工具的LLM应用程序提供的开源、本地优先的对抗性安全测试。
[](https://pypi.org/project/agent-guardian/)
[](https://pypi.org/project/agent-guardian/)
[](LICENSE)
[](https://github.com/glacien-technologies/agent-guardian/actions/workflows/ci.yml)
[](https://api.securityscorecards.dev/projects/github.com/glacien-technologies/agent-guardian)
[](https://docs.agentguardian.io)
[Docs](https://docs.agentguardian.io) · [Quickstart](https://docs.agentguardian.io/quickstart) · [试用演示代理](https://docs.agentguardian.io/start-here/try-the-demo-agent) · [攻击库](https://docs.agentguardian.io/attacks/overview) · [CI/CD](https://docs.agentguardian.io/ci-cd/overview) · [样本报告](./docs/_assets/sample-report.html)
AgentGuardian将一群对抗性探测针对您的目标，并提供您可以在工程、安全审查和CI中使用的可重复证据：AIVSS评分、签名JSON、SARIF、Markdown、JUnit、PDF以及每个探测的记录。
- 为代理系统构建，而不仅仅是单次提示聊天机器人评估。
- 发现提示注入、工具误用、权限滥用、内存中毒、代码执行路径、信任利用和目标漂移。
- 本地运行，在CI中运行或在确定性的`--model stub`模式下离线运行。
## 演示
```
pip install agent-guardian
echo 'You are a helpful customer-support agent for ACME Bank.' > prompt.txt
agent-guardian scan --system-prompt prompt.txt --mode fast --model stub
```
这为您提供了：
- 交互式扫描期间的实时本地仪表板
- 存储在`~/.agentguardian/scans/
/`下的扫描工件
- 通过`agent-guardian report SCAN_ID --output sarif --output-path scan.sarif`导出报告
- 静态参考渲染：[`docs/_assets/sample-report.html`](./docs/_assets/sample-report.html)
`--model stub`不需要API密钥和网络。当您想要一个权威的评判时，请将真实模型（如`gemini:gemini-2.5-flash`或`openai:gpt-4o`）替换进去。
## 安装
```
# pip
pip install agent-guardian
# pipx
pipx install agent-guardian
# uv
uv add agent-guardian
# or
uv tool install agent-guardian
```
Python `3.11`–`3.13`受支持。Linux和macOS是首选；Windows由社区支持。
## 60秒快速入门
```
# 1. 安装检查
agent-guardian doctor
# 2. 查看随附的探针语料库
agent-guardian list-probes
# 3. 运行离线扫描
echo 'You are a helpful customer-support agent for ACME Bank.' > prompt.txt
agent-guardian scan --system-prompt prompt.txt --mode fast --model stub
# 4. 获取扫描ID后导出机器可读报告
agent-guardian report SCAN_ID --output sarif --output-path scan.sarif
```
交互式扫描自动提供本地仪表板。您也可以稍后使用以下方式浏览结果：
```
agent-guardian serve
# → http://127.0.0.1:7474
```
## 您可以扫描的内容
- 通过`--system-prompt PATH`进行提示扫描的目标
- 通过`--endpoint URL`进行托管HTTP代理
- 通过`--framework KIND --framework-ref MODULE:ATTR`进行框架原生对象扫描
- 通过位置`target`参数进行自定义Python入口点扫描（`my_agent:run`，`path/to/app.py:graph`）
- 通过合同路径进行高级合同驱动目标扫描，包括MCP / OpenAPI / 浏览器 / WebSocket流程，该合同路径在`docs/concepts/target-adapters.mdx`中记录
内置框架类型：
- `langgraph`
- `crewai`
- `openai_agents`
- `autogen`
- `adk`
- `strands`
## 它可以捕获什么
AgentGuardian包含**96个攻击探测**，涵盖所有2026年OWASP Top 10代理应用程序类别：
- **ASI01** — 提示注入/目标劫持
- **ASI02** — 工具误用
- **ASI03** — 权限妥协
- **ASI04** — 供应链/资源过载
- **ASI05** — 代码执行
- **ASI06** — 内存中毒
- **ASI07** — 代理到代理妥协
- **ASI08** — 级联故障
- **ASI09** — 信任利用/不安全输出处理
- **ASI10** — 不可追踪性/目标漂移
语料库还映射到MITRE ATLAS v5.4.0和CSA代理AI红队指南。具体请见`docs/reference/framework-coverage-matrix.md`中的确切集合。
## 您可以得到什么
- **签名JSON证据** — `scan.json`包含HMAC-SHA256 + Ed25519签名，可通过`agent-guardian verify`进行验证
- **可导出报告** — `json`、`sarif`、`junit`、`md`、`gitlab`和`pdf`
- **每个探测的记录** — 提示、响应、裁决和证据轨迹
- **AIVSS评分** — 在`--mode full`模式下发布；在`fast`和`smart`模式下跟踪趋势
- **本地仪表板** — 浏览历史扫描、发现和证据包
要验证存储的报告：
```
agent-guardian verify ~/.agentguardian/scans/SCAN_ID/scan.json
```
## 为什么选择AgentGuardian
- **以代理为中心** — 为使用工具、有状态、多步骤系统构建，而不是单次提示检查
- **攻击前侦察** — 确定目标表面并运行相关专家
- **证据而非感觉** — 报告基于记录、结构化发现和签名工件
- **本地优先** — 无遥测、无电话回家，以及完全离线的stub模式路径
- **CI就绪** — 非零退出代码、SARIF导出和可重用的GitHub Action模式
有关更深入的竞争分析，请参阅`docs/concepts/agent-guardian-vs.mdx`。
## 它是如何工作的
每次扫描都遵循相同的叙事：
1. **计划** — 解决目标类型、预算、模型和输出格式
2. **侦察** — 黑盒指纹目标：工具、内存、PII暴露、多代理交接、可到达的系统
3. **红队** — 对观察到的表面派遣与ASI对齐的专家
4. **发现** — 判断结果、计算AIVSS并编写签名报告
侦察指纹是关键区别：AgentGuardian在花费预算之前决定哪些攻击对**此目标**很重要。
## 扫描真实目标
```
# 托管HTTP端点
agent-guardian scan \
--endpoint http://localhost:8000/chat \
--model gemini:gemini-2.5-flash \
--mode smart
# LangGraph 应用
agent-guardian scan \
--framework langgraph \
--framework-ref my_app.graph:graph \
--model gemini:gemini-2.5-flash
# 自定义Python入口点
agent-guardian scan \
my_agent:run \
--model gemini:gemini-2.5-flash
```
示例工作位于`examples/`下，以及`docs/try/`下的`Try AgentGuardian`指南。
## 扫描模式
| 模式 | 典型用途 | 备注 |
| --- | --- | --- |
| `fast` | 开发循环、烟雾检查、预推送 | 成本最低，反馈最快 |
| `smart` | PR迭代、更广泛的夜间覆盖 | 比`fast`更好，但仍非权威 |
| `full` | 发布门、`main`上的CI、审计证据 | AIVSS和`--fail-under`的权威模式 |
只有`--mode full`产生权威的AIVSS，适用于硬发布门。
## CI集成
```
name: AgentGuardian
on: [pull_request]
jobs:
scan:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- run: pip install agent-guardian
- name: Red-team the agent
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
run: |
agent-guardian scan \
--endpoint http://localhost:8000/chat \
--model gemini:gemini-2.5-flash \
--mode full \
--output sarif \
--output-path agentguardian.sarif \
--fail-under 80
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: agentguardian.sarif
```
有关更完整的设置、阈值和复合操作路径，请参阅`docs/ci-cd/overview.mdx`和`docs/ci-cd/github-actions.mdx`。
## 标准和覆盖率
在本地列举语料库：
```
agent-guardian list-probes
agent-guardian list-probes --by-standard owasp-asi
agent-guardian list-probes --by-standard mitre-atlas
agent-guardian list-probes --by-standard csa-agentic-rt
```
今天的覆盖率：
- **OWASP ASI 2026** — 所有10个类别都涵盖
- **MITRE ATLAS v5.4.0** — 在目标I/O表面可以观察技术的地方映射
- **CSA代理AI红队指南** — 在发布的语料库中映射
确切的探测到标准的映射位于`docs/reports/owasp-mapping.mdx`和`docs/reference/framework-coverage-matrix.md`。
## 隐私与遥测
**不收集遥测数据。** 没有分析ping、安装跟踪器或电话回家路径。stub模式还支持离线工作，无需LLM密钥。
## 文档
- [文档主页](https://docs.agentguardian.io)
- [`docs/quickstart.mdx`](./docs/quickstart.mdx)
- [`docs/attacks/overview.mdx`](./docs/attacks/overview.mdx)
- [`docs/concepts/target-adapters.mdx`](./docs/concepts/target-adapters.mdx)
- [`docs/integrations/index.md`](./docs/integrations/index.md)
- [`docs/reference/cli.mdx`](./docs/reference/cli.mdx)
## 项目状态
AgentGuardian `1.0.0`是第一个稳定版本。语义版本控制适用于公共Python API、CLI界面、报告模式和探测ID。探测内容和评分可能在次要版本中随着覆盖率的提高而演变。
请参阅`OSS路线图`、`CHANGELOG.md`和`governance`。
## 贡献
我们欢迎新的探测、新的适配器和新的攻击逻辑。从`CONTRIBUTING.md`和`good first issue`标签开始。
所有提交都必须是DCO签署的：
```
git commit -s
```
通过参与，您同意遵守[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)和[`ethics policy`](./docs/community/ethics.md）。AgentGuardian用于测试您拥有或明确授权测试的系统。
## 社区
加入我们，在[Discord](https://discord.gg/h4FRgxvr)上讨论探测设计、适配器问题和路线图讨论。有关更长时间的支持渠道，请参阅`docs/community/support.mdx`。
## 安全
有关漏洞报告，请参阅`SECURITY.md`。**不要**为安全报告打开公共问题。
## 许可证
Apache-2.0。请参阅`LICENSE`和`NOTICE`。
`AgentGuardian`是Glacien Technologies的商标。请参阅`TRADEMARKS.md`以获取使用指南。标签：AI 代理, AI 红队, Python, 二进制发布, 人工智能安全, 代码执行路径, 反取证, 合规性, 安全报告, 安全文档, 安全漏洞检测, 安全评估, 安全评分, 安全评分卡, 对抗性测试, 开源工具, 开源框架, 持续集成, 攻击库, 无后门, 本地测试, 权限滥用, 逆向工具