peg/snare
GitHub: peg/snare
Snare 通过在 AI agent 环境中植入伪造凭证来检测被劫持的 agent，当攻击者使用这些陷阱凭证时立即触发回调告警。
Stars: 5 | Forks: 1
# snare
**通过欺骗手段为 AI agent 进行失陷检测。**
Snare 会在你的 agent 环境中植入伪造的凭证。当被劫持的 agent 去寻找凭证时，它会找到你设置的陷阱并触发回调。
无需 daemon。无需 proxy。无需更改策略。
## 工作原理
被劫持的 AI agent 会做出健康 agent 不会做的事情：它会去寻找从未被告知的凭证并尝试使用它们。
Snare 利用了这一点。它会在真实凭证存放的标准位置植入极具欺骗性的伪造凭证。Precision canary 会在植入的目标被主动使用时触发；`awsproc` 会在任何 AWS API 调用离开机器之前触发。
`awsproc` canary 使用 AWS 的 `credential_process` —— 这是一个在 SDK 解析凭证时运行的 shell 命令。当受感染的 agent 运行 `aws s3 ls --profile prod-admin` 时，警报会在 T+0.01秒送达。CloudTrail 根本看不到它。
```
# ~/.aws/config
[profile prod-admin]
role_arn = arn:aws:iam::123456789012:role/OrganizationAccountAccessRole
source_profile = prod-admin-source
[profile prod-admin-source]
credential_process = sh -c 'curl -sf https://snare.sh/c/{token} >/dev/null 2>&1; echo "{\"Version\":1,\"AccessKeyId\":\"AKIA...\",\"SecretAccessKey\":\"...\"}"'
```
这种双配置文件模式与真实 AWS 环境中设置 assume-role 链的方式完全一致。受感染的 agent 会看到一个看似休眠的凭证，并尝试使用它。
agent 会看到一个看似波动的 AWS 响应。而你看到的是这个：
```
🔑 AWS canary fired — agent-01
Token agent-prod-admin-2026-••••••••
Time 2026-03-14 04:07:33 UTC
IP 34.121.8.92 Location Council Bluffs, US
Network Amazon Technologies Inc (AS16509)
UA Boto3/1.34.46 md/Botocore#1.34.46 ua/2.0 os/linux#6.8.0...
⚠️ Likely AI agent Request originated from Amazon Technologies Inc
```
Boto3 的 user agent 会告诉你是由哪个 SDK 触发的。ASN 会告诉你它来自云端托管的 agent。**凭证本身就是传感器。**
## 安装
```
curl -fsSL https://snare.sh/install | sh
```
或者使用 Homebrew：
```
brew install peg/tap/snare
```
或者从 [发布页面](https://github.com/peg/snare/releases) 下载二进制文件。
要求 Linux 或 macOS 系统。无其他依赖项。
## 快速开始
```
snare arm --webhook https://discord.com/api/webhooks/YOUR/WEBHOOK
```
就是这样。Snare 会完成初始化，植入信号最强的 canary，触发一次测试警报以确认 webhook 正常工作，并告诉你哪些已处于警戒状态。
默认情况下，`snare arm` 使用 **precision 模式**：将植入 `awsproc`、`ssh`、`k8s`、`git` 和 `npm` canary。每一个都限定于植入的伪造目标，并具备自动化的真实客户端契约测试。
**在这台机器上运行 AI agent 吗？** Precision 模式在正常工作期间会保持安静，除非植入的伪造 profile、host、cluster、repository 或 package scope 被主动使用。使用 `--select` 可呼出交互式选择器，或使用 `--all` 来启用所有受支持的 canary 类型。
```
✓ initialized (device: dev-2146102a5849a7b3)
Planting canaries...
Precision mode: planting active-use canaries only (awsproc, ssh, k8s, git, npm)
✓ awsproc ~/.aws/config
✓ ssh ~/.ssh/config
✓ k8s ~/.kube/staging-deploy.yaml
✓ git ~/.gitconfig
✓ npm ~/.npmrc
✓ webhook test fired
🪤 5 canaries armed. This machine is protected.
Precision mode is safe for first run: alerts require active use of the fake
planted fake target. Passive file reads do not fire them.
Next checks:
snare status show event state; `never fired` is normal at first
snare scan verify planted files are present and unchanged
snare doctor confidence screen: config, API, ownership, and test health
snare repair re-sync registrations safely if doctor finds drift
snare prove --run --report safely trigger precision canaries and print a proof report
snare prove --format json --redact --output proof.json write a share-safe proof artifact
snare prove --pack mcp --run --report prove MCP canaries after `--all` or `plant --type mcp`
snare events view real hits when one arrives
```
在启用警戒后，`snare status` 通常会显示 `never fired`。这是正常的：这意味着 Snare 尚未记录到该 canary 的真实回调。当需要进行本地文件完整性检查时使用 `snare scan`，检查配置健康状况使用 `snare doctor`，而当你想安全地触发 precision canary 并生成首份成功报告时，请使用 `snare prove --run --report`。当你需要为团队成员或 issue 提供可安全共享的证明产物时，请添加 `--redact --output proof.json --format json`。
要启用所有 canary 类型（包括基于 dotenv 的类型，如 OpenAI、Anthropic 等）：
```
snare arm --all --webhook https://discord.com/api/webhooks/YOUR/WEBHOOK
```
受支持的 webhook 目标：Discord、Slack、Telegram，或任何接受 JSON 的 endpoint。请将 webhook URL 视为机密——不要提交、截图或分享它们。
正在为团队或实验室评估 Snare 吗？请从 [企业评估指南](docs/enterprise-evaluation.md) 开始，然后按照 [webhook 集成文档](docs/integrations/generic-webhook.md) 将警报接入你的 SIEM。
## 命令
```
snare arm [--webhook ] # precision mode: plant awsproc, ssh, k8s, git, npm + test
snare arm --select # interactive picker: choose which canaries to arm
snare arm --all # plant all 15 supported canary types
snare disarm # remove all canaries (keep config)
snare disarm --purge # remove canaries + ~/.snare/ config
snare status # show active canaries + event state
snare repair # re-register active tokens + run a live test check
snare sync # alias for snare repair
snare prove [--type ] # guided precision triggers (awsproc/ssh/k8s/git/npm)
snare prove --pack mcp # guided MCP initialize proof for planted MCP canaries
snare prove --run --report # execute safe triggers and print a proof report
snare prove --pack all --run --report # prove precision + MCP canaries together
snare prove --format json # machine-readable proof report output
snare prove --redact --output proof.json --format json # share-safe proof artifact
snare events # fetch recent alert history from snare.sh
snare events --summary # ASN/UA distribution across all canaries
snare scan # check canary integrity on disk
snare test # fire a test alert to verify your webhook
snare doctor [--test] # confidence screen; add --test for live callback proof
snare config # show current config
snare config set webhook # update webhook URL
snare rotate # rotate device secret (if config.json was exposed)
snare serve [--dashboard-token ] # run self-hosted callback server
snare uninstall # remove everything including the binary
```
`snare arm` 是幂等的。再次运行它会跳过已经植入的 canary，并添加任何缺失的 canary。
如需更多控制：
```
snare plant --type aws # plant a single canary type
snare plant --type k8s --label prod-cluster
snare teardown --token # remove a specific canary
snare teardown --dry-run # preview what would be removed
```
## 信心循环（前 10 分钟）
在执行 `snare arm` 之后，预期的健康循环如下：
- `snare status` 显示活动的 canary 和事件状态。在有人主动使用植入的伪造凭证之前，显示 `never fired` 是正常的。
- `snare scan` 仅限本地完整性检查：文件是存在/被修改/丢失/孤立。它不会触发警报。
- `snare doctor` 是信心检测界面：检查配置、回调健康状况、本地 canary 文件、token 所有权、events API 的可读性以及 webhook 测试历史。
- `snare doctor --test` 会运行实时回调测试，并验证其在 events API 中是否可读。
- `snare test` 仅发送合成的回调测试；请检查你的 webhook 目的地以查看路由过来的警报。
- `snare events` 显示真实的命中历史；全新安装时输出为空是正常的。
- `snare repair`（或 `snare sync`）会在检测到偏差时，安全地重新注册活动的 token，并重新测试回调/事件的可读性。
- `snare prove` 会打印安全的 precision 触发命令，让你可以特意证明 `awsproc`、`ssh`、`k8s`、`git` 和 `npm` 的警报会正常触发。
- `snare prove --pack mcp` 会对植入的 `mcp` canary 打印一个安全的 MCP Streamable HTTP 初始化探测，且不会修改正在使用的 MCP 客户端配置。
- `snare prove --run --report` 会执行选定的验证触发器，通过 events API 确认回调，并打印一份简明的验证报告，其中包含清理命令、事件可见性、观测到的延迟以及明确的验证/限制说明。
- `snare prove --format json --redact --output proof.json` 会写入一个机器可读的产物，其中的设备 ID、token ID、标签、清理 token 以及绝对本地路径均已被脱敏。
重要的状态区别：
- `never fired` 表示 token 已注册/可读，且尚未发生真实的回调。
- `events unavailable` 表示该 token 的 API/认证/可读性失败；请运行 `snare doctor`，如有必要请运行 `snare repair`。
## Canary 类型
| 类型 | 位置 | 触发条件 | 等级 |
|------|----------|---------|------|
| `awsproc` | `~/.aws/config` | AWS SDK 通过 `credential_process` 解析凭证 —— 在任何 API 调用发出前触发 | Precision |
| `ssh` | `~/.ssh/config` | 通过 `ProxyCommand` 的 curl/wget 回调进行 SSH 连接 | Precision |
| `k8s` | `~/.kube/.yaml` | `kubectl` 使用静态伪造 bearer token 联系伪造的 API server | Precision |
| `git` | `~/.gitconfig` | 对伪造 host 的显式访问被重写至回调地址 | Precision |
| `npm` | `~/.npmrc` | 显式访问伪造 scope 下的 package | Precision |
| `aws` | `~/.aws/config` | 使用命名的 endpoint 重定向 profile 进行任何 AWS CLI/SDK 调用 | High |
| `gcp` | `~/.config/gcloud/sa-*.json` | 通过 `token_uri` 重定向进行 GCP 认证尝试 | High |
| `pypi-upload` | `~/.pypirc` 或无用的备份文件 | 显式上传至命名的内部 repository | High |
| `pypi` | `~/.config/pip/pip.conf` | `pip install` 查询伪造的额外索引 —— **在你自己安装时也会触发** | High-noisy |
| `openai` | `~/.env` | 通过 `OPENAI_BASE_URL` 进行的任何 OpenAI SDK 调用 | Medium |
| `anthropic` | `~/.env.local` | 通过 `ANTHROPIC_BASE_URL` 进行的任何 Anthropic SDK 调用 | Medium |
| `mcp` | `~/.cursor/mcp.json.bak` 或其他无用的、厂商相邻的备份文件 | MCP 客户端连接至伪造的 HTTP server | Medium |
| `huggingface` | `~/.env.hf` | 加载 dotenv 文件后通过 `HF_INFERENCE_ENDPOINT` 进行的推理调用 | Medium |
| `terraform` | `~/.terraformrc` | 使用伪造 namespace 下的 provider 执行 `terraform init` | Medium |
| `generic` | `~/.env.production` | 任何读取 `API_BASE_URL` 的 SDK | Medium |
**Precision** canary 通过现有的 SDK 和 OS 管道触发——在正常工作期间几乎为零误报，因为它们要求主动使用植入的伪造 profile、host 或 context。这是 `snare arm` 的默认行为。
**High** canary 会在凭证被任何人（人类攻击者、受感染的 agent、扫描程序）主动使用时触发。
**High-noisy** canary 极易触发，但在正常的开发者工作流中也可能被触发。`pypi` 适用于激进的监控，但不适合作为安静的默认选项。
**Medium** canary 为条件触发——攻击者必须同时遵循 SDK 的 base URL 覆盖配置。如果人类直接抓取原始密钥并直接调用真实 API，则不会触发这些 canary。
每种类型的支持和验证状态记录在 [检测契约](docs/detection-contracts.md) 中。`azure`、`docker`、`github` 和 `stripe` 已被弃用，因为它们以前的设计依赖于不受支持的客户端行为。已植入的现有实例仍然可见且可移除。
Snare 检测的是主动使用，而不是任意的文件读取。`snare scan` 可验证完整性，但单纯的文件打开操作不会产生警报；被动读取遥测数据需要驻留 OS 级别的传感器。
### awsproc
`awsproc` 使用 AWS 的 `credential_process` —— 这是一个在 SDK 解析凭证时、进行任何 API 调用之前运行的 shell 命令。
当受感染的 agent 运行 `aws s3 ls --profile prod-admin` 时的时间线：
```
T+0.00s aws s3 ls --profile prod-admin
T+0.01s AWS SDK begins credential resolution
T+0.01s credential_process shell command executes
T+0.01s curl fires to snare.sh -> alert in your webhook
T+0.02s SDK receives fake JSON credentials
T+0.03s SDK attempts s3.ListBuckets() -> fails (fake creds)
T+0.03s Agent: "AWS error, credentials may be invalid"
```
**在 agent 意识到凭证无效之前，警报就已经到达了。** 像 Canarytokens 这样基于 CloudTrail 的工具能看到 API 调用；而 awsproc 在该调用存在之前就已经触发了。
这种双配置文件模式看起来就像真实的 assume-role 设置：
```
# ~/.aws/config
[profile prod-admin]
role_arn = arn:aws:iam::123456789012:role/OrganizationAccountAccessRole
source_profile = prod-admin-source
[profile prod-admin-source]
credential_process = sh -c 'curl -sf https://snare.sh/c/{token} >/dev/null 2>&1; echo "{\"Version\":1,\"AccessKeyId\":\"AKIA...\",\"SecretAccessKey\":\"...\"}"'
```
Canarytokens 做不到这一点。它们的 AWS canary 会创建一个真实的 IAM 用户并监控 CloudTrail，这会增加数分钟的延迟，并且需要外部 AWS 基础设施。`awsproc` 在本地运行，这正是其核心所在。
在气隙隔离或设有防火墙的机器上：即使回调无法到达 snare.sh，shell 命令仍会返回伪造的凭证 JSON。agent 会获得看似有效的凭证并继续执行。如果它随后尝试从你的网络外部使用这些凭证，则会分别触发警报。
这就是默认植入 `awsproc`、`ssh` 和 `k8s` 的原因——它们仅在凭证被主动使用时触发，使其成为运行 AI agent 的机器的最佳选择。
### mcp
在可被发现但不会被自动加载的位置植入伪造的 MCP server 配置。扫描 MCP server 的受感染 agent 会找到它并尝试连接。其 HTTP 传输 URL 指向 snare.sh。它不会干扰你正在使用的 Claude/Cursor/VS Code 配置。
要在不将其接入活动客户端的情况下特意验证 MCP canary，请运行：
```
snare prove --pack mcp --run --report
```
这会向植入的伪造 server URL 发送一个 Streamable HTTP `initialize` 请求，并通过 events API 验证回调。
## 警报
每个警报包含：
- 哪个 canary 被触发以及它位于哪台机器上
- 时间戳 (UTC)
- IP、城市、国家
- ASN（托管组织 —— `Amazon Technologies Inc` = 云端 agent，`Hetzner` = VPS 等）
- User agent（识别确切的 SDK：`Boto3/1.34.46`、`kubectl/v1.35.1` 等）
- 当请求来自云基础设施时的“可能是 AI agent”标志
配置 webhook 签名后，警报会使用 `X-Snare-Signature` (HMAC-SHA256) 进行签名，以便接收方验证发送者。
有关 SIEM 集成模式，请参阅 [通用 webhook](docs/integrations/generic-webhook.md)、[Splunk](docs/integrations/splunk.md)、[Datadog](docs/integrations/datadog.md) 和 [Microsoft Sentinel](docs/integrations/sentinel.md)。
## 隐私
Snare 的回调处理程序从不读取请求体。当 canary 触发时，worker 会在消耗请求体之前返回响应。Canary 回调在其请求体中可能携带真实的凭证或 prompt —— 应用程序代码不会对其进行检查。在托管模式下，Cloudflare 仍然负责终止网络请求；如果你需要完全的网络层控制，请自行托管。
每个警报仅存储：token ID、时间戳、IP、user agent、方法、路径、国家、ASN。
伪造的凭证内容本地保存在 `~/.snare/manifest.json` (0600) 中，永远不会发送到 snare.sh。Token ID 是 128 位随机十六进制字符串。其他 snare.sh 用户无法查询你的事件。
## 副作用
## 对比 canarytokens.org
[Canarytokens](https://canarytokens.org) 很好。Snare 是专门为 AI agent 构建的：
| | Canarytokens | Snare |
|---|---|---|
| 设置 | 手动，一次一个 token | `are arm` 涵盖 15 种受支持的凭证和工具使用类型 |
| AWS 检测 | CloudTrail（数分钟延迟） | 直接 SDK 回调（亚秒级） |
| 凭证类型 | AWS 及其他几种 | AWS、GCP、SSH、k8s、git、terraform、OpenAI、Anthropic、npm、PyPI、MCP 等 |
| AI agent 上下文 | 无 | 云端 ASN 检测、SDK user-agent 解析、`credential_process` 时序 |
| 触发条件 | 读取或使用（因情况而异） | 仅使用 |
## 与 Rampart 的关系
[Rampart](https://rampart.sh) 负责执行策略，并阻止 agent 进行不该进行的调用。Snare 则负责检测 agent 何时已被攻陷。它们解决的是问题的不同部分，各自独立工作也能运行良好。
## 自托管
当你需要自定义回调域名、完全的网络层控制、私人数据保留或 SIEM 中继行为时，请使用自托管。该仓库包含 Cloudflare Worker 源代码 (`worker/`) 以及带有 Docker Compose 的独立 `snare serve` 路径。
快速独立 server：
```
SNARE_DASHBOARD_TOKEN="$(openssl rand -hex 32)" \
SNARE_ENROLLMENT_TOKEN="$(openssl rand -hex 32)" \
snare serve --port 8080 --db /var/lib/snare/snare.db
```
快速 Docker Compose 路径：
```
{
echo "SNARE_DASHBOARD_TOKEN=$(openssl rand -hex 32)"
echo "SNARE_ENROLLMENT_TOKEN=$(openssl rand -hex 32)"
echo "SNARE_PORT=8080"
} > .env
docker compose up -d
curl -fsS http://localhost:8080/health
```
仅在你控制的反向代理后公开 `snare serve`。默认情况下，服务器会忽略 `X-Forwarded-For` 和 `X-Real-IP`；仅在允许提供这些 header 的代理网络中设置 `--trusted-proxy `。
有关反向代理、备份、升级、Cloudflare Worker 和客户端 `callback_base` 步骤，请参阅 [自托管指南](docs/self-hosting.md)。
## 验证发布版本
发布校验和使用 [Sigstore/cosign](https://docs.sigstore.dev/) 通过 GitHub Actions 的无密钥 OIDC 签名进行签署。要验证下载的发布版本：
```
cosign verify-blob --bundle checksums.txt.bundle checksums.txt
```
这可以确认校验和文件是由官方 GitHub Actions 发布工作流生成的，并且未被篡改。
## 许可证
Apache 2.0 —— 请参阅 [LICENSE](./LICENSE)。
标签：AWS, BOF, Cutter, DPI, EVTX分析, StruQ, 凭据监控, 安全助手, 日志审计, 欺骗防御, 蜜罐, 证书利用