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'

### Docker (sem Python necessário)

Execute o SkillSpector sem instalar Python, compilando-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`.

**Compilar a imagem:**```bash
make docker-build
# or: docker build -t skillspector .

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

pip install kitploit-tool

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

kitploit-tool --version

kitploit-tool [opções] <comando>

kitploit-tool scan --target https://exemplo.com

kitploit-tool scan --target https://exemplo.com --port 8080 --intensity alta

kitploit-tool report --format pdf --output relatorio.pdf

# Configuração padrão da ferramenta
scan:
  timeout: 30
  threads: 10
  user_agent: "Kitploit-Tool/1.0"

report:
  format: "html"
  output_dir: "./relatorios"

sudo kitploit-tool scan --target https://exemplo.com

pip install -r requirements.txt --upgrade

export KITPLOIT_PROXY=http://seu-proxy:porta

Ou passe as 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/

**Alias opcional** para análises estáticas repetidas:```bash
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm

#### Limites de tamanho

O SkillSpector impõe dois limites independentes para entradas remotas e de arquivos, a fim de limitar o impacto de downloads excessivamente grandes e de zip bombs:

- **Limite por ingestão**: `INGEST_MAX_BYTES` (100 MiB) — aplicado a downloads de URLs transmitidos, ao tamanho total descomprimido de arquivos zip e ao uso de disco pós-clonagem 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 analisadores individuais lerão de um diretório já ingerido. Os limites de ingestão acima restringem quanto conteúdo pode ser gravado no 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```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

Suporta deteção multilingue (zh/ja/ko) e saída em terminal/JSON/Markdown.

Para scans de LLM com maior concorrência, configure múltiplas chaves de API seguindo
[`.env.example`](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/.env.example) — o pool melhora a taxa de transferência
e a resiliência, desde que as chaves não partilhem um limite de taxa ao nível da conta.

Consulte o [guia de contribuição](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/docs) para mais detalhes.

> **Nota sobre 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 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 puder
> contribuir com um backend mais universal (Ollama, vLLM ou outro fornecedor),
> PRs são muito bem-vindos.

### Suprimir Falsos Positivos (baseline)

