Skill Scanner

Um scanner de segurança de melhor esforço para AI Agent Skills que detecta injeção de prompt, exfiltração de dados e padrões de código malicioso. Ele combina detecção baseada em padrões (YAML + YARA-X), análise AST e de fluxo de dados, um LLM-as-a-judge opcional e uma camada de decisão CEL limitada sobre fatos tipados de detectores.
Importante: Este scanner fornece detecção de melhor esforço, não cobertura abrangente ou completa. Uma varredura que não retorna descobertas não garante que uma skill esteja livre de todas as ameaças. Consulte Escopo e Limitações abaixo.
Suporta os formatos OpenAI Codex Skills e Cursor Agent Skills seguindo a especificação Agent Skills. Com --lenient, também varre formatos não padrão, como Claude Code .claude/commands/*.md e repositórios de skills em markdown plano.
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
- Decisões CEL Tipadas - O scanner principal usa o runtime oficial
cel-go v0.32.0 para correlacionar fatos limitados após a detecção determinística e antes da análise opcional por LLM
- Presets Medidos - Presets
low-noise e quiet e limites de LLM, com recall, taxa de falsos positivos e F1 publicados para cada um (Configurações Recomendadas)
- Pronto para CI/CD - Saída SARIF para GitHub Code Scanning, workflow reutilizável do GitHub Actions, códigos de saída para falhas de build
- Hook de Pre-commit - Integração com o framework padrão de pre-commit para varrer skills antes de cada commit
- Extensível - Arquitetura de plugins para analisadores personalizados
Participe do Cisco AI Discord para discutir, compartilhar feedback ou se conectar 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:
- Nenhuma descoberta ≠ nenhum risco. Uma varredura que retorna "Nenhuma descoberta" 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 baseada em LLM, análise de fluxo de dados comportamental, serviços de nuvem opcionais e pacotes de regras configuráveis. Embora essa abordagem melhore a cobertura, nenhuma ferramenta automatizada consegue detectar todas as técnicas, especialmente ataques novos ou de dia zero.
- Falsos positivos e falsos negativos podem ocorrer. Presets, o juiz LLM e supressões com escopo reduzem o ruído, mas nenhuma configuração elimina todas as classificações incorretas. Escolha uma configuração equilibrada em Recommended Settings e ajuste a política de varredura conforme sua tolerância ao 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 em produção devem combinar os resultados do scanner com revisão manual de código e/ou modelagem de ameaças.
Resultados medidos
Em skills de validação (divisão de teste congelada do MaliciousSkillBench, 839 maliciosas e 545 inofensivas):
- Apenas as regras detectam 7,7% das skills maliciosas em HIGH, com uma taxa de falsos positivos de 4,0%.
- Com o juiz LLM (Gemma 4 26B,
balanced), 66,7% chegam à revisão em MEDIUM+ (15,4% de FPR), e
33,7% são bloqueadas em HIGH (6,4% de FPR).
Cada número, com seu corpus e método, está em Measured Results
e no Space de avaliação.
Documentação
O site de documentação é cisco-ai-defense.github.io/docs/skill-scanner.
Páginas aprofundadas ficam em docs/.