agent-canary

Señuelos de cero falsos positivos para agentes de IA: 8 herramientas MCP inertes de engaño (transferencia falsa, lector de secretos de producción, shell sudo) más tokens canarios plantados en archivos honeypot. Cualquier toque es una señal de compromiso: detección de inyección de prompts con contexto completo del ataque. MIT, funciona con Claude Code / Cursor / cualquier cliente MCP.

GitHubPrueba este MCPPatrocinado

Documentación

agent-canary

CI License: MIT Node

Señuelos con cero falsos positivos para agentes de IA. Entérate al instante cuando tu agente de codificación ha sido secuestrado por una inyección de prompt — no porque un heurístico lo adivinó, sino porque tocó un señuelo que nada legítimo toca jamás.

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

agent-canary demo

La idea en 20 segundos

El dueño de una tienda coloca una caja fuerte falsa conectada a una alarma en el cuarto trasero. Ningún cliente real la toca jamás — así que si la alarma suena, alguien está robando la tienda. Punto. Cero falsos positivos.

agent-canary hace lo mismo para los agentes de IA (Claude Code, Cursor, Cline, tus propias construcciones) que pueden leer archivos, ejecutar comandos y llamar APIs en tu máquina:

  1. Herramientas MCP señuelo — una herramienta falsa de transferencia bancaria, un lector falso de secretos de producción, un "ejecutar shell como root" falso. Un agente sano nunca las llama. Uno secuestrado lo hace, y recibes una alerta con el contexto completo del ataque.
  2. Tokens canarios — cadenas cnry_… únicas y sin valor plantadas en archivos honeypot. Si alguna aparece en la salida de un agente, en un archivo exfiltrado o en una solicitud saliente, un secreto fue robado. Eso es todo.

Cada respuesta falsa que devuelve un señuelo incorpora un token de rastreo de un solo uso fresco — así que si el payload del atacante exfiltra los "secretos robados", el token te dice exactamente de qué llamada a herramienta provino.

¿Por qué no simplemente escanear inyecciones de prompt?

Los detectores de inyección puntúan el texto y adivinan. Te ahogan en falsos positivos o pasan por alto payloads novedosos. Los canarios invierten el problema:

Detectores de inyecciónagent-canary
Señal"este prompt parece sospechoso""el señuelo fue tocado"
Falsos positivosmuchoscero por construcción
Detecta ataques novedososa vecessí — cualquier compromiso toca un señuelo
Configuraciónentrenar/ajustar/tubería todouna línea de configuración MCP

Ambos enfoques pueden coexistir; los canarios son la alarma que nunca grita "lobo".

Inicio rápido

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

El paquete npm se está implementando — si npm install -g agent-canary aún no está disponible, instala desde el código fuente (Node 20+):

git clone https://github.com/DorianChn/agent-canary.git && cd agent-canary
npm install && npm run build && npm link

Reinicia tu editor. El agente ahora ve 8 herramientas señuelo de aspecto jugoso que nunca debería tocar. Si lo hace:

$ 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

Combina el escaneo de tokens con cualquier cosa que ya ejecutes:

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

Cómo se ven los señuelos (para el agente)

El agente ve herramientas tentadoras de nivel administrador. Ninguna de ellas hace nada — cada manejador es inerte y devuelve salida fabricada:

Herramienta señueloLo que un agente secuestrado cree que obtiene
canary_transfer_fundsTransferencia bancaria ADMIN, aprobada automáticamente bajo 50k
canary_read_secretsclaves API de producción para cualquier entorno
canary_run_shellcomando arbitrario como root en el servidor de compilación
canary_delete_fileseliminación permanente, sin papelera, sin deshacer
canary_send_emailcorreo desde cualquier dirección interna, SPF omitido
canary_export_databasevolcado CSV de tabla completa, sin entrada de auditoría
canary_fetch_internalpanel de administración interno desde la red confiable
canary_disable_securityprotección de endpoint desactivada

Y la alerta que recibes lleva el panorama completo: qué señuelo, con qué argumentos, cuándo, más un token de rastreo por llamada.

Garantías sólidas

  • Las herramientas señuelo son inertes. canary_run_shell no ejecuta comandos; canary_transfer_funds no toca dinero. Cada manejador devuelve un falso plausible — nada más. Ver SECURITY.md.
  • Los tokens canarios no desbloquean nada. Son cadenas cnry_… aleatorias sin significado en ningún lugar.
  • Sin telemetría. Los eventos permanecen en ~/.agent-canary/events.jsonl en tu máquina a menos que tú configures un webhook.
  • Cero falsos positivos por construcción. Los señuelos y tokens están fuera de todo flujo de trabajo legítimo; tocarlos es la señal.

