Skill Scanner

Um scanner de segurança de melhor esforço para Skills de Agentes de IA que detecta injeção de prompt, exfiltração de dados e padrões de código malicioso. Combina detecção baseada em padrões (YAML + YARA), LLM-como-juiz e análise comportamental de fluxo de dados para maximizar a cobertura de detecção de ameaças prováveis, minimizando falsos positivos.

Importante: Este scanner fornece detecção de melhor esforço, não cobertura abrangente ou completa. Uma varredura que não retorna achados não garante que uma skill esteja livre de todas as ameaças. Consulte Escopo e Limitações abaixo.

Suporta formatos OpenAI Codex Skills e Cursor Agent Skills seguindo a especificação Agent Skills. Com --lenient, também varre formatos não padronizados, como .claude/commands/*.md do Claude Code e repositórios de skills em markdown simples.

Destaques

• Detecção Multi-Engine - Análise estática, fluxo de dados comportamental, análise semântica por LLM e varredura baseada em nuvem para cobertura em camadas de melhor esforço
• Filtragem de Falsos Positivos - Meta-analisador reduz significativamente o ruído preservando a capacidade de detecção
• Pronto para CI/CD - Saída SARIF para GitHub Code Scanning, workflow reutilizável de GitHub Actions, códigos de saída para falhas de build
• Hook de Pre-commit - Integração com o framework padrão pre-commit para varrer skills antes de cada commit
• Extensível - Arquitetura de plugins para analisadores personalizados

Junte-se ao Discord da Cisco AI para discutir, compartilhar feedback ou conectar-se com a equipe.

Escopo e Limitações

O Skill Scanner é uma ferramenta de detecção. Ele identifica padrões de risco conhecidos e prováveis, mas não certifica segurança.

Principais limitações:

• Sem achados ≠ sem risco. Uma varredura que retorna "Sem achados" indica que nenhum padrão de ameaça conhecido foi detectado. Isso não garante que uma skill seja segura, benigna ou livre de vulnerabilidades.
• A cobertura é inerentemente incompleta. O scanner combina detecção baseada em assinaturas, análise semântica por LLM, análise comportamental de fluxo de dados, serviços de nuvem opcionais e pacotes de regras configuráveis. Embora essa abordagem melhore a cobertura, nenhuma ferramenta automatizada pode detectar todas as técnicas, especialmente ataques novos ou de dia zero.
• Falsos positivos e falsos negativos podem ocorrer. Modos de consenso e meta-análise reduzem o ruído, mas nenhuma configuração elimina todas as classificações incorretas. Ajuste a política de varredura à sua tolerância a risco.
• A revisão humana continua essencial. A varredura automatizada é um componente de uma estratégia de defesa em profundidade. Implantações de alto risco ou produção devem combinar os resultados do scanner com revisão manual de código e/ou modelagem de ameaças.

Documentação

Instalação

Pré-requisitos: Python 3.10+ e uv (recomendado) ou pip

# Usando uv (recomendado)
uv pip install cisco-ai-skill-scanner

# Usando pip
pip install cisco-ai-skill-scanner

# Suporte a AWS Bedrock
pip install cisco-ai-skill-scanner[bedrock]

# Suporte a Google AI Studio / Gemini
pip install cisco-ai-skill-scanner[google]

# Suporte a Google Vertex AI
pip install cisco-ai-skill-scanner[vertex]

# Suporte a Azure OpenAI
pip install cisco-ai-skill-scanner[azure]

# Todos os provedores de nuvem
pip install cisco-ai-skill-scanner[all]

Início Rápido

Configuração de Ambiente (Opcional)

# Para analisador LLM e Meta-analisador
export SKILL_SCANNER_LLM_API_KEY="your_api_key"
export SKILL_SCANNER_LLM_MODEL="claude-3-5-sonnet-20241022"
# Opcional: disabled, minimal, low, medium, high, xhigh, ou max
export SKILL_SCANNER_LLM_REASONING_EFFORT="low"

# Para varredura binária VirusTotal
export VIRUSTOTAL_API_KEY="your_virustotal_api_key"

# Para Cisco AI Defense
export AI_DEFENSE_API_KEY="your_aidefense_api_key"

Assistente Interativo

Não sabe quais flags usar? Execute skill-scanner sem argumentos para iniciar o assistente interativo:

skill-scanner

O assistente orienta você na seleção de alvo de varredura, analisadores, política e formato de saída, e então mostra o comando montado antes de executá-lo. Ótimo para aprender a CLI.

Uso da CLI

# Varre uma única skill (analisadores principais: estático + bytecode + pipeline)
skill-scanner scan /path/to/skill

# Varre com analisador comportamental (análise de fluxo de dados)
skill-scanner scan /path/to/skill --use-behavioral

# Varre com todos os engines
skill-scanner scan /path/to/skill --use-behavioral --use-llm --use-aidefense

# Varre com meta-analisador para filtragem de falsos positivos
skill-scanner scan /path/to/skill --use-llm --enable-meta

# Varre com analisador de gatilho para verificações de descrição vaga
skill-scanner scan /path/to/skill --use-trigger

# Executa o analisador LLM várias vezes e mantém achados com acordo majoritário
skill-scanner scan /path/to/skill --use-llm --llm-consensus-runs 3

# Varre múltiplas skills recursivamente
skill-scanner scan-all /path/to/skills --recursive --use-behavioral

# Varre múltiplas skills com detecção de sobreposição entre skills
skill-scanner scan-all /path/to/skills --recursive --check-overlap

# Varre um repositório GitHub (atalho owner/repo ou URL completa)
skill-scanner scan-repo owner/repo
skill-scanner scan-repo https://github.com/owner/repo --use-llm

# Modo leniente: tolera skills malformadas em vez de falhar
skill-scanner scan /path/to/skill --lenient
skill-scanner scan-all /path/to/skills --recursive --lenient

# Modo leniente com formatos de skill não padronizados (sem SKILL.md obrigatório)
skill-scanner scan .claude/commands/deploy --lenient
skill-scanner scan-all .claude/commands --recursive --lenient

# Usa um nome de arquivo de metadados personalizado em vez de SKILL.md
skill-scanner scan /path/to/skill --skill-file README.md

# CI/CD: Falha o build se ameaças forem encontradas
skill-scanner scan-all ./skills --fail-on-severity high --format sarif --output results.sarif

# Gera relatório HTML interativo com grupos de correlação de ataques
skill-scanner scan /path/to/skill --use-llm --enable-meta --format html --output report.html

# Usa regras YARA personalizadas
skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/

# Usa taxonomia personalizada + perfis de mapeamento de ameaças (JSON/YAML)
skill-scanner scan /path/to/skill --taxonomy /path/to/taxonomy.json --threat-mapping /path/to/threat_mapping.json

# Varredura de hash VirusTotal com uploads opcionais de arquivos desconhecidos
skill-scanner scan /path/to/skill --use-virustotal --vt-upload-files

# Usa uma predefinição de política de varredura (strict, balanced, permissive)
skill-scanner scan /path/to/skill --policy strict

# Usa um arquivo de política organizacional personalizado
skill-scanner scan /path/to/skill --policy my_org_policy.yaml

# Gera um arquivo de política para personalizar
skill-scanner generate-policy -o my_org_policy.yaml

# Configurador interativo de política (TUI)
skill-scanner configure-policy

O modo de consenso mantém um achado somente quando ele aparece em mais da metade das execuções configuradas. Quando esses votos discordam sobre a gravidade, a maior gravidade observada vence, independentemente da ordem das respostas. Execuções com falha e execuções bem-sucedidas que omitem o achado não votam, mas permanecem no denominador. Isso torna a seleção de gravidade estável para achados com acordo majoritário. Isso não torna uma amostra individual de LLM determinística, e campos descritivos de votos com gravidade igual, saída de execução única e achados não majoritários ainda podem variar entre varreduras.

Nota sobre provedores de LLM: --llm-provider atualmente aceita anthropic ou openai. Para Bedrock, Vertex, Azure, Gemini e outros backends LiteLLM, defina strings de modelo e variáveis de ambiente específicas do provedor (consulte documentação do Analisador LLM).

SDK Python

from skill_scanner import SkillScanner
from skill_scanner.core.analyzers import BehavioralAnalyzer

# Cria scanner com analisadores
scanner = SkillScanner(analyzers=[
    BehavioralAnalyzer(),
])

# Varre uma skill
result = scanner.scan_skill("/path/to/skill")

print(f"Achados: {len(result.findings)}")
print(f"Gravidade máxima: {result.max_severity}")

# Nota: is_safe indica que nenhum achado HIGH/CRITICAL foi detectado.
# Isso não garante que a skill esteja livre de todo risco.
if not result.is_safe:
    print("Problemas detectados -- revise os achados antes da implantação")

Analisadores de Segurança

Opções da CLI

Exemplo de Saída

$ skill-scanner scan ./my-skill --use-behavioral

============================================================
Skill: my-skill
============================================================
Status: [OK] Sem achados
Gravidade Máxima: NONE
Total de Achados: 0
Duração da Varredura: 0.15s

Nota: "Sem achados" significa que o scanner não detectou nenhum padrão de ameaça conhecido -- isso não é uma garantia de que a skill esteja livre de todo risco. Consulte Escopo e Limitações.

GitHub Actions

Varre skills automaticamente a cada push ou PR usando o workflow reutilizável:

# .github/workflows/scan-skills.yml
name: Scan Skills
on:
  pull_request:
    paths: [".cursor/skills/**"]
jobs:
  scan:
    uses: cisco-ai-defense/skill-scanner/.github/workflows/scan-skills.yml@main
    with:
      skill_path: .cursor/skills
    permissions:
      security-events: write
      contents: read

Os resultados aparecem como anotações inline em PRs via GitHub Code Scanning. Consulte o guia completo para integração com LLM, configuração de segredos e configuração de proteção de branch.

Hook de Pre-commit

Varre skills antes de cada commit usando o framework pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/cisco-ai-defense/skill-scanner
    rev: v1.0.0  # use a tag de release mais recente
    hooks:
      - id: skill-scanner

Ou instale o hook integrado diretamente:

skill-scanner-pre-commit --install

O hook mapeia arquivos alterados para o SKILL.md mais próximo e varre cada skill afetada uma vez. Durante um commit normal, ele lê o diff em staged. Em CI, compare duas revisões para que nenhum índice staged seja necessário:

pre-commit run skill-scanner --from-ref "$BASE_SHA" --to-ref "$HEAD_SHA"

Ambas as revisões devem existir no checkout. Para varrer todas as skills configuradas, invoque o hook diretamente:

skill-scanner-pre-commit --scan-all

Alternativamente, configure args: [--scan-all] para o hook em .pre-commit-config.yaml.

Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para diretrizes.

Licença

Apache 2.0 - Consulte LICENSE para detalhes.

Copyright 2026 Cisco Systems, Inc. e suas afiliadas

GitHub • Discord • PyPI