agent-canary

Zero-false-positive tripwires for AI agents. Know instantly when your coding agent has been hijacked by a prompt injection — not because a heuristic guessed it, but because it touched a decoy that nothing legitimate ever touches.

中文文档：README.zh-CN.md

The idea in 20 seconds

A shop owner puts a fake safe wired to an alarm in the back room. No real customer ever touches it — so if the alarm goes off, someone is robbing the store. Period. Zero false positives.

agent-canary does the same for the AI agents (Claude Code, Cursor, Cline, your own builds) that can read files, run commands, and call APIs on your machine:

1. Decoy MCP tools — a fake wire-transfer tool, a fake production-secrets reader, a fake "run shell as root". A healthy agent never calls them. A hijacked one does, and you get alerted with the full attack context.

2. Canary tokens — worthless, unique cnry_… strings planted in honeypot files. If one ever shows up in an agent's output, an exfiltrated archive, or an outbound request, a secret was stolen. That's it.

Every fake response a decoy returns embeds a fresh one-time trace token — so if the attacker's payload exfiltrates the "stolen secrets", the token tells you exactly which tool call it came from.

Related MCP server: Deception Remote MCP Server

Why not just scan for prompt injections?

Injection detectors score text and guess. They drown you in false positives or miss novel payloads. Canaries invert the problem:

Both approaches can coexist; canaries are the alarm that never cries wolf.

Quickstart

npm install -g agent-canary

# 1. Plant a honeypot file of fake secrets in your project
agent-canary tokens plant .env.canary --label my-project

# 2. Register the decoy MCP server in Claude Code (or: install cursor)
agent-canary install claude

# 3. Verify alerts work end to end
agent-canary alert-test

Restart your editor. The agent now sees 8 juicy-looking decoy tools it should never touch. If it does:

$ agent-canary events
2026-09-15T10:21:04Z  decoy_called  tool=canary_read_secrets
2026-09-15T10:21:09Z  token_found   label=decoy:canary_read_secrets path=https://evil.example/collect

Pair the token scan with anything you already run:

agent-canary tokens check . && echo clean          # exit 1 on leak — CI / git-hook friendly
agent-canary watch .                               # live watch: alert when a token appears in any file
agent-canary set-webhook https://hooks.slack.com/… # push alerts to Slack / Discord / a Telegram bridge

What the decoys look like (to the agent)

The agent sees tempting, admin-grade tools. None of them do anything — every handler is inert and returns fabricated output:

And the alert you receive carries the whole picture: which decoy, with what arguments, when, plus a per-call trace token.

Hard guarantees

• Decoy tools are inert. canary_run_shell does not execute commands; canary_transfer_funds does not touch money. Every handler returns a plausible fake — nothing else. See SECURITY.md.

• Canary tokens unlock nothing. They are random cnry_… strings with no meaning anywhere.

• No telemetry. Events stay in ~/.agent-canary/events.jsonl on your machine unless you configure a webhook.

• Zero false positives by construction. Decoys and tokens sit outside every legitimate workflow; touching them is the signal.

CLI reference

agent-canary serve                 run the decoy MCP server (what the editor launches)
agent-canary init                  create ~/.agent-canary + starter config
agent-canary install claude|cursor register the decoy server in your MCP client (backs up config first)
agent-canary uninstall claude|cursor
agent-canary tokens generate --label <l> [-c n]
agent-canary tokens plant <file> --label <l> [-c n]
agent-canary tokens check [paths...] [--stdin]     exit 1 on leak (CI-friendly)
agent-canary tokens list / print --label <l>
agent-canary watch <paths...>      live file watch for token leaks
agent-canary events [-n 20]        recent tripwire events
agent-canary report                markdown incident report
agent-canary alert-test            fire a test alert through all channels
agent-canary set-webhook <url|null>
agent-canary set-notify <on|off>

Config lives in ~/.agent-canary/config.json:

{ "webhook": null, "notify": true, "eventsFile": "~/.agent-canary/events.jsonl" }

How it works

Claude Code / Cursor / your agent
        │  one MCP config line
        ▼
┌───────────────────────────────┐
│ agent-canary (decoy server)   │── touched ──▶ 🚨 alert + JSONL audit trail
│ 8 inert, tempting fake tools  │               + one-time trace token in the fake reply
└───────────────────────────────┘
┌───────────────────────────────┐
│ canary tokens in honeypot     │── token appears anywhere ──▶ 🚨 zero-false-positive alert
│ files / .env / databases      │   (scan · watch · CI check)
└───────────────────────────────┘

Roadmap

• v0.1 — decoy MCP server, canary tokens, file watch, JSONL + webhook + desktop alerts

• v0.2 — eval mode: run a curated prompt-injection suite against any agent+model combo, output a reproducible resistance score

• v0.3 — dashboard: attack-chain timeline across sessions; SIEM export

• v0.4 — SDK instrumentation beyond MCP (OpenAI / Anthropic agent SDK hooks)

Compatibility

Node 20+, Windows / macOS / Linux. Works with any MCP-capable client (Claude Code, Cursor, Cline, Windsurf, …). The token scanner and watcher work with any agent, MCP or not.

Support this project

agent-canary is free, local, and telemetry-free — but paid promotion and hosting are funded out of pocket. If it ever catches an injection for you:

• ⭐ Star the repo — genuinely the highest-value thing you can do for discovery

• 💳 GitHub Sponsors — the sponsor button at the top of this repo

• 🧧 WeChat Pay / Alipay — a self-hosted sponsor gateway ships in sponsor/: a single-file server that renders a QR donation page and verifies WeChat Pay (API v3 signatures + AES-GCM callbacks) and Alipay (RSA2 notifications) end to end. Demo mode works with zero merchant credentials; see sponsor/README.md.

• 💳 Personal Edition — $10/mo — a subscription tier sold through the same gateway: bound to your GitHub handle or email, billed ¥72/mo via WeChat/Alipay (rate configurable), renewal simply stacks another 30 days. Entitlement status is a single API: GET /api/subscription/:handle.

Contributing

Issues and PRs welcome — especially new decoy tool designs and injection payloads for the eval suite. Please keep decoys inert; see SECURITY.md for the guarantees contributors must preserve.

License

MIT