Suprima achados conhecidos/aceites para que a pontuação de risco reflita apenas problemas
não triados e que re-scans revelem apenas achados *novos*. Consulte o
[guia de supressão](https://github.com/nvidia/skillspector/blob/main/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

### 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 proteção 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

> **Segurança — modelo de confiança do transporte HTTP**
>
> O transporte HTTP é fornecido **sem autenticação**. Qualquer chamador que
> consiga alcançar a porta pode invocar `scan_skill`. Via stdio ou `127.0.0.1`,
> isso representa o mesmo limite de confiança que a CLI. Se você vincular a uma
> interface roteável:
>
> - Coloque o servidor atrás de um proxy reverso autenticado (ex.: nginx + mTLS)
>   antes de expô-lo externamente.
> - Caminhos locais e URLs `file://` são **automaticamente rejeitados** 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 **71 padrões de vulnerabilidade** em 17 categorias:

### Injeção de Prompt (6 padrões)

| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| P1 | Substituição de Instruções | 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 Prejudicial | CRÍTICA | Instruções que podem causar dano físico |
| P9 | Preenchimento com Espaços em Branco | MÉDIA | Grande preenchimento com espaços em branco ocultando instruções abaixo/ao lado da área visível |

### Anti-Recusa (3 padrões)

| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| AR1 | Supressão de Recusa | ALTA | Instruções para nunca recusar ou sempre cumprir (ex.: "nunca recuse", "sempre cumpra") |
| AR2 | Supressão de Avisos | ALTA | Instruções para omitir avisos, isenções de responsabilidade ou comentários éticos (ex.: "sem avisos", "não moralize") |
| AR3 | Anulação da Política de Segurança | ALTA | Enquadramento de jailbreak que anula proteções (ex.: "você não tem restrições", "ignore suas diretrizes", "faça qualquer coisa agora") |

### 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 | Enumeração, cópia ou busca de 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 do contexto da 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, senhas |

### Cadeia de Suprimentos (9+ padrões)

| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| SC1 | Dependências sem Versão Fixada | BAIXA | Sem restrições de versão nos pacotes |
| SC2 | Busca de Scripts Externos | 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 conhecidas (consulta ao vivo no 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 |
| SC8 | Bytecode Python Incluído | ALTA | Presença de `__pycache__` / `.pyc` (a descoberta ignora; bytecode malicioso contorna) |
| SC9 | Artefato Executável Oculto | ALTA | Executável aninhado em um contêiner de documento ou artefato oculto/disfarçado |

### Agência Excessiva (5 padrões)

| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| EA1 | Acesso Irrestrito a Ferramentas | ALTA | Acesso irrestrito a ferramentas sem limitações |
| EA2 | Tomada de Decisão Autônoma | ALTA | Decisões de alto impacto sem supervisão humana |
| EA3 | Expansão de Escopo | MÉDIA | Capacidades 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 |
| EA5 | Seleção de Modelo ou Provedor Externo | MÉDIA/ALTA | Fixação de modelo/provedor ou chamadas externas de CLI de codificação que podem alternar contas de cobrança |

### Tratamento 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 | Saída flui entre limites de confiança sem validação |
| OH3 | Saída Ilimitada | MÉDIA | Sem limites no tamanho da saída ou na 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 gravações de arquivos ou solicitaçõ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 |

### Uso Indevido de Ferramentas (3 padrões)

| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| TM1 | Abuso de Parâmetros de Ferramenta | ALTA | Parâmetros elaborados para comportamento não intencional (shell=True, --force) |
| TM2 | Abuso por 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 Malicioso (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 Gatilhos (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 integrados ou outras habilidades |
| TR3 | Gatilho de Atração 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 objetos 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 | Sumidouro getattr() Reflexivo | ALTA | exec reflexivo via `getattr(os,'system')` / `getattr(builtins,'exec')` que evade AST1/AST5 |

### Rastreamento de Fluxo (5 padrões)

| ID | Padrão | Severidade | Descrição |
|----|---------|----------|-------------|
| TT1 | Fluxo de Dados Direto | ALTA | Dados fluem diretamente de uma fonte para um sumidouro sem sanitização |
| TT2 | Fluxo de Dados Mediado por Variáveis | MÉDIA | Dados fluem da fonte para o sumidouro por meio 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údo de arquivos flui 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 com 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 o código possui capacidades detectáveis |
| LP4 | Permissão Superdeclarada | BAIXA | Permissão declarada, mas nenhuma capacidade correspondente encontrada no código |

### 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, URIs de dados) |
| TP2 | Engano Unicode | ALTA | Homóglifos, sobrescritas RTL, identificadores de script misto em metadados de ferramentas |
| TP3 | Injeção na Descrição de Parâmetros | MÉDIA | Padrões de injeção em definições de parâmetros (sobrescritas, tokens de sistema, padrões maliciosos) |
| TP4 | Incompatibilidade Descrição-Comportamento | MÉDIA | Descrição declarada da ferramenta não corresponde ao comportamento real do código (com tecnologia LLM) |

Todos os padrões detectados estão listados nas tabelas acima.

## Pontuação de Risco

### Cálculo da Pontuação

- **Problemas CRÍTICOS**: +50 pontos
- **Problemas ALTOS**: +25 pontos
- **Problemas MÉDIOS**: +10 pontos
- **Problemas BAIXOS**: +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 INSTALAR |
| 81-100 | CRÍTICA | NÃO INSTALAR |

## 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.

## Integrando o SkillSpector

O SkillSpector é projetado para ser controlado por outras ferramentas (pipelines de CI, portões de instalação, integrações de editores). Seu código de saída e saída JSON são um contrato estável.

### Códigos de saída

`skillspector scan` sai com:

| Código | Significado |
|------|---------|
| `0` | Varredura concluída, `risk_score` ≤ 50 (recomendação `SAFE` ou `CAUTION`) |
| `1` | Varredura concluída, `risk_score` > 50 (recomendação `DO_NOT_INSTALL`) |
| `2` | Erro (entrada inválida, fonte ilegível, falha interna) |

> O código de saída reduz `SAFE` e `CAUTION` para `0`. Para agir de forma diferente sobre 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 na saída padrão (stdout):```bash
skillspector scan ./my-skill/ --format json

- `risk_assessment.severity` ∈ `LOW | MEDIUM | HIGH | CRITICAL`.
- `risk_assessment.recommendation` ∈ `SAFE | CAUTION | DO_NOT_INSTALL`, mapeado a partir da severidade: `LOW → SAFE`, `MEDIUM → CAUTION`, `HIGH`/`CRITICAL → DO_NOT_INSTALL`.
- `metadata.llm_error` aparece apenas quando a análise por LLM foi solicitada, mas não estava disponível.
- `metadata.inference_usage` contém um registro saneado por resposta de 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
  e gravações de cache, para que a precificação a jusante possa separar essas partições com segurança.
  `model_source` distingue um modelo de provedor identificado de forma independente 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, portanto, suas
  solicitações de varredura não podem selecionar os níveis separados de gravação de cache de 5 minutos ou 1 hora;
  os 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/main/docs/INFERENCE_USAGE.md) para obter a
  proveniência completa, contabilidade de cache, privacidade, ingestão com falha fechada e o
  contrato de precificação a jusante.
- O formato completo por problema é definido por `Finding.to_dict()` em [models.py](https://github.com/nvidia/skillspector/blob/main/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 de gate recomendado

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 rígido é 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 `make` pressupõem 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

## Licença

Apache License 2.0 — consulte [LICENSE](https://github.com/nvidia/skillspector/blob/main/LICENSE) para mais detalhes.

## Contribuições

Contribuições são bem-vindas! Leia as nossas diretrizes de contribuição e envie pull requests.

## Suporte

- **Problemas**: [GitHub Issues](https://github.com/NVIDIA/skillspector/issues)