Snyk Agent Scan

Descubra e escaneie componentes de agentes na sua máquina em busca de injeções de prompt
e vulnerabilidades (incluindo agentes, servidores MCP, skills).

Nota: Não publicamos um pacote npm para o Agent Scan. Instale-o via uvx ou como um binário autônomo.

Nota: A saída da CLI é experimental e está sujeita a alterações

Agent Scan v0.5.x (com descontinuação planejada)

A saída bruta desta CLI — incluindo códigos de problema, nomes de campos, rótulos de severidade e estrutura de resposta — é experimental e pode mudar sem aviso entre versões. Não recomendamos criar fluxos de trabalho de produção que dependam de campos de saída específicos da CLI ou códigos de problema.

Agent Scan v0.6 e posteriores

A saída bruta desta CLI — incluindo nomes de indicadores de risco, pontuações, nomes de campos e estrutura de resposta — é experimental e pode mudar sem aviso entre versões. Não recomendamos criar fluxos de trabalho de produção que dependam de campos de saída específicos da CLI ou nomes de risco.

Se você é um cliente empresarial que usa o Snyk para gerenciar riscos de segurança de agentes em escala, a saída da CLI pode não refletir o que é enviado e exibido na plataforma Evo. A integração subjacente, a descoberta e a avaliação de risco que alimentam as implantações empresariais são estáveis e suportadas — quaisquer alterações serão comunicadas de acordo com as práticas padrão de produtos da Snyk. Entre em contato com sua equipe de contas para obter orientações de implantação.

NOVO Leia nosso relatório técnico sobre as ameaças emergentes do ecossistema de skills de agentes publicado junto com o Agent Scan 0.4, que adiciona suporte para escanear skills de agentes.

Saída do Agent Scan v0.5.x

[!WARNING] O Agent Scan v0.5.x usa saída com códigos de problema. Esta linha da CLI tem descontinuação planejada.

Saída do Agent Scan v0.6 e posteriores

O Agent Scan ajuda você a descobrir todos os componentes de agentes instalados (harnesses, servidores MCP e skills) e os escaneia em busca de ameaças comuns, como injeções de prompt, manuseio de dados sensíveis ou cargas maliciosas ocultas em linguagem natural. Ignore a análise em skills usando --no-skills.

Aviso de Segurança

⚠️ IMPORTANTE: O escaneamento de configurações MCP executará os comandos definidos nelas.

Quando o Agent Scan escaneia um arquivo de configuração MCP, ele inicia os servidores MCP stdio executando os comandos e argumentos especificados na configuração. Isso é necessário para recuperar descrições de ferramentas e realizar a análise de segurança.

Recomendações:

• Execute os escaneamentos dentro de um sandbox (contêiner Docker, VM ou ambiente descartável) ao avaliar configurações MCP não confiáveis ou de terceiros
• Revise o prompt de consentimento com atenção durante escaneamentos interativos, ele mostra o comando e os argumentos exatos que serão executados para cada servidor
• Use --dangerously-run-mcp-servers apenas em ambientes confiáveis onde você verificou todos os comandos dos servidores MCP

Por padrão, o Agent Scan exige consentimento explícito do usuário (s/n) antes de iniciar cada servidor MCP stdio durante execuções interativas. Isso lhe dá controle sobre o que é executado no seu sistema.

Início Rápido

Escolha uma das duas maneiras de executar o Agent Scan:

1. Execute o pacote Python com uvx usando as instruções abaixo.
2. Baixe um binário autônomo para sua plataforma em GitHub Releases. As versões também incluem o SBOM, checksums, checksums assinados e arquivos de código-fonte.

Antes de usar qualquer uma das opções:

1. Cadastre-se no Snyk e obtenha um token de API em https://app.snyk.io/account (API Token → KEY → clique para mostrar).
2. Defina o token como uma variável de ambiente antes de executar qualquer escaneamento: ```bash export SNYK_TOKEN=your-api-token-here
   root@kitploit:~

Executar com uvx

Tenha o uv instalado no seu sistema. Escolha as instruções para a versão da sua CLI.

Agent Scan v0.5.x

Os exemplos fixam a v0.5.17 como uma versão concreta da v0.5.x:```bash

Scan the whole machine

uvx [email protected]

Scan a specific MCP configuration

uvx [email protected] ~/.vscode/mcp.json

Scan a single agent skill

uvx [email protected] ~/path/to/my/SKILL.md

