Scanner de segurança para skills de agentes de IA. Detecta vulnerabilidades, padrões maliciosos, riscos de segurança, injeção de prompt, exfiltração de dados e riscos de supply-chain em skills do Claude Code, Codex e MCP antes de instalá-las.
Scanner de segurança para habilidades de agentes de IA. Detecte vulnerabilidades, padrões maliciosos e riscos de segurança antes de instalar habilidades de agentes.
Habilidades 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. Pesquisas mostram que 26,1% das habilidades contêm vulnerabilidades e 5,2% apresentam provável intenção maliciosa.
SkillSpector ajuda você a responder: "Esta habilidade é segura para instalar?"
SkillSpector faz parte do pipeline NVIDIA Verified Skills, que verifica, avalia e assina habilidades de agentes antes da publicação. As habilidades aprovadas são publicadas no catálogo de habilidades da NVIDIA.
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 um ambiente virtual primeiro (todos os alvos make pressupõem que o venv esteja 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
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'
I don't see any translatable content in this chunk — the source text after "From source:" is empty. There's nothing for me to translate.```bash
git clone https://github.com/NVIDIA/skillspector.git cd skillspector
uv venv .venv && source .venv/bin/activate
make install
make install-dev
### Docker (não requer Python)
Execute o SkillSpector sem instalar Python, construindo-o localmente a partir do [Dockerfile](https://github.com/nvidia/skillspector/blob/HEAD/Dockerfile) incluído. A imagem é baseada na imagem oficial Python `3.12-slim-bookworm` do Docker.
**Construa a imagem:**```bash
make docker-build
# or: docker build -t skillspector .
Escanear 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
**Escanear 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
Mas vamos começar com algumas definições antes de implantar sua ferramenta:
Ou passe credenciais diretamente do seu ambiente de shell:```bash
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 escrevendo no diretório montado:```bash
docker run --rm
-v "$PWD:/scan"
skillspector scan ./my-skill/ --no-llm --format json --output report.json
**Alias opcional** para varreduras estáticas repetidas:```bash
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm
skillspector scan ./my-skill/
skillspector scan ./SKILL.md
skillspector scan https://github.com/user/my-skill
skillspector scan ./my-skill.zip
#### Limites de tamanho
O SkillSpector impõe dois limites independentes para entradas remotas e de arquivos para limitar o impacto de downloads excessivamente grandes e bombas zip:
- **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 limita o que analisadores individuais lerão de um diretório já ingerido. Os limites de ingestão acima limitam quanto conteúdo pode chegar ao disco em primeiro lugar. Uma violação de qualquer um dos limites de ingestão falha em modo fechado com um `IngestLimitExceededError`.
### Formatos de Saída```bash
# 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
Digitalize diretórios inteiros de habilidades em paralelo a partir de contrib/batch_scan/:```bash
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
Suporta detecção multilíngue (zh/ja/ko) e saída em terminal/JSON/Markdown.
Para varreduras de LLM com maior concorrência, configure múltiplas chaves de API seguindo
[`.env.example`](https://github.com/nvidia/skillspector/blob/HEAD/contrib/batch_scan/.env.example) — o pool melhora a vazão
e a resiliência, desde que as chaves não compartilhem um limite de taxa em nível de conta.
Consulte o [guia de contrib](https://github.com/nvidia/skillspector/blob/HEAD/contrib/batch_scan/docs/) para detalhes.
> **Nota sobre o suporte a LLM:** A configuração padrão tem como alvo o DeepSeek como a
> opção pública mais barata. O DeepSeek-Chat está
> [previsto para ser descontinuado](https://api-docs.deepseek.com/), e o contribuidor
> não possui hardware para testar com modelos locais. O scanner em lote foi
> originalmente testado com endpoints compatíveis com OpenAI — a falta de suporte
> a saída estruturada do DeepSeek exigiu correções manuais de parsing de JSON. Se você puder
> contribuir com um backend mais universal (Ollama, vLLM ou outro provedor),
> PRs são muito bem-vindos.
### Suprimindo Falsos Positivos (baseline)
Suprima descobertas conhecidas/aceitas para que a pontuação de risco reflita apenas
problemas não triados e re-varreduras evidenciem apenas descobertas *novas*. Consulte o
[guia de supressão](https://github.com/nvidia/skillspector/blob/HEAD/docs/SUPPRESSION.md) para a referência completa.```bash
# Accept all current findings into a baseline (run once), then commit it.
skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml
# Scan against the baseline — only NEW findings are reported and scored.
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml
# Review what was suppressed (still excluded from the score).
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed
A baseline também pode usar regras de glob tolerantes a drift (por id de regra, caminho de arquivo ou mensagem) — consulte .skillspector-baseline.example.yaml. Baselines de impressão digital exatas são vinculadas a evidências: alterar o código-fonte escaneado ou a versão do SkillSpector mantém o achado ativo até que ele seja revisado novamente. Quando uma baseline selecionada ou a saída de baseline é armazenada dentro do diretório da skill, o SkillSpector exclui esse arquivo exato da análise de conteúdo para que seu texto de supressão não possa criar achados ou entrar em impressões digitais regeneradas; arquivos irmãos permanecem no escopo normal de varredura.
Para obter os melhores resultados, configure um endpoint LLM compatível com OpenAI para análise semântica. Escolha um provedor com SKILLSPECTOR_PROVIDER; provedores hospedados incluem modelos padrão integrados, enquanto provedores CLI usam como fallback o modelo padrão do runtime local, a menos que SKILLSPECTOR_MODEL seja definido. O SkillSpector também funciona com servidores locais compatíveis com OpenAI (Ollama, vLLM, llama.cpp) e gateways de inferência gerenciados.
export SKILLSPECTOR_PROVIDER=openai export OPENAI_API_KEY=sk-... skillspector scan ./my-skill/
export SKILLSPECTOR_PROVIDER=anthropic export ANTHROPIC_API_KEY=sk-ant-... skillspector scan ./my-skill/
export SKILLSPECTOR_PROVIDER=anthropic_proxy export ANTHROPIC_PROXY_ENDPOINT_URL=https://my-gateway.example.com/models/claude-sonnet-4-6:streamRawPredict export ANTHROPIC_PROXY_API_KEY=your-bearer-token export SKILLSPECTOR_MODEL=claude-sonnet-4-6 skillspector scan ./my-skill/
export SKILLSPECTOR_PROVIDER=bedrock
export AWS_REGION=us-west-2 # default if unset
skillspector scan ./my-skill/
export SKILLSPECTOR_PROVIDER=nv_build export NVIDIA_INFERENCE_KEY=nvapi-... skillspector scan ./my-skill/
claude auth login sessionexport SKILLSPECTOR_PROVIDER=claude_cli
skillspector scan ./my-skill/
codex login sessionexport SKILLSPECTOR_PROVIDER=codex_cli skillspector scan ./my-skill/
export SKILLSPECTOR_PROVIDER=openai export OPENAI_API_KEY=ollama export OPENAI_BASE_URL=http://localhost:11434/v1 export SKILLSPECTOR_MODEL=llama3.1:8b skillspector scan ./my-skill/
export SKILLSPECTOR_MODEL=gpt-5.2 skillspector scan ./my-skill/
skillspector scan ./my-skill/ --no-llm
### Servidor MCP
Execute o SkillSpector como um servidor [Model Context Protocol](https://modelcontextprotocol.io)
para que qualquer agente compatível com MCP (Claude Code, Codex CLI, Gemini CLI) ou runtime
remoto possa chamar a varredura como uma ferramenta e **condicionar instalações de skills/MCP ao
resultado** — transformando o SkillSpector em uma salvaguarda em tempo de execução em vez de uma
etapa de auditoria fora do fluxo.
`skillspector mcp` requer `skillspector[mcp]`.```bash
# Install, or reinstall if you already used the CLI-only path
uv tool install --force 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'
# FastMCP stdio transport for local CLI agents
skillspector mcp
# streamable HTTP/SSE transport for remote / A2A callers
skillspector mcp --transport http --host 127.0.0.1 --port 8000
O transporte stdio é o caminho FastMCP atual para agentes CLI locais, e o travamento de inicialização relatado na issue #199 ainda se aplica ali.
O servidor expõe uma única ferramenta:
scan_skill(target, use_llm=true, output_format="json") — verifica uma URL
Git, URL de arquivo, arquivo .zip, .md ou diretório e retorna um veredito
estruturado: risk_score (0-100), severity, recommendation,
safe_to_install e findings. Também informa llm_used / scan_mode
para que uma pontuação baixa de uma verificação apenas estática nunca seja
confundida com uma verificação completa limpa.Registre-a com o Claude Code via:```bash claude mcp add skillspector -- skillspector mcp
> **Segurança — modelo de confiança do transporte HTTP**
>
> O transporte HTTP é fornecido **sem autenticação**. Qualquer chamador que
> alcance a porta pode invocar `scan_skill`. Via stdio ou `127.0.0.1`, essa é
> a mesma fronteira de confiança que a CLI. Se você vincular a uma interface roteável:
>
> - Coloque o servidor atrás de um proxy reverso com autenticação (ex.: nginx + mTLS)
> antes de expô-lo externamente.
> - Caminhos locais e URLs `file://` são **rejeitados automaticamente** via HTTP para
> impedir que chamadores não autenticados leiam arquivos arbitrários do host. Apenas
> URLs remotas de Git e `.zip` são aceitas.
## Padrões de Vulnerabilidade
O SkillSpector detecta **68 padrões de vulnerabilidade** em 17 categorias:
### Injeção de Prompt (5 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| P1 | Sobrescrita de Instrução | ALTA | Comandos para ignorar restrições de segurança |
| P2 | Instruções Ocultas | ALTA | Diretivas maliciosas em comentários/texto invisível |
| P3 | Comandos de Exfiltração | ALTA | Instruções para transmitir contexto externamente |
| P4 | Manipulação de Comportamento | MÉDIA | Instruções sutis que alteram decisões do agente |
| P5 | Conteúdo Nocivo | CRÍTICA | Instruções que podem causar dano físico |
### Anti-Recusa (3 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| AR1 | Supressão de Recusa | ALTA | Instruções para nunca recusar ou sempre concordar (ex.: "never refuse", "always comply") |
| AR2 | Supressão de Avisos | ALTA | Instruções para omitir avisos, isenções de responsabilidade ou comentários éticos (ex.: "no disclaimers", "do not moralize") |
| AR3 | Anulação de Política de Segurança | ALTA | Enquadramento de jailbreak que anula salvaguardas (ex.: "you have no restrictions", "ignore your guidelines", "do anything now") |
### Exfiltração de Dados (4 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| E1 | Transmissão Externa | MÉDIA | Envio de dados para URLs externas |
| E2 | Coleta de Variáveis de Ambiente | ALTA | Enumerar, copiar ou pesquisar dados de ambiente para coletar segredos |
| E3 | Enumeração do Sistema de Arquivos | MÉDIA | Varredura de diretórios em busca de arquivos sensíveis |
| E4 | Vazamento de Contexto | ALTA | Transmissão de contexto de conversa externamente |
### Escalação de Privilégios (3 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| PE1 | Permissões Excessivas | BAIXA | Solicitação de acesso além da funcionalidade declarada |
| PE2 | Execução Sudo/Root | MÉDIA | Invocação de privilégios elevados do sistema |
| PE3 | Acesso a Credenciais | ALTA | Leitura de chaves SSH, tokens e senhas |
### Cadeia de Suprimentos (6 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| SC1 | Dependências Não Fixadas | BAIXA | Sem restrições de versão em pacotes |
| SC2 | Busca de Script Externo | ALTA | curl \| bash e execução remota de código |
| SC3 | Código Ofuscado | ALTA | Execução codificada em Base64/hex |
| SC4 | Dependências Vulneráveis Conhecidas | ALTA | Dependências com CVEs conhecidos (consulta ao vivo ao OSV.dev) |
| SC5 | Dependências Abandonadas | MÉDIA | Pacotes sem manutenção e sem atualizações de segurança |
| SC6 | Typosquatting | ALTA | Nomes de pacotes semelhantes a pacotes populares |
### Agência Excessiva (4 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| EA1 | Acesso Irrestrito a Ferramentas | ALTA | Acesso ilimitado a ferramentas sem restrições |
| EA2 | Tomada de Decisão Autônoma | ALTA | Decisões de alto impacto sem supervisão humana (human-in-the-loop) |
| EA3 | Expansão de Escopo | MÉDIA | Recursos que vão além do propósito declarado |
| EA4 | Acesso Ilimitado a Recursos | MÉDIA | Sem limites de taxa ou cotas no consumo de recursos |
### Manipulação de Saída (3 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| OH1 | Injeção de Saída Não Validada | ALTA | Saída do modelo usada sem sanitização |
| OH2 | Saída Entre Contextos | MÉDIA | A saída flui entre fronteiras de confiança sem validação |
| OH3 | Saída Ilimitada | MÉDIA | Sem limites no tamanho da saída ou taxa de geração |
### Vazamento do Prompt do Sistema (3 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| P6 | Vazamento Direto | ALTA | Instruções que expõem prompts do sistema ou regras internas |
| P7 | Extração Indireta | MÉDIA | Extração via reformulação, tradução ou canais laterais |
| P8 | Exfiltração Baseada em Ferramentas | ALTA | Prompts do sistema exfiltrados via escrita de arquivos ou requisições de rede |
### Envenenamento de Memória (3 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| MP1 | Injeção Persistente de Contexto | ALTA | Conteúdo projetado para persistir entre interações |
| MP2 | Preenchimento da Janela de Contexto | MÉDIA | Conteúdo de preenchimento que desloca restrições de segurança |
| MP3 | Manipulação de Memória | ALTA | Adulteração da memória do agente ou do estado armazenado |
### Mau Uso de Ferramentas (3 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| TM1 | Abuso de Parâmetros de Ferramenta | ALTA | Parâmetros criados para comportamento não intencional (shell=True, --force) |
| TM2 | Abuso de Encadeamento | ALTA | Cadeias de ferramentas que contornam verificações de segurança individuais |
| TM3 | Padrões Inseguros | MÉDIA | Padrões excessivamente permissivos (TLS desabilitado, sem autenticação) |
### Agente Rogue (2 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| RA1 | Automodificação | CRÍTICA | Modificação do próprio código ou configuração em tempo de execução |
| RA2 | Persistência de Sessão | ALTA | Persistência não autorizada via cron jobs ou scripts de inicialização |
### Abuso de Gatilho (3 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| TR1 | Gatilho Excessivamente Amplo | MÉDIA | Padrões de gatilho que correspondem a palavras comuns |
| TR2 | Gatilho de Comando Sombra | ALTA | Gatilhos que fazem sombra a comandos internos ou outras habilidades |
| TR3 | Gatilho de Isca por Palavras-Chave | MÉDIA | Gatilhos genéricos projetados para maximizar a ativação |
### AST Comportamental (9 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| AST1 | Chamada exec() | CRÍTICA | exec() direto permitindo execução arbitrária de código |
| AST2 | Chamada eval() | ALTA | eval() direto avaliando expressões arbitrárias |
| AST3 | Importação Dinâmica | ALTA | \_\_import\_\_() carregando módulos arbitrários em tempo de execução |
| AST4 | Chamada subprocess | ALTA | Execução de comandos externos via subprocess |
| AST5 | os.system / família exec | ALTA | Comandos de shell via módulo os |
| AST6 | Chamada compile() | MÉDIA | Criação de objeto de código a partir de strings |
| AST7 | getattr() Dinâmico | MÉDIA | Acesso arbitrário a atributos com nomes não literais |
| AST8 | Cadeia de Execução Perigosa | CRÍTICA | exec/eval combinados com fonte dinâmica (rede, dados codificados) |
| AST9 | Sink getattr() Reflexivo | ALTA | exec reflexivo via `getattr(os,'system')` / `getattr(builtins,'exec')` que evade AST1/AST5 |
### Rastreamento de Taint (5 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| TT1 | Fluxo de Taint Direto | ALTA | Dados fluem diretamente de uma fonte para um sumidouro sem sanitização |
| TT2 | Fluxo de Taint Mediado por Variável | MÉDIA | Dados fluem da fonte para o sumidouro através de variáveis intermediárias |
| TT3 | Cadeia de Exfiltração de Credenciais | CRÍTICA | Credenciais (variáveis de ambiente, segredos) fluem para sumidouros de saída de rede |
| TT4 | Leitura de Arquivo para Exfiltração de Rede | ALTA | Conteúdos de arquivos fluem para sumidouros de saída de rede |
| TT5 | Entrada Externa para Execução de Código | CRÍTICA | Entrada de rede ou do usuário flui para sumidouros exec/eval/subprocess |
### Assinaturas YARA (4 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| YR1 | Correspondência de Malware | CRÍTICA | Correspondência de regra YARA para assinaturas de malware conhecidas |
| YR2 | Correspondência de Webshell | CRÍTICA | Correspondência de regra YARA para padrões de webshell |
| YR3 | Correspondência de Criptominerador | ALTA | Correspondência de regra YARA para indicadores de mineração de criptomoedas |
| YR4 | Correspondência de Ferramenta de Hack / Exploit | ALTA | Correspondência de regra YARA para ferramentas de hack ou código de exploit |
### MCP Menor Privilégio (4 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| LP1 | Capacidade Subdeclarada | ALTA | Código usa capacidades não listadas nas permissões declaradas |
| LP2 | Permissão Curinga | MÉDIA | Lista de permissões contém curingas (\*, all, full, any) |
| LP3 | Declaração de Permissão Ausente | MÉDIA | Sem campo de permissões, mas com código com capacidades detectáveis |
| LP4 | Permissão Superdeclarada | BAIXA | Permissão declarada, mas nenhuma capacidade de código correspondente encontrada |
### Envenenamento de Ferramentas MCP (4 padrões)
| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| TP1 | Instruções Ocultas | ALTA | Diretivas ocultas em metadados (comentários HTML, caracteres de largura zero, base64, data URIs) |
| TP2 | Engano Unicode | ALTA | Homóglifos, overrides RTL, identificadores de script misto em metadados de ferramentas |
| TP3 | Injeção em Descrição de Parâmetro | MÉDIA | Padrões de injeção em definições de parâmetros (overrides, tokens de sistema, padrões maliciosos) |
| TP4 | Incompatibilidade entre Descrição e Comportamento | MÉDIA | A descrição declarada da ferramenta não corresponde ao comportamento real do código (com LLM) |
Todos os padrões detectados estão listados nas tabelas acima.
## Pontuação de Risco
### Cálculo de Pontuação
- **Problemas de severidade CRÍTICA**: +50 pontos
- **Problemas de severidade ALTA**: +25 pontos
- **Problemas de severidade MÉDIA**: +10 pontos
- **Problemas de severidade BAIXA**: +5 pontos
- **Scripts executáveis**: multiplicador de 1.3x
### Níveis de Severidade
| Pontuação | Severidade | Recomendação |
|-------|----------|----------------|
| 0-20 | BAIXA | SEGURO |
| 21-50 | MÉDIA | CUIDADO |
| 51-80 | ALTA | NÃO INSTALE |
| 81-100 | CRÍTICA | NÃO INSTALE |
## Exemplo de Saída
### Saída do Terminal```
SkillSpector Security Report v2.0.0
Skill: suspicious-skill
Source: ./suspicious-skill/
Scanned: 2026-01-29 10:30:00 UTC
Risk Assessment
Metric Value
Score 78/100
Severity HIGH
Recommendation DO NOT INSTALL
Components (3)
File Type Lines Executable
SKILL.md markdown 142 No
scripts/sync.py python 87 Yes
requirements.txt text 3 No
Issues (2)
HIGH: Env Variable Harvesting (E2)
Location: scripts/sync.py:23
Finding: for key, val in os.environ.items():...
Confidence: 94%
Explanation: This code collects environment variables containing
API keys and secrets, then sends them to an external server.
HIGH: External Transmission (E1)
Location: scripts/sync.py:45
Finding: requests.post("https://api.skill.io/env"...
Confidence: 89%
Explanation: Data is being sent to an external server. Combined
with env harvesting above, this indicates credential exfiltration.
Provedores CLI (
claude_cli,codex_cli): Nenhuma chave de API é necessária. A autenticação é gerenciada inteiramente pela sessão de login da própria CLI do agente (claude auth login/codex login). O SkillSpector nunca lê nem encaminha chaves de API quando esses provedores estão ativos. O subprocesso é executado em um sandbox endurecido: ferramentas desabilitadas, sem MCP, modo sandbox somente leitura (codex) e o conteúdo de habilidades não confiável é entregue apenas via stdin.
skillspector scan --help
Options: -f, --format [terminal|json|markdown|sarif] Output format [default: terminal] -o, --output PATH Output file path --no-llm Skip LLM analysis (static only) --yara-rules-dir PATH Extra YARA rules directory -b, --baseline PATH Suppress findings listed in a baseline --show-suppressed List baseline-suppressed findings -V, --verbose Show detailed progress --help Show this message and exit
skillspector baseline [-o FILE] [--no-llm] [--reason TEXT]
## Integrando o SkillSpector
O SkillSpector é construído para ser controlado por outras ferramentas (pipelines de CI, portões de instalação, integrações com editores). Seu código de saída e a saída JSON são um contrato estável.
### Códigos de saída
`skillspector scan` termina com:
| Código | Significado |
|------|---------|
| `0` | Scan concluído, `risk_score` ≤ 50 (recomendação `SAFE` ou `CAUTION`) |
| `1` | Scan concluído, `risk_score` > 50 (recomendação `DO_NOT_INSTALL`) |
| `2` | Erro (entrada inválida, fonte ilegível, falha interna) |
> O código de saída colapsa `SAFE` e `CAUTION` em `0`. Para agir de forma diferente em relação a eles (por exemplo, *avisar* em `CAUTION` mas *bloquear* em `DO_NOT_INSTALL`), leia o campo `recommendation` da saída JSON em vez de depender do código de saída.
### Saída legível por máquina
`--format json` produz um relatório JSON; sem `--output`/`-o`, ele é gravado no stdout:```bash
skillspector scan ./my-skill/ --format json
A forma de nível superior é (este exemplo mostra uma varredura completa com suporte de LLM; com --no-llm, metadata.llm_requested é false):```json
{
"skill": { "name": "...", "source": "...", "scanned_at": "<ISO 8601>" },
"risk_assessment": { "score": 0, "severity": "LOW", "recommendation": "SAFE" },
"components": [ { "path": "...", "type": "...", "lines": 0, "executable": false, "size_bytes": 0 } ],
"issues": [ { "id": "...", "category": "...", "severity": "...", "confidence": 0.0, "location": { "file": "...", "start_line": 0 } } ],
"metadata": {
"has_executable_scripts": false,
"skillspector_version": "...",
"llm_requested": true,
"llm_available": true,
"inference_usage": [
{
"node": "semantic_security_discovery",
"request_kind": "structured_output",
"provider": "nv_inference",
"model": "azure/anthropic/claude-opus-4-6",
"model_source": "provider_response",
"usage_source": "provider_response",
"prompt_tokens": 1000,
"completion_tokens": 100,
"cached_tokens": 400,
"cache_write_tokens": 50,
"total_tokens": 1100
}
]
}
}
- `risk_assessment.severity` ∈ `LOW | MEDIUM | HIGH | CRITICAL`.
- `risk_assessment.recommendation` ∈ `SAFE | CAUTION | DO_NOT_INSTALL`, mapeado da gravidade: `LOW → SAFE`, `MEDIUM → CAUTION`, `HIGH`/`CRITICAL → DO_NOT_INSTALL`.
- `metadata.llm_error` aparece apenas quando a análise do LLM foi solicitada, mas não estava disponível.
- `metadata.inference_usage` contém um registro sanitizado por resposta do LLM quando o
provedor expõe contadores de tokens. É uma lista vazia quando o uso não está disponível;
o SkillSpector nunca estima tokens ausentes. Os totais de prompt incluem leituras de cache
e gravações, para que a precificação downstream possa separar essas partições com segurança.
`model_source` distingue um modelo de provedor identificado independentemente do
modelo exato solicitado usado quando a identidade da resposta está ausente ou ambígua.
O SkillSpector atualmente não envia controles de cache de prompt da Anthropic, então suas
solicitações de verificação não podem selecionar os níveis separados de gravação de cache de
5 minutos ou 1 hora; campos de resposta específicos de TTL são normalizados defensivamente
no contador agregado de gravação de cache.
- Consulte [Telemetria de uso de inferência](https://github.com/nvidia/skillspector/blob/HEAD/docs/INFERENCE_USAGE.md) para o contrato
completo de proveniência, contabilidade de cache, privacidade, ingestão fail-closed
e precificação downstream.
- A estrutura completa por problema é definida por `Finding.to_dict()` em [models.py](https://github.com/nvidia/skillspector/blob/HEAD/src/skillspector/models.py); confie nos campos acima e trate quaisquer campos adicionais como melhor esforço.
Para ferramentas de CI/IDE, `--format sarif` emite SARIF 2.1.0.
### Mapeamento recomendado do gate
Ao usar o SkillSpector como um gate de instalação, mapeie a recomendação para uma ação:
| `recommendation` | Ação sugerida |
|------------------|------------------|
| `SAFE` | permitir |
| `CAUTION` | solicitar / avisar o usuário |
| `DO_NOT_INSTALL` | bloquear |
O SkillSpector calcula a faixa de pontuação e a recomendação; o quão rigoroso é o gate (por exemplo, se `CAUTION` bloqueia em CI) é uma decisão de política para a ferramenta integradora.
## Desenvolvimento
### Configuração
Todos os alvos do `make` assumem que um ambiente virtual já foi criado e ativado. O Makefile usa **uv** se disponível, caso contrário **pip**.```bash
# Clone, create venv, activate, install dev dependencies
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector
uv venv .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate
make install-dev
# Run tests
make test
# Run tests with coverage
make test-cov
# Run linting
make lint
# Format code
make format
O SkillSpector usa um pipeline de detecção em dois estágios:
Uma assinatura válida de OpenSSF Model Signing de nível raiz (skill.oms.sig) é mantida no
inventário de componentes como tipo oms_signature, mas excluída da análise estática e de conteúdo LLM.
Os bundles OMS necessariamente contêm campos longos de payload, assinatura e certificado codificados em base64;
verificações genéricas de código ofuscado podem, de outra forma, classificar erroneamente esses campos como conteúdo executável oculto.
O reconhecedor verifica a estrutura mínima de OMS DSSE/in-toto; ele não verifica a assinatura,
a cadeia de certificados, a entrada do log de transparência ou a identidade do signatário. Arquivos de assinatura inválidos
ou não reconhecidos são examinados normalmente.
O prompt do LLM inclui proteções anti-jailbreak para impedir que skills maliciosas manipulem a análise.
O SC4 usa a API do OSV.dev para verificar dependências em relação ao banco de dados completo de Vulnerabilidades de Código Aberto — cobrindo dezenas de milhares de avisos em PyPI e npm.
A ferramenta requer acesso HTTPS de saída a api.osv.dev para dados de vulnerabilidades em tempo real. Quando isso não está disponível, os achados se limitam à lista de fallback estática.
O SkillSpector é defesa em profundidade, não um sandbox. Saiba o que ele faz e o que não faz antes de confiar nele:
SKILLSPECTOR_PROVIDER. Arquivos de assinatura OMS reconhecidos são excluídos. Use --no-llm para manter os conteúdos locais (somente análise estática).--no-llm. Ele envia coordenadas de dependências (não conteúdos de arquivos), não exige chave de API e recorre a uma lista embutida quando o OSV.dev está inacessível.api.osv.dev, o SC4 usa uma pequena lista de fallback estáticaBaseado na pesquisa de "Agent Skills in the Wild: An Empirical Study of Security Vulnerabilities at Scale" (Liu et al., 2026):
from skillspector import graph
result = graph.invoke({ "input_path": "/path/to/skill", "output_format": "json", # terminal, json, markdown, or sarif "use_llm": True, # False for static-only analysis })
print(f"Risk Score: {result['risk_score']}/100") print(f"Severity: {result['risk_severity']}") print(f"Recommendation: {result['risk_recommendation']}")
for finding in result["filtered_findings"]: print(f"[{finding['severity']}] {finding['rule_id']}: {finding['message']}")
## Licença
Apache License 2.0 - veja [LICENSE](https://github.com/nvidia/skillspector/blob/HEAD/LICENSE) para detalhes.
## Contribuindo
Contribuições são bem-vindas! Por favor, leia nossas diretrizes de contribuição e envie pull requests.
## Suporte
- **Issues**: [GitHub Issues](https://github.com/NVIDIA/skillspector/issues)
Provider (SKILLSPECTOR_PROVIDER) | Credential env var | Endpoint | Default model |
|---|
openai | OPENAI_API_KEY (+ OPENAI_BASE_URL opcional) | api.openai.com (ou qualquer URL compatível com OpenAI) | gpt-5.4 |
anthropic | ANTHROPIC_API_KEY | api.anthropic.com | claude-opus-4-6 |
anthropic_proxy | ANTHROPIC_PROXY_API_KEY + ANTHROPIC_PROXY_ENDPOINT_URL | Qualquer proxy raw-predict estilo Vertex | claude-sonnet-4-6 |
bedrock | AWS_PROFILE (opcional) + AWS_REGION — SigV4 via boto3 | AWS Bedrock Runtime | us.anthropic.claude-sonnet-4-6-20250915-v1:0 |
nv_build | NVIDIA_INFERENCE_KEY | build.nvidia.com | deepseek-ai/deepseek-v4-flash |
claude_cli | (nenhum — usa autenticação CLI local) | binário claude local | fallback do runtime Claude local, ou SKILLSPECTOR_MODEL |
codex_cli | (nenhum — usa autenticação CLI local) | binário codex local | fallback do runtime Codex local, ou SKILLSPECTOR_MODEL |
| Variável | Descrição | Obrigatório |
|---|
SKILLSPECTOR_PROVIDER | Provedor LLM ativo: openai, anthropic, anthropic_proxy, bedrock, nv_build, claude_cli, codex_cli ou gemini_cli. Provedores hospedados usam os padrões do model_registry.yaml incluído; claude_cli e codex_cli recorrem ao modelo padrão do runtime da CLI local, a menos que SKILLSPECTOR_MODEL esteja definido. O padrão é nv_build. | Opcional |
NVIDIA_INFERENCE_KEY | Credencial para o provedor nv_build (build.nvidia.com). | Obrigatória para análise LLM quando SKILLSPECTOR_PROVIDER=nv_build |
OPENAI_API_KEY | Credencial para o provedor OpenAI (SKILLSPECTOR_PROVIDER=openai). Também serve como fallback de nível 2 no fluxo de credenciais quando o provedor ativo não retorna credenciais. | Obrigatória para análise LLM quando SKILLSPECTOR_PROVIDER=openai |
OPENAI_BASE_URL | Substitui o endpoint da OpenAI (ex.: apontar para Ollama). | Opcional |
SKILLSPECTOR_REASONING_EFFORT | Configuração opcional de esforço de raciocínio, dependente do provedor e do modelo. Valores não vazios são aparados e repassados sem alteração; não definido ou vazio preserva o comportamento padrão do provedor. | Opcional |
ANTHROPIC_API_KEY | Credencial para o provedor Anthropic (SKILLSPECTOR_PROVIDER=anthropic). | Obrigatória para análise LLM quando SKILLSPECTOR_PROVIDER=anthropic |
ANTHROPIC_BASE_URL | Substitui o endpoint nativo da Anthropic (padrão: https://api.anthropic.com). | Opcional |
ANTHROPIC_PROXY_ENDPOINT_URL | URL completa do endpoint para o provedor proxy Anthropic (raw-predict estilo Vertex). | Obrigatória quando SKILLSPECTOR_PROVIDER=anthropic_proxy |
ANTHROPIC_PROXY_API_KEY | Token Bearer para o provedor proxy Anthropic. | Obrigatória quando SKILLSPECTOR_PROVIDER=anthropic_proxy |
ANTHROPIC_PROXY_API_VERSION | Valor anthropic_version enviado no corpo da requisição (padrão: vertex-2023-10-16). | Opcional |
AWS_PROFILE | Perfil AWS nomeado para o provedor Bedrock — autentica via SigV4 por meio do boto3. Quando não definido, a cadeia de credenciais padrão do boto3 (variáveis de ambiente, metadados de instância, SSO etc.) é resolvida. | Opcional (usado quando SKILLSPECTOR_PROVIDER=bedrock) |
AWS_REGION | Região AWS para o endpoint do Bedrock Runtime. O padrão é us-west-2. | Opcional (usado quando SKILLSPECTOR_PROVIDER=bedrock) |
SKILLSPECTOR_MODEL | Substitui o modelo do provedor ativo. Para provedores hospedados, substitui o padrão incluído da tabela de Análise LLM. Para claude_cli e codex_cli, é encaminhado como --model em vez de usar o fallback do runtime da CLI local. | Opcional |
SKILLSPECTOR_MODEL_REGISTRY | Substitui o registro YAML por provedor incluído (src/skillspector/providers/<provider>/model_registry.yaml) por um caminho personalizado. | Opcional |
SKILLSPECTOR_LOG_LEVEL | Nível de log: DEBUG, INFO, WARNING, ERROR (padrão: WARNING). | Opcional |