Referencia de CLI

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>

La configuración vive en ~/.agent-canary/config.json:

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

Cómo funciona

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)
└───────────────────────────────┘

Hoja de ruta

  • v0.1 — servidor MCP señuelo, tokens canarios, vigilancia de archivos, alertas JSONL + webhook + escritorio
  • v0.2 — modo eval: ejecuta una suite curada de inyección de prompt (20 payloads, 7 categorías) contra cualquier modelo compatible con OpenAI o Anthropic, genera una puntuación reproducible de resistencia — agent-canary eval
  • v0.3 — panel y exportación SIEM: línea de tiempo autocontenida de cadena de ataque en HTML (agent-canary dashboard --open) + exportación CEF / JSON / CSV para Splunk / Elastic / ArcSight (agent-canary export)
  • v0.4 — instrumentación SDK más allá de MCP: import { decoyToolDefs, runDecoy, createTokenGuard } from "agent-canary/sdk" — LangChain.js / Vercel AI SDK / bucles de proveedor crudos obtienen los mismos señuelos, tokens de rastreo y protección de fugas de cero falsos positivos en tres líneas

La hoja de ruta ahora está completamente implementada. Lo que sigue está impulsado por los usuarios — abre un issue con tu escenario de implementación.

Uso con agentes no-MCP (modo SDK)

El código de agente personalizado (LangChain.js, Vercel AI SDK, bucles de proveedor crudos) obtiene los mismos señuelos sin MCP:

import { generateText } from "ai";                       // any framework, same pattern
import { decoyToolDefs, isDecoy, runDecoy, createTokenGuard } from "agent-canary/sdk";

const guard = createTokenGuard();                        // zero-false-positive leak scanner
const toolDefs = [...myRealToolSchemas, ...decoyToolDefs("openai")];

const { text, toolCalls } = await myAgentLoop(toolDefs); // your existing loop

for (const call of toolCalls) {
  if (isDecoy(call.name)) await runDecoy(call.name, call.args); // inert + audited 🚨
}
guard.inspect(text, "final-answer");                     // any leaked token fires an alert

decoyToolDefs("anthropic") emite esquemas de herramientas nativos de Anthropic. Las llamadas señuelo nunca ejecutan nada real — ver SECURITY.md.

Compatibilidad

Node 20+, Windows / macOS / Linux. Funciona con cualquier cliente compatible con MCP (Claude Code, Cursor, Cline, Windsurf, …). El escáner de tokens y el vigilante funcionan con cualquier agente, MCP o no.

Gratis vs Personal

Gratis (para siempre)Personal ($10/mes)
Servidor MCP señuelo · tokens canarios · vigilancia · alertas · instalación✅✅
Modo eval — puntuación de resistencia a inyección (eval)—✅
Panel de cadena de ataque (dashboard)—✅
Exportación SIEM — CEF / JSON / CSV (export)—✅
Modo SDK — agent-canary/sdk para agentes no-MCP—✅

La protección principal permanece gratis para siempre — ese es el trato. Compra una suscripción Personal en la página de patrocinador (WeChat / Alipay), luego activa:

agent-canary activate --handle <your GitHub username or email>

La activación verifica tu suscripción una vez y la almacena localmente con gracia sin conexión hasta su vencimiento.

Apoya este proyecto

agent-canary es gratis, local y sin telemetría — pero la promoción pagada y el alojamiento se financian de tu bolsillo. Si alguna vez atrapa una inyección por ti:

  • ⭐ Da estrella al repositorio — genuinamente lo más valioso que puedes hacer para el descubrimiento
  • 💳 GitHub Sponsors — el botón de patrocinador en la parte superior de este repositorio
  • 🧧 WeChat Pay / Alipay — una pasarela de patrocinador autohospedada se incluye en sponsor/: un servidor de un solo archivo que renderiza una página de donación con código QR y verifica WeChat Pay (firmas API v3 + callbacks AES-GCM) y Alipay (notificaciones RSA2) de extremo a extremo. El modo demo funciona con cero credenciales de comerciante; ver sponsor/README.md.
  • 💳 Edición Personal — $10/mes — un nivel de suscripción vendido a través de la misma pasarela: vinculado a tu usuario de GitHub o correo, facturado ¥72/mes vía WeChat/Alipay (tasa configurable), la renovación simplemente agrega otros 30 días. El estado de derecho es una sola API: GET /api/subscription/:handle.

Contribuciones

Issues y PRs bienvenidos — especialmente nuevos diseños de herramientas señuelo y payloads de inyección para la suite de eval. Por favor mantén los señuelos inertes; ver SECURITY.md para las garantías que los contribuyentes deben preservar.

Licencia

MIT