sudan94/agentaudit
GitHub: sudan94/agentaudit
agentaudit 是一个只读、离线、CI 原生的安全扫描器，用于在 AI agent 执行前检测技能文件、规则文件和 MCP 配置中的 prompt injection、隐藏指令和危险权限。
Stars: 0 | Forks: 0
# 🛡 agentaudit
**你审计你的依赖。现在来审计你的 agent 指令。**
一个针对 AI agent 技能、规则文件和 MCP 配置的只读安全扫描器。
它检测 prompt injection、隐藏指令和危险权限
*在* 你的 agent 执行它们*之前*。
[](https://github.com/sudan94/agentaudit/actions/workflows/ci.yml)
[](https://pypi.org/project/agentaudit-scanner/)
[](https://pypi.org/project/agentaudit-scanner/)
[](LICENSE)
## 原因
你的 AI agent 会执行你安装的每一个文件 —— `SKILL.md`、`CLAUDE.md`、
`.cursorrules`、`.mcp.json`。这些是**可执行指令**，但与
代码不同，没人审查它们。恶意指令可能是不可见的：隐藏在
HTML 注释、零宽度 unicode 或 base64 中。单个被投毒的 skill 可以告诉
你的 agent 窃取 `.env` 文件、运行破坏性命令，或向你隐藏其自身
行为。**agentaudit 会优先读取这些文件。**
## 快速开始
```
pip install agentaudit-scanner
agentaudit scan .
```
使用 [uv](https://github.com/astral-sh/uv) 进行零安装：
```
uvx --from agentaudit-scanner agentaudit scan .
```
```
🛡 agentaudit v0.1.0 — scanned 14 file(s) in 0.3s
HIGH SKILL.md:47 Hidden instruction inside HTML comment
HIGH .mcp.json Server "helper-tools" combines filesystem read + network access
MEDIUM CLAUDE.md:12 Instruction to act silently or without confirmation
LOW .cursorrules:3 Base64-encoded block (2.1 KB) — cannot verify contents
2 high · 1 medium · 1 low → exit code 1
```
- **只读。** 从不修改任何内容。可在任何地方安全运行。
- **零配置。** 即开即用，无需设置。
- **默认离线。** 启发式引擎无需网络和 API key。
- **最小依赖。** `typer`、`rich`、`pyyaml`。该扫描器不会带来供应链风险。
- **原生 CI 支持。** 有意义的退出代码，JSON/SARIF 输出。
## 它能捕获什么
| 类别 | 示例 |
|---|---|
| **隐藏内容** | HTML 注释中的指令；零宽度与 bidi（Trojan Source）unicode；同形字；不可见的 CSS |
| **Prompt injection** | “忽略所有之前的指令”；角色劫持；“不要告诉用户”；条件触发器 |
| **数据窃取** | `.env`/`.ssh`/凭据与 `curl`/`POST`/webhook 结合；URL 缩短器，原始 IP，punycode |
| **危险命令** | `curl … \| sh`、`rm -rf`、反向 shell、base64-to-shell、cron/注册表持久化 |
| **MCP 权限过大** | 结合了文件系统 + 网络的服务器；未指定版本的 `npx @latest`；内联密钥；明文 HTTP endpoint |
| **Hooks** | 运行 shell 命令的 `.claude/settings.json` hooks（总是报告；危险的标记为 HIGH） |
| **混淆** | 解码 base64/hex 数据块并进行一层深度的重新扫描 |
运行 `agentaudit rules` 查看每条检测规则，或运行 `agentaudit rules --explain AA-INJ-003` 查看详情。
## GitHub Action
```
- uses: sudan94/agentaudit@v0.1.1
with:
path: .
fail-on: high
```
或直接在任何 workflow 中运行它：
```
- run: pipx run --spec agentaudit-scanner agentaudit scan . --format sarif -o agentaudit.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: agentaudit.sarif
```
## `--ai` 深度扫描（可选）
默认关闭。在启发式引擎之上添加 LLM 审计器：
```
export ANTHROPIC_API_KEY=sk-...
pip install 'agentaudit-scanner[ai]'
agentaudit scan . --ai
```
被扫描的内容被视为**不受信任的数据** —— 包裹在分隔符中，
绝不作为指令执行，并且只接受严格验证过的 JSON。
## 配置
在你的项目根目录下放置一个 `.agentaudit.yml`：
```
fail_on: high
ignore_paths:
- docs/examples/**
ignore_rules:
- AA-CMD-002
allow:
- rule: AA-INJ-001
path: SKILL.md
reason: "False positive — documented in #12"
```
或者直接在发现的上一行进行内联抑制：
```
```
## 编写自定义规则
一个检测规则大约是 10 行 YAML —— [查看指南](docs/writing-rules.md)：
```
- id: AA-INJ-100
title: Instruction to disable logging
severity: high
category: injection
applies_to: [markdown]
patterns:
- regex: '(?i)\b(disable|turn off|suppress)\s+(logging|audit|telemetry)\b'
```
使用 `--rules ./my-rules/` 或配置中的 `custom_rules_dir` 让 agentaudit 指向它。
**提交规则的 PR 是最好的贡献方式** —— 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 对比
包扫描器审计你安装的代码。**agentaudit 审计你安装的*指令*** —— 也就是你的 agent 实际上会服从的那一层。
## 路线图
- [x] v0.1 — 启发式引擎，规则包，美观的 JSON 报告器，配置，CI
- [ ] v0.2 — `--ai` 深度扫描，SARIF + GitHub Action，`scan --installed`，`scan 标签：AI代理, DNS 反向解析, GraphQL安全矩阵, LNA, Python, Redis利用, 云安全监控, 安全扫描器, 恶意代码分类, 无后门, 逆向工具, 静态分析