Snyk Agent Scan

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

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

Agent Scan v0.5.x (planejado para descontinuação)

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 as versões. Não recomendamos a criação de fluxos de trabalho de produção que dependam de campos específicos da saída da CLI ou de códigos de problema.

Agent Scan v0.6 e posterior

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 as versões. Não recomendamos a criação de fluxos de trabalho de produção que dependam de campos específicos da saída da CLI ou de nomes de risco.

Se você é um cliente empresarial que usa o Snyk para gerenciar o risco de segurança de agentes em grande 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 sustentam 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 produto da Snyk. Fale com sua equipe de contas para obter orientação 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 à varredura de skills de agentes.

Saída do Agent Scan v0.5.x

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

Saída do Agent Scan v0.6 e posterior

O Agent Scan ajuda você a descobrir todos os componentes de agentes instalados (harnesses, servidores MCP e skills) e a analisá-los em busca de ameaças comuns, como injeções de prompt, tratamento de dados confidenciais ou cargas de malware ocultas em linguagem natural. Para ignorar a análise de skills, use --no-skills.

Aviso de Segurança

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

Quando o Agent Scan analisa 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 as descrições das ferramentas e realizar a análise de segurança.

Recomendações:

• Execute as varreduras dentro de um sandbox (contêiner Docker, máquina virtual 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 varreduras interativas; 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, nos quais você verificou todos os comandos dos servidores MCP

Por padrão, o Agent Scan exige consentimento explícito do usuário (y/n) antes de iniciar cada servidor MCP stdio em execuções interativas. Isso dá a você 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 a 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 varredura: ```bash export SNYK_TOKEN=your-api-token-here
   root@kitploit:~

Run with uvx

Have uv installed on your system. Choose the instructions for your CLI version.

Agent Scan v0.5.x

The examples pin v0.5.17 as a concrete v0.5.x release:```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 depreciação.

#### Agent Scan v0.6 e posterior```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 posterior 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

Baixe o binário para o seu sistema operacional e arquitetura na última versão do GitHub. A página da versão também fornece um SBOM (sbom-<version>.json), arquivos de checksum e arquivos de código-fonte gerados pelo GitHub. Consulte Verificando binários autônomos para verificar o seu download.

Exemplo de execução do Agent Scan v0.5.x

Para a saída baseada em risco da v0.6, veja a imagem da v0.6 no topo deste README.

Destaques

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

Agent Scan v0.5.x

• Detecta 15+ riscos de segurança distintos em servidores MCP e skills de agentes:
  • MCP: Injeção de Prompt, Envenenamento de Ferramentas, Sombra de Ferramentas, Fluxos Tóxicos
  • Skills: Injeção de Prompt, Payloads de Malware, Conteúdo Não Confiável, Tratamento de Credenciais, Segredos Codificados

Agent Scan v0.6 e posterior

• Detecta 15 riscos de segurança distintos em servidores MCP e skills de agentes:
  • MCP: Injeção de prompt, palavras perigosas, conteúdo não confiável, dados privados e capacidades destrutivas
  • Skills: injeção de prompt, downloads suspeitos, código malicioso, tratamento de credenciais, detecção de segredos e mais

Agentes e capacidades suportados

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

• ✓: pelo menos um caminho está definido para essa capacidade.
• ✗: o agente está listado para esse SO, mas não possui 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 detecção por escopo

A matriz acima mostra em quais sistemas operacionais cada agente é verificado. Esta tabela detalha a detecção por escopo de configuração e tipo de componente (skills vs servidores MCP), combinados entre sistemas operacionais. "Servers" significa servidores MCP.

Os quatro escopos:

• Sistema — configuração em toda a máquina / gerenciada pelo administrador / corporativa que se aplica a todos os usuários (ex.: managed-mcp.json, arquivos em /etc, /Library/Application Support ou ProgramData).
• Usuário — a configuração do diretório pessoal do usuário (aplica-se a todos os seus projetos).
• Projeto / workspace — configuração com escopo em um projeto ou espaço de trabalho aberto.
• Extensão / plugin — componentes empacotados dentro de extensões ou plugins instalados.

Legenda: ✓ detectado · ✗ o agente suporta isso, mas o Agent Scan ainda não o verifica · N/A o agente não possui esse componente nesse escopo.

† O OpenClaw não tem enumeração de projeto aberto: 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 as skills de escopo do usuário ~/.config/agents/skills são detectadas atualmente, portanto, skills de escopo de projeto são suportadas, mas ainda não são verificadas.

Verificando binários autônomos

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

Guia de verificação passo a passo

1. Baixe os artefatos da versão: Baixe o binário para a sua plataforma (ex.: agent-scan-<version>-<os>-<arch>) e o arquivo de checksums assinado (sha256sums.txt.asc) da página de GitHub Releases para o mesmo diretório.

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

   root@kitploit:~

Procure uma linha na saída que diga 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 exibirá agent-scan-<version>-<os>-<arch>: OK.

Recursos do Scanner

Agent Scan v0.5.x

O Agent Scan é uma ferramenta de varredura de segurança que escaneia e inspeciona a cadeia de suprimentos dos componentes de agente na sua máquina. Ele procura 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 versões 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 maliciosas de agentes.

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 agente, como habilidades e servidores MCP. Ao concluir, ele produzirá 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 a uma instância do Snyk Evo. Isso pode ser usado por equipes de segurança para monitorar a cadeia de suprimentos de agentes em toda a empresa em um local central. Para configurar isso, entre em contato conosco.

Como Funciona

Varredura

O Agent Scan pesquisa nos arquivos de configuração do seu agente local para encontrar agentes, habilidades e servidores MCP. Para MCP, ele conecta-se 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. Esse fluxo de consentimento:

• Mostra o nome do servidor, o comando e as variáveis de ambiente (ocultas) 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)