Scan all Claude skills

uvx [email protected] ~/.claude/skills

> [!WARNING]
> v0.5.x usa saída de código de problema e a API de análise `2025-09-02`. Esta linha de CLI está planejada para descontinuação.

#### Agent Scan v0.6 e posteriores```bash
# Scan the whole machine
uvx snyk-agent-scan@latest

# Scan a specific MCP configuration
uvx snyk-agent-scan@latest ~/.vscode/mcp.json

# Scan a single agent skill
uvx snyk-agent-scan@latest ~/path/to/my/SKILL.md

# Scan all Claude skills
uvx snyk-agent-scan@latest ~/.claude/skills

v0.6 e versões posteriores usam a saída baseada em risco e a API de análise 2026-07-10.

Ambas as versões escaneiam servidores MCP, ferramentas, prompts, recursos e skills, e descobrem automaticamente configurações de agentes suportadas, como Claude Code/Desktop, Cursor, Gemini CLI e Windsurf.

Executar com um binário autónomo

Descarregue o binário para o seu sistema operativo e arquitetura a partir da última versão do GitHub. A página de lançamento também disponibiliza um SBOM (sbom-<version>.json), ficheiros de checksum e arquivos de código-fonte gerados pelo GitHub. Consulte Verificar Binários Autónomos para verificar a sua transferência.

Destaques

• Descoberta automática de configurações MCP, ferramentas de agentes, skills
• Escaneamento de Claude, Cursor, GitHub Copilot, Windsurf, Gemini CLI, Amp, Amazon Q e outros agentes.

Agent Scan v0.5.x

• Deteta mais de 15 riscos de segurança distintos em servidores MCP e skills de agentes:
  • MCP: Prompt Injection, Tool Poisoning, Tool Shadowing, Toxic Flows
  • Skills: Prompt Injection, Malware Payloads, Untrusted Content, Credential Handling, Hardcoded Secrets

Agent Scan v0.6 e versões posteriores

• Deteta 14 riscos de segurança distintos em servidores MCP e skills de agentes:
  • MCP: Prompt injection, untrusted content, private data e destructive capabilities
  • Skills: prompt injection, suspicious downloads, malicious code, credential handling, secret detection e mais

Agentes e capacidades suportados

O Agent Scan descobre automaticamente agentes e as suas capacidades (servidores MCP ou skills) quando os seus caminhos de instalação existem. A tabela abaixo mostra em que sistemas operativos cada agente é escaneado.

• ✓: pelo menos um caminho está definido para essa capacidade.
• ✗: o agente está listado para esse SO mas não tem caminhos para essa capacidade.
• —: esse agente não está incluído para esse SO.
• Skills As skills podem ser ignoradas usando --no-skills

Cobertura de deteção por âmbito

A matriz acima mostra em que sistemas operativos cada agente é escaneado. Esta decompõe a deteção por âmbito de configuração e tipo de componente (skills vs servidores MCP), combinados entre sistemas operativos. "Servers" significa servidores MCP.

Os quatro âmbitos:

• System — configuração à escala da máquina / gerida por administrador / empresarial que se aplica a todos os utilizadores (por exemplo, managed-mcp.json, ficheiros em /etc, /Library/Application Support ou ProgramData).
• User — configuração no diretório home do utilizador (aplica-se a todos os seus projetos).
• Project / workspace — configuração limitada a um projeto ou workspace aberto.
• Extension / plugin — componentes incluídos em extensões ou plugins instalados.

Legenda: ✓ detetado · ✗ o agente suporta isto mas o Agent Scan ainda não o escaneia · N/A o agente não tem esse componente neste âmbito.

† O OpenClaw não tem enumeração de projetos abertos: as suas skills de projeto/workspace são encontradas apenas no caminho fixo ~/.openclaw/workspace/skills

‡ O Amp armazena skills de projeto/workspace em .agents/skills (e no caminho de compatibilidade .claude/skills); apenas o âmbito de utilizador ~/.config/agents/skills é detetado atualmente, pelo que as skills de âmbito de projeto são suportadas mas ainda não escaneadas.

