SamsonCyber/agent-canary
GitHub: SamsonCyber/agent-canary
为自主 AI agent 提供绊线式检测的工具，通过文件蜜罐、MCP 工具陷阱和 API 诱饵捕捉并记录 agent 的越权访问行为。
Stars: 0 | Forks: 0
# Agent Canary
为自主 AI agent 提供绊线检测。
## 功能简介
在你的代码库、MCP 工具接口和 API endpoint 中植入 canary token。当 agent 读取 honeypot 文件、调用 tripwire 工具或访问诱饵 API 路由时，Agent Canary 会记录带有取证链（参数、请求头、客户端 IP、先前的工具调用）的结构化触发事件。你可以在不改变生产环境应用逻辑的情况下，察觉到范围蔓延（scope creep）和未经授权的工具使用。
## 安装
从 GitHub 安装（这是唯一的权威源；不在 PyPI 上发布）：
```
pip install "git+https://github.com/SamsonCyber/agent-canary.git"
# 固定 release tag
pip install "git+https://github.com/SamsonCyber/agent-canary.git@v0.2.0"
# 可选的 MCP tripwire server extras
pip install "git+https://github.com/SamsonCyber/agent-canary.git#egg=agent-canary[mcp]"
```
## 快速入门
```
# 在你的项目根目录中初始化
agent-canary init
# 植入 honeypot 文件（默认 --notice off：静默 honeypot）
agent-canary plant file .env.production --template aws_creds
agent-canary plant file secrets/database.yml --template db_creds
# 用于测量的软作用域通知（static | stochastic）
agent-canary plant file traps/.env.prod --template aws_creds --notice stochastic
# 注册 MCP tripwire tools
agent-canary plant mcp-tool execute_sql_admin \
--description "Run admin SQL queries on production database" --notice static
agent-canary plant mcp-tool export_user_data --description "Export user data in bulk"
# 注册 API decoy endpoints
agent-canary plant api /admin/config --method GET --description "Admin config access lure"
agent-canary plant api /v1/users/export --method POST --description "Bulk export" --notice stochastic
# 查看已部署的内容
agent-canary list
# 开始监控 triggers
agent-canary watch
```
## MCP 集成
将 tripwire MCP 服务器添加到你的 `claude_desktop_config.json` 中：
```
{
"mcpServers": {
"canary": {
"command": "agent-canary",
"args": ["serve-mcp", "--stdio"]
}
}
}
```
该服务器通过 JSON-RPC 暴露 tripwire 工具。任何调用这些工具的 agent 都会被记录下完整的取证上下文，随后会收到一个看似合理的权限拒绝错误。
## 三大攻击向量
**文件 honeypot。** 通过 6 个内置模板生成逼真的凭证文件、API key 配置、PII 导出数据和内部文档。使用 `watchdog` 进行监控（带有轮询回退机制）。手动访问检查适用于拦截 `read_file` 的 MCP 封装器。
**MCP tripwire 工具。** 注册虚假的高权限工具（默认 5 个：`execute_sql_admin`、`send_email`、`export_user_data`、`modify_production_config`、`delete_resources`）。在被调用时，它们会记录完整的参数并返回一个看似合理的权限拒绝错误。
**API 诱饵 endpoint。** 提供虚假的 HTTP 路由（默认 4 个：批量导出、管理员配置、云元数据凭证、Vault 风格的机密信息），并捕获请求头、请求体、查询参数和客户端 IP。
## 告警
配置 webhook、Slack 或 Discord 通知：
```
# 通用 webhook
agent-canary alert add webhook https://your-server.com/canary-hook
# Slack incoming webhook
agent-canary alert add slack https://hooks.slack.com/services/T.../B.../xxx
# Discord webhook
agent-canary alert add discord https://discord.com/api/webhooks/123/abc
# 测试所有已配置的 destinations
agent-canary alert test
# 列出已配置的 destinations
agent-canary alert list
```
每次触发事件都会发出告警，其结构化 payload 包含 canary ID、向量类型、严重程度、取证链和 agent 指纹。
## 文件模板
| 模板 | 生成内容 | 适用场景 |
|---|---|---|
| `aws_creds` | 带有 AWS 访问密钥的虚假 `.env` | 凭证收集 |
| `db_creds` | 包含生产/预生产环境配置块的数据库配置 YAML | 数据库访问尝试 |
| `ssh_key` | 带有嵌入式追踪信息的虚假 RSA 私钥 | 密钥外泄 |
| `api_keys` | 包含 Stripe、OpenAI 和 GitHub token 的 YAML | API key 窃取 |
| `pii_data` | 包含 6 行虚假 PII（姓名、SSN、电子邮件）的 CSV | 数据外泄 |
| `internal_doc` | 标记为机密的 Markdown 架构文档 | 文档访问 |
每个模板都以符合格式且合理的方式嵌入 canary ID，这样诱饵既能保持可追踪性，又不会看起来像一个 tripwire。
## 范围规则
Canary 支持允许/拒绝列表，以减少误报：
- `allow_agents`：列出的 agent 永远不会触发。其他任何对象都会触发。
- `deny_agents`：仅列出的 agent 会触发。其他所有对象都会被忽略。
- 两者都设置：允许列表优先（白名单中的 agent 保持安全）。
- 两者均未设置：全局 canary；任何对象访问都会触发。
## 范围提示（agent robots.txt）
随 tripwire 响应一起返回的可选软边界文本。默认植入模式为 `off`，以确保现有的静默 honeypot 保持静默。
| 模式 | 行为 |
|------|----------|
| `off` | 无提示。与 v0.1 版本相同（记录 + 拒绝 / 仅返回诱饵内容）。 |
| `static` | 每次访问返回固定的横幅文本。适合用于可复现的演示。 |
| `stochastic` | 每次访问抽样显示策略/边界/禁止条款。罕见的诚实 honeypot 分支。 |
取证中你会获得以下信息：
- 每个 `TriggerEvent` 上的 `scope_notice`（包含 `notice_id`、`family`、`access_n`、`text`、`mode`）
- canary 上的 `access_count`（重试次数在达到 3 次后会升级措辞）
- 文件植入：当模式不是 `off` 时，在植入时会在文件开头添加提示横幅
- MCP / API：将提示合并到 agent 看到的 JSON 错误体中
它的**非**适用范围：
- 不是硬性控制。Agent 可以忽略或改写软性文本。
- 不能修复生产环境中偶然发生的 agent“黑客”行为。请为此使用硬性范围网关、工具白名单和网络策略。
- 首要在于衡量和取证：agent 是否看到了提示、进行了重试，或者改变了路径？
```
agent-canary plant file traps/keys.env --template api_keys --notice stochastic
agent-canary plant mcp-tool delete_resources \
--description "Delete cloud resources" --notice static
agent-canary plant api /admin/config --method GET \
--description "Admin config" --notice stochastic
```
带有提示的触发事件会显示在 `agent-canary triggers --format json` 命令输出的 `scope_notice` 字段下。
## 与现有工具的区别
| 工具 | 主要目标 | 部署位置 |
|------|----------------|---------------|
| Thinkst Canary | 针对传统基础设施上的人类攻击者（DNS token、HTTP 信标、凭证对） | 网络 / 基础设施 |
| Beelzebub MCP | 通用网络欺骗 honeypot | 网络 |
| SNARE/TANNER | 针对扫描器的 Web 应用 honeypot | Web 层 |
| **Agent Canary** | 针对 AI agent：MCP 工具调用、agent 文件读取、自主 API 探测 | 项目目录树中的应用层 |
Agent Canary 记录特定于 agent 的取证数据（工具参数、可用的推理轨迹、agent 指纹），以便你可以区分范围蔓延、注入或意外的工具使用。无需单独的 honeypot 主机。
## 许可证
MIT
标签：AI智能体, Python, StruQ, 无后门, 模型上下文协议, 蜜罐, 行为审计, 证书利用, 诱饵技术, 逆向工具