osv-scanner

Um plugin do Claude Code para varredura de vulnerabilidades em dependências e triagem de alcançabilidade.

Documentação

Um plugin Claude Code para varredura de vulnerabilidades em dependências e triagem de alcançabilidade.

Louvado seja o sol. Suas dependências transitivas não o fazem. O OSV Scanner ilumina a masmorra: revelando CVEs conhecidas, buscando avisos completos e usando triagem de alcançabilidade baseada em grep para dizer quais vulnerabilidades realmente vivem em seus caminhos de código.

O que é o Plugin OSV Scanner?

Este plugin integra o OSV Scanner como um servidor MCP no Claude Code. Ele dá ao Claude acesso direto ao banco de dados de vulnerabilidades OSV para escanear as dependências do seu projeto e raciocinar sobre quais descobertas realmente importam.

O que Ele Faz

Escaneia dependências em busca de CVEs conhecidas em npm, pip, Go, Rust, Maven, Ruby e mais
Busca avisos completos: detalhes de CVE, versões afetadas, pontuações CVSS, orientação de correção
Triagem de alcançabilidade: usa análise estática baseada em grep para estimar se APIs vulneráveis são realmente chamadas no seu código-fonte
Prioriza descobertas em níveis FOUND_IN_SOURCE / UNCERTAIN / NOT_FOUND_IN_GREP
Orienta supressão: instruções para ignorar descobertas conhecidas como seguras via configuração do osv-scanner

O que Ele NÃO Faz

Análise determinística de grafo de chamadas (use o --call-analysis nativo do osv-scanner para Go/Rust)
Análise em tempo de execução ou dinâmica
Substituir revisão de segurança humana

Instalação

Pré-requisitos

osv-scanner deve estar instalado e no seu PATH do sistema.

Windows (Scoop):

scoop install osv-scanner

macOS (Homebrew):

brew install osv-scanner

Linux: Baixe dos GitHub Releases

Verifique a instalação:

osv-scanner --version

Nota de segurança: Garanta que o binário osv-scanner no seu PATH seja o lançamento oficial de github.com/google/osv-scanner. O plugin passa dados de avisos do binário diretamente para o loop de raciocínio do Claude. Um binário adulterado poderia fabricar conteúdo de avisos.

Instalar Plugin

No Claude Code:

/plugin marketplace add alejandrosaenz117/bonfires-marketplace
/plugin install osv-scanner@bonfires-marketplace

Ou se testando localmente:

claude --plugin-dir ./plugins/osv-scanner

Três Maneiras de Usar o OSV Scanner

1. Skill: Gatilho Contextual

O plugin ativa quando você pergunta sobre segurança de dependências naturalmente.

user: "Check my dependencies for vulnerabilities"
user: "Are my packages safe?"
user: "Run a security audit on my project"

Frases de gatilho:

"verifique minhas dependências em busca de vulnerabilidades"
"escaneie meus pacotes"
"minhas dependências estão seguras?"
"auditoria de dependências"
"verifique CVEs"
"auditoria de segurança"
"pacotes vulneráveis"
"escaneie dependências em busca de vulnerabilidades"

2. Comando de Varredura

/osv-scanner scan [path]

Escaneia um diretório ou arquivo de bloqueio em busca de vulnerabilidades conhecidas. Padrão: raiz do espaço de trabalho atual.

/osv-scanner scan .
/osv-scanner scan ./src
/osv-scanner scan package-lock.json

3. Comando de Triagem

/osv-scanner triage [path]

Executa uma varredura completa e, em seguida, usa análise estática baseada em grep para estimar quais APIs vulneráveis são realmente alcançáveis no seu código.

/osv-scanner triage .
/osv-scanner triage ./src

Vereditos de Triagem

Veredito	Significado	Ação
FOUND_IN_SOURCE	API vulnerável encontrada via grep no seu código-fonte	Corrija primeiro: atualize ou aplique patch
UNCERTAIN	Dependência transitiva, padrão de código dinâmico ou CVE ampla de pacote	Revise manualmente, provavelmente prioridade média a alta
NOT_FOUND_IN_GREP	Nenhuma correspondência de grep para a API vulnerável	Prioridade menor: monitore, não ignore CRITICAL/HIGH

⚠️ NOT_FOUND_IN_GREP = ausência de evidência, não evidência de ausência. Dependências transitivas e padrões de código dinâmico podem ser alcançáveis mesmo quando não detectados por busca estática.

Segurança: Texto de avisos de get_vulnerability_details é tratado como dado não confiável. Se um binário MCP malicioso fabricasse conteúdo de avisos com instruções injetadas, o comando de triagem é projetado para ignorá-las e basear vereditos somente na severidade CVSS e evidência local de grep.

Como Funciona

Este plugin registra osv-scanner experimental-mcp como um servidor MCP. O Claude pode chamar três ferramentas:

scan_vulnerable_dependencies: Escaneia um caminho em busca de vulnerabilidades
get_vulnerability_details: Recupera o JSON OSV completo para um ID de vulnerabilidade
ignore_vulnerability: Fornece instruções de configuração do osv-scanner para suprimir descobertas

Gerenciadores de Pacotes Suportados

O OSV Scanner detecta e escaneia pacotes de:

npm (package.json, package-lock.json, yarn.lock)
pip (requirements.txt, Pipenv, Poetry)
Maven (pom.xml)
Go (go.mod, go.sum)
Rust (Cargo.toml, Cargo.lock)
Dart (pubspec.yaml, pubspec.lock)
Ruby (Gemfile, Gemfile.lock)
PHP (composer.json, composer.lock)
Java (pom.xml, gradle.lock)
E mais via plugins osv-scalibr

Estrutura do Projeto

plugins/osv-scanner/
├── .claude-plugin/
│   └── plugin.json              # Plugin metadata and MCP server registration
├── commands/
│   ├── scan.md                  # /osv-scanner scan command
│   └── triage.md                # /osv-scanner triage command
├── skills/
│   └── osv-scanner/
│       └── SKILL.md             # Contextual auto-triggered skill
├── banner.png                   # Plugin banner
└── README.md                    # This file

Documentação

Contribuindo

Veja CONTRIBUTING.md para diretrizes sobre adicionar plugins e contribuir.

Licença

Licença MIT. Veja LICENSE para detalhes.

Plugin OSV Scanner: Louvado seja o sol. Suas dependências transitivas não o fazem.