agent-canary

agent-canary

Armadilhas com zero falso-positivo para agentes de IA. Saiba instantaneamente quando seu agente de codificação foi sequestrado por uma injeção de prompt — não porque uma heurística adivinhou, mas porque ele tocou em um chamariz que nada legítimo jamais toca.

Documentação em chinês: README.zh-CN.md

---

A ideia em 20 segundos

Um dono de loja coloca um cofre falso ligado a um alarme nos fundos. Nenhum cliente real jamais toca nele — então, se o alarme disparar, alguém está roubendo a loja. Ponto final. Zero falso-positivos.

O agent-canary faz o mesmo para agentes de IA (Claude Code, Cursor, Cline, suas próprias construções) que podem ler arquivos, executar comandos e chamar APIs na sua máquina:

1. Ferramentas MCP chamariz — uma ferramenta falsa de transferência bancária, um leitor falso de segredos de produção, um falso "executar shell como root". Um agente saudável nunca as chama. Um sequestrado chama, e você é alertado com o contexto completo do ataque.
2. Tokens canários — strings cnry_… únicas e sem valor plantadas em arquivos honeypot. Se um deles aparecer na saída de um agente, em um arquivo exfiltrado ou em uma requisição de saída, um segredo foi roubado. É isso.

Cada resposta falsa que um chamariz retorna incorpora um token de rastreamento descartável novo — então, se o payload do atacante exfiltrar os "segredos roubados", o token informa exatamente de qual chamada de ferramenta ele veio.

Por que não apenas escanear por injeções de prompt?

Detectores de injeção pontuam texto e adivinham. Eles afogam você em falso-positivos ou perdem payloads novos. Canários invertem o problema:

	Detectores de injeção	agent-canary
Sinal	"este prompt parece suspeito"	"o chamariz foi tocado"
Falso-positivos	muitos	zero por construção
Detecta ataques novos	às vezes	sim — qualquer comprometimento toca um chamariz
Configuração	treinar/ajustar/encanar tudo	uma linha de configuração MCP

Ambas as abordagens podem coexistir; canários são o alarme que nunca grita "lobo".

Início 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

Pacote npm em lançamento — se npm install -g agent-canary ainda não estiver disponível, instale a partir do código-fonte (Node 20+):

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

Reinicie seu editor. O agente agora vê 8 ferramentas chamariz de aparência tentadora que ele nunca deve tocar. Se tocar:

$ 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

Combine a verificação de tokens com qualquer coisa que você já executa:

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

Como os chamarizes parecem (para o agente)

O agente vê ferramentas tentadoras, de nível administrativo. Nenhuma delas faz nada — cada manipulador é inerte e retorna saída fabricada:

Ferramenta chamariz	O que um agente sequestrado pensa que recebe
canary_transfer_funds	Transferência bancária ADMIN, aprovada automaticamente abaixo de 50 mil
canary_read_secrets	chaves de API de produção para qualquer ambiente
canary_run_shell	comando arbitrário como root no servidor de build
canary_delete_files	exclusão permanente, sem lixeira, sem desfazer
canary_send_email	e-mail de qualquer endereço interno, SPF ignorado
canary_export_database	dump CSV de tabela completa, sem registro de auditoria
canary_fetch_internal	painel administrativo interno da rede confiável
canary_disable_security	proteção de endpoint desativada

E o alerta que você recebe traz o quadro completo: qual chamariz, com quais argumentos, quando, além de um token de rastreamento por chamada.

Garantias rígidas

• Ferramentas chamariz são inertes. canary_run_shell não executa comandos; canary_transfer_funds não toca em dinheiro. Cada manipulador retorna um falso plausível — nada mais. Veja SECURITY.md.
• Tokens canários não desbloqueiam nada. São strings cnry_… aleatórias sem significado em lugar nenhum.
• Sem telemetria. Eventos permanecem em ~/.agent-canary/events.jsonl na sua máquina, a menos que você configure um webhook.
• Zero falso-positivos por construção. Chamarizes e tokens ficam fora de todo fluxo de trabalho legítimo; tocá-los é o sinal.

