Agent Canary

Tripwire detection for autonomous AI agents.

What it does

Plants canary tokens in your codebase, MCP tool surface, and API endpoints. When an agent reads a honeypot file, calls a tripwire tool, or hits a decoy API route, Agent Canary logs a structured trigger with the forensic chain (arguments, headers, client IP, preceding tool calls). You see scope creep and unauthorized tool use without changing production app logic.

Related MCP server: AgentShield

Install

From GitHub (this is the source of truth; not on PyPI):

pip install "git+https://github.com/SamsonCyber/agent-canary.git"
# pin a release tag


![agent-canary banner](banner.jpg)
pip install "git+https://github.com/SamsonCyber/agent-canary.git@v0.2.0"
# optional MCP tripwire server extras


![agent-canary banner](banner.jpg)
pip install "git+https://github.com/SamsonCyber/agent-canary.git#egg=agent-canary[mcp]"

Quickstart

# Initialize in your project root


![agent-canary banner](banner.jpg)
agent-canary init

# Plant honeypot files (default --notice off: silent honeypot)


![agent-canary banner](banner.jpg)
agent-canary plant file .env.production --template aws_creds
agent-canary plant file secrets/database.yml --template db_creds

# Soft scope notice for measurement (static | stochastic)


![agent-canary banner](banner.jpg)
agent-canary plant file traps/.env.prod --template aws_creds --notice stochastic

# Register MCP tripwire tools


![agent-canary banner](banner.jpg)
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"

# Register API decoy endpoints


![agent-canary banner](banner.jpg)
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

# See what's deployed


![agent-canary banner](banner.jpg)
agent-canary list

# Start watching for triggers


![agent-canary banner](banner.jpg)
agent-canary watch

MCP integration

Add the tripwire MCP server to your claude_desktop_config.json:

{
 "mcpServers": {
 "canary": {
 "command": "agent-canary",
 "args": ["serve-mcp", "--stdio"]
 }
 }
}

The server exposes tripwire tools via JSON-RPC. Any agent that calls one of these tools gets logged with full forensic context, then receives a plausible permission-denied error.

Three vectors

File honeypots. Generate realistic credential files, API key configs, PII exports, and internal documents from 6 built-in templates. Monitors with watchdog (polling fallback). Manual access checks work for MCP wrappers that intercept read_file.

MCP tripwire tools. Register fake high-privilege tools (5 defaults: execute_sql_admin, send_email, export_user_data, modify_production_config, delete_resources). On call, they log full arguments and return a plausible permission-denied error.

API decoy endpoints. Serve fake HTTP routes (4 defaults: bulk export, admin config, cloud metadata credentials, Vault-style secrets) and capture headers, body, query parameters, and client IP.

Alerts

Configure webhook, Slack, or Discord notifications:

# Generic webhook


![agent-canary banner](banner.jpg)
agent-canary alert add webhook https://your-server.com/canary-hook

# Slack incoming webhook


![agent-canary banner](banner.jpg)
agent-canary alert add slack https://hooks.slack.com/services/T.../B.../xxx

# Discord webhook


![agent-canary banner](banner.jpg)
agent-canary alert add discord https://discord.com/api/webhooks/123/abc

# Test all configured destinations


![agent-canary banner](banner.jpg)
agent-canary alert test

# List configured destinations


![agent-canary banner](banner.jpg)
agent-canary alert list

Alerts fire on every trigger event with structured payloads containing the canary ID, vector type, severity, forensic chain, and agent fingerprint.

File templates

Each template embeds the canary ID in a format-plausible way so the lure stays traceable without looking like a tripwire.

Scope rules

Canaries support allow/deny lists to cut false positives:

• allow_agents: listed agents never trigger. Anyone else does.

• deny_agents: only listed agents trigger. Everyone else is ignored.

• Both set: allow list wins (allowlisted agents stay safe).

• Neither set: universal canary; everything triggers.

Scope notices (agent robots.txt)

Optional soft boundary text returned with a tripwire response. Default plant mode is off so existing silent honeypots stay silent.

What you get in forensics:

• scope_notice on each TriggerEvent (notice_id, family, access_n, text, mode)

• access_count on the canary (retries escalate wording after 3 hits)

• File plants: notice banner prepended at plant time when mode is not off

• MCP / API: notice merged into the JSON error body the agent sees

What this is not:

• Not a hard control. Agents can ignore or paraphrase soft text.

• Not a fix for accidental agent "hacking" in production. Use hard scope gates, tool allowlists, and network policy for that.

• Measurement and forensics first: did the agent see the notice, retry, or change path?

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

Triggers with notices appear in agent-canary triggers --format json under scope_notice.

How it differs from existing tools

Agent Canary records agent-specific forensics (tool arguments, reasoning traces when available, agent fingerprints) so you can tell scope creep from injection or unexpected tool use. No separate honeypot host required.

License

MIT