§ O GitHub Copilot abrange a CLI e a aplicação de desktop, que partilham o home ~/.copilot com o Copilot no VS Code, e é detetado a partir desse home em vez de a partir de uma instalação do VS Code. As realocações de COPILOT_HOME são respeitadas ao escanear o seu próprio home. O âmbito de projeto abrange os ficheiros .mcp.json / .github/mcp.json relativos ao repositório e os diretórios .github/skills, .claude/skills e .agents/skills, para as pastas passadas ao escaneamento e os diretórios que o Copilot registou em permissions-config.json, mais os seus antecessores. O âmbito de plugin abrange ~/.copilot/installed-plugins, incluindo manifestos plugin.json que realocam a sua configuração MCP ou declaram raízes de skills adicionais. Não escaneado: as raízes de projeto por sessão em session-state/*/workspace.yaml. Os caminhos ao nível do utilizador do Copilot também estão listados em VS Code, que lê os mesmos ficheiros.

Verificar Binários Autónomos

Usamos assinatura GPG no ficheiro de checksums da versão para garantir a integridade e autenticidade da distribuição.

Guia de Verificação Passo a Passo

1. Descarregue os recursos da versão: Descarregue o binário para a sua plataforma (por exemplo, agent-scan-<version>-<os>-<arch>) e o ficheiro de checksums assinado (sha256sums.txt.asc) a partir da página GitHub Releases para o mesmo diretório.

2. Verifique a assinatura GPG do ficheiro de checksums: Descarregue a chave pública GPG para o mesmo diretório e, em seguida, execute: ```bash gpg --import snyk-code-signing-public.pgp gpg --verify sha256sums.txt.asc

   root@kitploit:~

Procure por uma linha na saída dizendo gpg: Good signature from "Snyk Limited <[email protected]>".

3. Verifique a integridade do binário: Após confirmar que a assinatura é válida, verifique se o binário baixado corresponde ao checksum:
   • No Linux (ou macOS com coreutils):
     root@kitploit:~

     grep agent-scan-<version>-<os>-<arch> sha256sums.txt.asc | sha256sum -c -
     

   • No macOS (usando o shasum padrão):
     root@kitploit:~

     grep agent-scan-<version>-<os>-<arch> sha256sums.txt.asc | shasum -a 256 -c -
     

   Isso produzirá agent-scan-<version>-<os>-<arch>: OK.

Capacidades do Scanner

Agent Scan v0.5.x

O Agent Scan é uma ferramenta de varredura de segurança para escanear e inspecionar a cadeia de suprimentos de componentes de agentes na sua máquina. Ele procura por vulnerabilidades de segurança comuns, como injeções de prompt, envenenamento de ferramentas, fluxos tóxicos ou vulnerabilidades em habilidades de agentes.

Agent Scan v0.6 e posteriores

O Agent Scan relata indicadores de risco pontuados para ameaças como injeção de prompt, exposição a dados não confiáveis ou privados, capacidades destrutivas e habilidades de agentes maliciosas.

O Agent Scan opera em dois modos principais que podem ser usados em conjunto ou separadamente:

1. Modo de Varredura: O comando CLI snyk-agent-scan escaneia a máquina atual em busca de agentes e componentes de agentes, como habilidades e servidores MCP. Ao concluir, ele emitirá um relatório abrangente para o usuário revisar.

2. Modo em Segundo Plano (MDM). O Agent Scan escaneia a máquina em intervalos regulares em segundo plano e relata os resultados para uma instância do Snyk Evo. Isso pode ser usado por equipes de segurança para monitorar a cadeia de suprimentos de agentes de toda a empresa em um local central. Para configurar isso, por favor, entre em contato conosco.

Como Funciona

Varredura

O Agent Scan procura nos arquivos de configuração do seu agente local para encontrar agentes, habilidades e servidores MCP. Para MCP, ele se conecta aos servidores e recupera as descrições das ferramentas.

Consentimento Interativo para Servidores MCP

⚠️ Nota de Segurança: Escanear uma configuração MCP executa os comandos definidos nela. Sempre revise o que será executado antes de aprovar.

Por padrão, o Agent Scan solicita o consentimento do usuário antes de iniciar cada servidor MCP stdio durante execuções interativas. Este fluxo de consentimento:

• Mostra o nome do servidor, comando e variáveis de ambiente (redigidas) que serão executados
• Permite que você aprove ou recuse cada servidor individualmente
• Impede que servidores potencialmente não confiáveis sejam executados sem sua permissão explícita
• Registra servidores recusados com um erro user_declined (eles nunca são iniciados)

Melhores Práticas:

• Revise o comando e os argumentos cuidadosamente antes de aprovar
• Ao escanear configurações MCP não confiáveis ou de terceiros, execute o Agent Scan dentro de um sandbox (Docker, VM ou ambiente descartável)
• Recuse qualquer servidor com comandos desconhecidos ou suspeitos

Para ambientes não interativos (por exemplo, pipelines de CI/CD), você deve usar a flag --dangerously-run-mcp-servers para ignorar o prompt de consentimento e iniciar todos os servidores automaticamente. Use esta flag apenas em ambientes confiáveis onde todos os comandos dos servidores MCP foram verificados.

Análise e Validação

O Agent Scan valida os componentes descobertos com verificações locais e a API do Agent Scan. Ele envia as informações do componente necessárias para a análise, incluindo detalhes da aplicação do agente, configurações e assinaturas do servidor MCP, nomes e descrições de ferramentas e conteúdo de habilidades. Segredos em valores de configuração e texto são redigidos antes da transmissão.

Ao usar o Agent Scan, você concorda com os termos de uso do Agent Scan da Snyk.

O Agent Scan não armazena nem registra nenhum dado de uso, ou seja, o conteúdo e os resultados das suas chamadas de ferramentas MCP.

Parâmetros da CLI

A referência completa de flags está em docs/cli-reference.md. A maioria dos comandos e flags é compartilhada entre v0.5.x e v0.6 e posteriores.

Comandos compartilhados```text

snyk-agent-scan scan [CONFIG_FILE...] Scan MCP servers and skills (default) snyk-agent-scan inspect [CONFIG_FILE...] Inspect components without analysis snyk-agent-scan help Display help

### Opções compartilhadas por ambas as linhas de versão

Essas opções existem tanto na v0.5.x quanto na v0.6 e posteriores. Sua aplicabilidade de comando está detalhada na referência completa da CLI.```text
--storage-file FILE               Path to store scan state (default: ~/.mcp-scan)
--analysis-url URL                Analysis endpoint; the default API version depends on the CLI version
--verification-H HEADER           Additional analysis request header (repeatable)
--mcp-oauth-tokens-path PATH      OAuth tokens for protected remote MCP servers
--verbose                         Enable detailed logging
--print-errors                    Show error details and tracebacks
--print-full-descriptions         Show full entity descriptions without truncation
--json                            Emit JSON; the response schema depends on the CLI version
--skip-ssl-verify                 Disable TLS certificate verification
--skills / --no-skills            Include skills (default) or skip them
--scan-all-users                  Scan all readable user home directories
--show-analysis-results           Force synchronous analysis so results display for push-key scans
--ci                              Exit non-zero when findings or operational failures remain
--server-timeout SECONDS          MCP connection timeout (default: 10)
--suppress-mcpserver-io BOOL      Suppress stdio MCP server stderr
--dangerously-run-mcp-servers     Skip consent and start configured stdio MCP servers
--control-server URL              Upload destination (repeatable)
--control-server-H HEADER         Header for the current control-server block
--control-identifier ID           Identifier for the current control-server block
--no-bootstrap                    Accepted compatibility no-op; does not change behavior
--checks-per-server NUM           Accepted compatibility no-op; does not change behavior

Agent Scan v0.5.x

[!WARNING] A v0.5.x está planejada para descontinuação. Os exemplos fixam a v0.5.17 como uma versão concreta da v0.5.x.```text --analysis-url URL Defaults to the 2025-09-02 analysis API --ignore-issues-codes CODES Comma-separated E/W security finding codes and X failure codes to ignore in CI

v0.5.x emite descobertas de código de problema e JSON `ScanPathResult` com chave de caminho. Consulte a [referência da CLI v0.5.x](https://github.com/snyk/agent-scan/blob/main/docs/cli-reference.md#agent-scan-v05x) e a [referência de códigos de problema](https://github.com/snyk/agent-scan/blob/main/docs/issue-codes.md).

### Agent Scan v0.6 e posteriores```text
--analysis-url URL                Defaults to the 2026-07-10 analysis API
--ignore-risks NAMES              Comma-separated risk names to omit from output and CI evaluation
--ignore-failure-codes CODES      Comma-separated X codes to omit from CI evaluation
--show-full-discovery             List every MCP entity and skill file instead of compact scan summaries

v0.6 e posteriores emitem indicadores de risco pontuados e JSON scan_path_responses. A saída de varredura legível por humanos é compacta por padrão; --show-full-discovery a expande sem alterar o JSON ou a saída de inspect. Consulte a referência da CLI v0.6 e posteriores, a referência de riscos e a referência de códigos de falha.

Exemplos```bash

Scan all known MCP configs and agent skills

snyk-agent-scan

Scan a specific config file or skill

snyk-agent-scan ~/custom/config.json snyk-agent-scan ~/path/to/my/SKILL.md

Inspect without security analysis

snyk-agent-scan inspect

CI mode

snyk-agent-scan --ci --dangerously-run-mcp-servers

## Demonstração

Este repositório inclui um servidor MCP vulnerável que demonstra descobertas de segurança do Model Context Protocol que o Agent Scan reporta.

Como demonstrar descobertas de segurança do MCP?

1. Clone este repositório
2. Crie um arquivo de configuração `mcp.json` no diretório raiz do repositório git clonado com o seguinte conteúdo:```jsonc
{
  "mcpServers": {
    "Demo MCP Server": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "mcp", "run", "demoserver/server.py"],
    },
  },
}

3. Execute a versão apropriada:

   • Agent Scan v0.5.x (saída de código de problema): uvx --python 3.13 [email protected] scan mcp.json
   • Agent Scan v0.6 e posteriores (saída baseada em risco): uvx --python 3.13 snyk-agent-scan@latest scan mcp.json

Nota: se você colocar o caminho do arquivo de configuração mcp.json em outro local, ajuste o caminho args dentro da configuração do servidor MCP para refletir o caminho para o Servidor MCP (demoserver/server.py), bem como o comando uvx que executa o Agent Scan com o caminho correto para mcp.json.

Agent Scan está fechado a contribuições

O Agent Scan não aceita contribuições externas no momento.

Acolhemos sugestões, relatórios de bugs ou pedidos de funcionalidades como issues no GitHub.

Configuração de Desenvolvimento

Para executar o Agent Scan a partir do código-fonte, siga estes passos:```bash uv run pip install -e . uv run -m src.agent_scan.cli

## Incluindo resultados do Agent Scan em seu próprio projeto / registro

Se você deseja incluir resultados do Agent Scan em seu próprio projeto ou registro, por favor [entre em contato](https://evo.ai.snyk.io/#contact-us). Existem APIs designadas para essa finalidade. Usar a API padrão do Agent Scan para varredura em larga escala é considerado abuso e resultará no bloqueio da sua conta.

## Documentação

- [Índice da documentação](https://github.com/snyk/agent-scan/blob/main/docs/README.md) — Documentação versionada para ambas as linhas de CLI.
- [Referência da CLI](https://github.com/snyk/agent-scan/blob/main/docs/cli-reference.md) — Comandos, flags, opções e variáveis de ambiente das versões v0.5.x e v0.6-and-later.
- [Varredura](https://github.com/snyk/agent-scan/blob/main/docs/scanning.md) — Comportamento e exemplos de varredura das versões v0.5.x e v0.6-and-later.
- [Saída JSON](https://github.com/snyk/agent-scan/blob/main/docs/json-output.md) — A saída com chaves de caminho da v0.5.x e o esquema de resposta da v0.6.
- [Códigos de Problema](https://github.com/snyk/agent-scan/blob/main/docs/issue-codes.md) — Referência de descobertas de segurança `E*` e `W*` da v0.5.x.
- [Referência de riscos](https://github.com/snyk/agent-scan/blob/main/docs/risks.md) — Indicadores de risco de segurança, pontuações e campos de evidência da v0.6.
- [Códigos de falha](https://github.com/snyk/agent-scan/blob/main/docs/failure-codes.md) — Falhas operacionais de descoberta, inspeção e análise da v0.6.

## Leitura Adicional

- [Apresentando o MCP-Scan](https://invariantlabs.ai/blog/introducing-mcp-scan)
- [Ataques de Envenenamento de Ferramentas por Notificação de Segurança do MCP](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks)
- [WhatsApp MCP Explorado](https://invariantlabs.ai/blog/whatsapp-mcp-exploited)
- [Injeção de Prompt no MCP](https://simonwillison.net/2025/Apr/9/mcp-prompt-injection/)
- [Análise de Fluxo Tóxico](https://invariantlabs.ai/blog/toxic-flow-analysis)
- [Relatório de Skills](https://github.com/snyk/agent-scan/blob/main/.github/reports/skills-report.pdf)

## Changelog

Veja [CHANGELOG.md](https://github.com/snyk/agent-scan/blob/main/CHANGELOG.md).