Referência da 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>

A configuração fica em ~/.agent-canary/config.json:

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

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

Roteiro

• v0.1 — servidor MCP chamariz, tokens canários, monitoramento de arquivos, alertas JSONL + webhook + desktop
• v0.2 — modo de avaliação: execute uma suíte curada de injeção de prompt (20 payloads, 7 categorias) contra qualquer modelo compatível com OpenAI ou Anthropic, gere uma pontuação de resistência reproduzível — agent-canary eval
• v0.3 — painel e exportação SIEM: linha do tempo de cadeia de ataque HTML autocontida (agent-canary dashboard --open) + exportação CEF / JSON / CSV para Splunk / Elastic / ArcSight (agent-canary export)
• v0.4 — instrumentação de SDK além do MCP: import { decoyToolDefs, runDecoy, createTokenGuard } from "agent-canary/sdk" — LangChain.js / Vercel AI SDK / loops de provedor brutos recebem os mesmos chamarizes, tokens de rastreamento e proteção contra vazamento com zero falso-positivo em três linhas

O roteiro agora está totalmente entregue. O que vem a seguir é guiado pelos usuários — abra uma issue com seu cenário de implantação.

Uso com agentes não-MCP (modo SDK)

Código de agente personalizado (LangChain.js, Vercel AI SDK, loops de provedor brutos) recebe as mesmas armadilhas sem 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 ferramentas Anthropic nativos. Chamadas chamariz nunca executam nada real — veja SECURITY.md.

Compatibilidade

Node 20+, Windows / macOS / Linux. Funciona com qualquer cliente compatível com MCP (Claude Code, Cursor, Cline, Windsurf, …). O verificador de tokens e o monitor funcionam com qualquer agente, MCP ou não.

Gratuito vs Pessoal

	Gratuito (para sempre)	Pessoal ($10/mês)
Servidor MCP chamariz · tokens canários · monitoramento · alertas · instalação	✅	✅
Modo de avaliação — pontuação de resistência a injeção (eval)	—	✅
Painel de cadeia de ataque (dashboard)	—	✅
Exportação SIEM — CEF / JSON / CSV (export)	—	✅
Modo SDK — agent-canary/sdk para agentes não-MCP	—	✅

A proteção principal permanece gratuita para sempre — esse é o acordo. Compre uma assinatura Pessoal na página do patrocinador (WeChat / Alipay) e ative:

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

A ativação verifica sua assinatura uma vez e a armazena localmente com tolerância offline até o vencimento.

Apoie este projeto

O agent-canary é gratuito, local e sem telemetria — mas a promoção paga e a hospedagem são financiadas do próprio bolso. Se ele já pegou uma injeção para você:

• ⭐ Dê uma estrela no repositório — genuinamente a coisa de maior valor que você pode fazer para a descoberta
• 💳 GitHub Sponsors — o botão de patrocinador no topo deste repositório
• 🧧 WeChat Pay / Alipay — um gateway de patrocinador auto-hospedado acompanha sponsor/: um servidor de arquivo único que renderiza uma página de doação por QR e verifica WeChat Pay (assinaturas API v3 + callbacks AES-GCM) e Alipay (notificações RSA2) de ponta a ponta. O modo de demonstração funciona sem credenciais de comerciante; veja sponsor/README.md.
• 💳 Edição Pessoal — $10/mês — um nível de assinatura vendido pelo mesmo gateway: vinculado ao seu usuário do GitHub ou e-mail, cobrado ¥72/mês via WeChat/Alipay (taxa configurável), a renovação simplesmente adiciona mais 30 dias. O status de direito é uma única API: GET /api/subscription/:handle.

Contribuindo

Issues e PRs são bem-vindos — especialmente novos designs de ferramentas chamariz e payloads de injeção para a suíte de avaliação. Por favor, mantenha os chamarizes inertes; veja SECURITY.md para as garantias que os contribuidores devem preservar.

Licença

MIT