Thomaszhou22/agent-canary

[English](#english) | [中文](./README_CN.md) ## 中文 ### 简介 Agent Canary 是一款用于 AI agent 工作区的主动防御 skill。它会生成逼真的虚假凭证（AWS key、GitHub token、API key、Stripe key、数据库密码），并将其植入工作区的关键位置。当恶意 skill 读取、复制或窃取这些凭证时，Agent Canary 会检测到该行为并立即向您发出警报。 兼容 OpenClaw、Claude Code、Cursor、Windsurf、Cline 以及任何使用 skill 的 agent 平台。与仅在安装前检查 skill 的静态扫描器不同，Agent Canary 能够在运行时（即 skill 实际尝试访问您的凭证时）捕获恶意行为。 ### 问题背景 - 7.6% 的 ClawHub skill 包含恶意模式（Snyk 研究，2026 年 2 月） - 36% 的 skill 至少包含一个安全漏洞 - 静态扫描器可在 1 小时内被绕过（Trail of Bits，2026 年 6 月） - 恶意 skill 可以从 `.env` 文件、内存文件和配置中窃取凭证 - 目前没有工具能在运行时主动监控凭证窃取行为 ### 工作原理 ``` ┌─────────────────────────────────────────────────┐ │ 1. GENERATE fake credentials │ │ AWS keys, GitHub PATs, Stripe keys, etc. │ │ Each has unique CANARY fingerprint │ │ │ │ 2. PLANT in strategic locations │ │ .env.canary, secrets.backup.json, │ │ memory/canary-tokens.json │ │ │ │ 3. MONITOR via cron (every 30 min) │ │ ┌──────────┬──────────┬───────────────────┐ │ │ │ Hash │ atime │ Log + Git grep │ │ │ │ modified │ accessed │ Token exfiltrated │ │ │ └──────────┴──────────┴───────────────────┘ │ │ │ │ 4. ALERT when triggered │ │ Severity + file + token ID + recommendation │ └─────────────────────────────────────────────────┘ ``` ### 功能特性 - **5 种 token 类型**：AWS Access Key、GitHub PAT、Stripe key、通用 API key、数据库密码 - **3 个植入位置**：`.env.canary`、`secrets.backup.json`、`memory/canary-tokens.json` - **4 种检测方法**：文件哈希对比、访问时间监控、exec 日志检索、git diff 检查 - **自动警报**：即时通知，包含严重程度、文件和处置建议 - **便捷的部署与清理**：单条命令即可完成部署和清理 - **零真实凭证接触**：所有 token 均为伪造，并标记有 `CANARY`，无法通过认证 ### 实时演示 **启用前**（无保护）： ``` Malicious skill installed → silently reads .env → finds AWS_ACCESS_KEY_ID → exfiltrates to attacker server → you never know ``` **启用后**（使用 Agent Canary）： ``` Malicious skill installed → reads .env.canary (canary file) → finds fake AWS key "AKIACANARY7F3A2B9X0" → exfiltrates to attacker server → cron check finds token in logs → YOU GET ALERTED IMMEDIATELY → rotate real credentials, uninstall skill ``` ### 安装说明 #### 作为 OpenClaw Skill ``` openclaw skills install @Thomaszhou22/agent-canary ``` #### 手动安装 ``` git clone https://github.com/Thomaszhou22/agent-canary.git cd agent-canary ``` ### 使用方法 ``` You: deploy canary Agent: Canary deployed! 5 tokens planted in 3 files. Monitoring cron active (every 30 min). You: canary status Agent: 3 canary files intact. Last check: 2026-07-30 12:00. 0 incidents. You: canary check Agent: Running immediate check... CRITICAL: Token "AKIACANARY..." found in exec log! File: .env.canary Recommendation: Check which skill was running at 12:34. You: canary cleanup Agent: 3 files removed. Monitoring stopped. ``` ### 技术栈 - Python 3（仅使用标准库，零依赖） - OpenClaw cron 系统用于定时监控 - OpenClaw 消息工具用于发出警报 ### 文件结构 ``` agent-canary/ ├── SKILL.md # Skill instructions ├── scripts/ │ ├── generate_tokens.py # Token generation engine │ ├── plant_canaries.py # Canary file deployment │ ├── check_canaries.py # Monitoring and detection │ └── cleanup_canaries.py # Removal └── templates/ # Canary file templates ``` ### 平台兼容性 Agent Canary 适用于任何运行 AI agent skill 的环境： | 平台 | 监控方式 | 警报方式 | |----------|-----------|----------| | OpenClaw | Cron（自动） | 消息工具 | | Claude Code | Cron / 手动 | 终端输出 | | Cursor | 手动 | 终端输出 | | Windsurf | 手动 | 终端输出 | | Cline | 手动 | 终端输出 | | 任何支持 SKILL.md 的平台 | 手动 | 日志文件 | 核心脚本（`generate_tokens.py`、`plant_canaries.py`、`check_canaries.py`、`cleanup_canaries.py`）是纯 Python 3 编写的，且零依赖。它们可以在任何地方运行。 ### 对比 | 工具 | 方式 | Agent Canary | |------|----------|-------------| | sukiraman/canary | 被动 secret 扫描 | 主动诱饵植入 | | mcp-scan | 安装前静态代码分析 | 安装后运行时检测 | | SkillGuard | 安装前扫描器 | 安装后持续监控 | | Pipelock | 网络代理（需配置） | 无需网络配置 | ### 局限性 - 如果没有网络层面的检查，则无法检测通过加密通道进行的窃取行为 - 文件访问时间（atime）可能无法在所有文件系统上生效 - 以 30 分钟的 cron 间隔进行检查（非实时） - `CANARY` 标记使 token 在人工检查时很容易被发现（这是有意为之，为了安全清理） ### 开源许可 MIT

标签：AI代理, BOF, Python, StruQ, 人工智能, 无后门, 时间线生成, 欺骗防御, 用户模式Hook绕过, 蜜罐, 证书利用