Boas 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 uma 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 essa 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 dos componentes necessárias para a análise, incluindo detalhes do aplicativo de agente, configurações e assinaturas dos servidores MCP, nomes e descrições de ferramentas e conteúdo das habilidades. Segredos em valores de configuração e textos são ocultados 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 versões 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 no v0.5.x quanto no v0.6 e posteriores. Sua aplicabilidade de comando é 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
--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] 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` chaveado por caminho. Consulte a [referência da CLI v0.5.x](https://github.com/snyk/agent-scan/blob/HEAD/docs/cli-reference.md#agent-scan-v05x) e a [referência de códigos de problema](https://github.com/snyk/agent-scan/blob/HEAD/docs/issue-codes.md).

### Agent Scan v0.6 e posterior```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

Versões v0.6 e posteriores emitem indicadores de risco pontuados e o JSON de scan_path_responses. A saída de varredura legível por humanos é compacta por padrão; --show-full-discovery a expande sem alterar a saída JSON ou inspect. Consulte a referência de 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

## Demo

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

Como demonstrar as 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 issue-code): 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.

O Agent Scan está fechado para contribuições

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

Aceitamos sugestões, relatórios de bugs ou solicitações de recursos como issues do GitHub.

Configuração de Desenvolvimento

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

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

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

## Documentação

- [Índice da documentação](https://github.com/snyk/agent-scan/blob/HEAD/docs/README.md) — Documentação versionada para ambas as linhas de CLI.
- [Referência da CLI](https://github.com/snyk/agent-scan/blob/HEAD/docs/cli-reference.md) — Comandos, flags, opções e variáveis de ambiente para v0.5.x e v0.6 em diante.
- [Varredura](https://github.com/snyk/agent-scan/blob/HEAD/docs/scanning.md) — Comportamento e exemplos de varredura para v0.5.x e v0.6 em diante.
- [Saída JSON](https://github.com/snyk/agent-scan/blob/HEAD/docs/json-output.md) — A saída indexada por caminho da v0.5.x e o esquema de resposta da v0.6.
- [Códigos de problema](https://github.com/snyk/agent-scan/blob/HEAD/docs/issue-codes.md) — Referência de achados de segurança `E*` e `W*` da v0.5.x.
- [Referência de riscos](https://github.com/snyk/agent-scan/blob/HEAD/docs/risks.md) — Indicadores, pontuações e campos de evidência de risco de segurança da v0.6.
- [Códigos de falha](https://github.com/snyk/agent-scan/blob/HEAD/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 ferramenta de 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 habilidades](https://github.com/snyk/agent-scan/blob/HEAD/.github/reports/skills-report.pdf)

## Histórico de alterações

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