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

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 intenção provavelmente 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, layout de pacotes e como estender o pipeline do analisador.
• Limites de recursos de análise — Limites de bundle, parser, artefatos aninhados, ledger e findings com falha segura.
• Extensão Pi — Instale o SkillSpector como uma ferramenta Pi para escanear skills de dentro de sessões de agentes.
• Extensão OpenCode — Instale o SkillSpector como uma 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, escalação 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 baseline / falsos positivos: Aceite findings conhecidos via regra glob ou baseline de fingerprint para que reescaneamentos revelem apenas problemas novos (docs)

Início rápido

Instalação

Aviso sobre software de código aberto: Este projeto irá 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 um ambiente virtual primeiro (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):```bash 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:```bash
uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

Da fonte:```bash

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, criando-o localmente a partir do [Dockerfile](https://github.com/nvidia/skillspector/blob/main/Dockerfile) incluído. A imagem é baseada na imagem oficial do Docker Python `3.12-slim-bookworm`.

**Criar a imagem:**```bash
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:```bash docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm

**Scan com análise de LLM** passando credenciais com um arquivo `.env` local:```bash
cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

Instalação

Requisitos

• Python 3.8+
• pip
• Acesso à rede para APIs de IA (opcional, dependendo do modo de operação)

Instalação via pip

pip install pyxam

Instalação a partir do código-fonte

git clone https://github.com/example/pyxam.git
cd pyxam
pip install -r requirements.txt

Verificar a instalação

pyxam --version

Início rápido

Análise básica

from pyxam import XamScanner

scanner = XamScanner()
results = scanner.scan("/path/to/target")
print(results.summary())

Interface de linha de comando

pyxam scan --target /path/to/target --output report.json

Modo de análise com IA

pyxam scan --target /path/to/target --ai-enabled --model gpt-4

Configuração

O PyXam pode ser configurado através de um arquivo de configuração ou variáveis de ambiente.

Arquivo de configuração

Crie um arquivo pyxam.yaml no diretório do seu projeto:

scanner:
  threads: 4
  timeout: 30
  verbose: false

ai:
  enabled: true
  provider: openai
  model: gpt-4
  api_key: ${OPENAI_API_KEY}

output:
  format: json
  path: ./reports

Variáveis de ambiente

Variável	Descrição	Padrão
PYXAM_CONFIG	Caminho para o arquivo de configuração	./pyxam.yaml
PYXAM_THREADS	Número de threads de análise	4
PYXAM_TIMEOUT	Tempo limite da análise em segundos	30
OPENAI_API_KEY	Chave da API OpenAI para recursos de IA	-
PYXAM_LOG_LEVEL	Nível de log (DEBUG, INFO, WARN, ERROR)	INFO

Uso

Comandos da CLI

pyxam scan

Executa uma análise no alvo especificado.

pyxam scan --target /path/to/target [options]

Opções:

• --target, -t: Caminho ou URL do alvo (obrigatório)
• --output, -o: Caminho do arquivo de saída
• --format, -f: Formato de saída (json, xml, csv, html)
• --ai-enabled: Ativar análise com IA
• --model: Modelo de IA a ser usado
• --threads: Número de threads
• --verbose, -v: Saída detalhada

pyxam report

Gera um relatório a partir de resultados de análise anteriores.

pyxam report --input results.json --format html --output report.html

pyxam config

Gerencia a configuração do PyXam.

pyxam config --init          # Criar arquivo de configuração padrão
pyxam config --show          # Exibir configuração atual
pyxam config --validate      # Validar arquivo de configuração

Uso como biblioteca

from pyxam import XamScanner, AIAnalyzer

# Inicializar o scanner
scanner = XamScanner(
    threads=4,
    timeout=30,
    verbose=True
)

# Executar a análise
results = scanner.scan("/path/to/target")