Skill Scanner

Un escáner de seguridad de mejor esfuerzo para AI Agent Skills que detecta inyección de prompts, exfiltración de datos y patrones de código malicioso. Combina detección basada en patrones (YAML + YARA), LLM-as-a-judge y análisis de flujo de datos conductual para maximizar la cobertura de detección de amenazas probables mientras minimiza los falsos positivos.

Importante: Este escáner proporciona detección de mejor esfuerzo, no una cobertura exhaustiva o completa. Un escaneo que no devuelve hallazgos no garantiza que una skill esté libre de todas las amenazas. Consulte Alcance y Limitaciones a continuación.

Admite formatos de OpenAI Codex Skills y Cursor Agent Skills siguiendo la especificación Agent Skills. Con --lenient, también escanea formatos no estándar como .claude/commands/*.md de Claude Code y repositorios de skills en markdown plano.

Destacados

• Detección Multi-Motor - Análisis estático, flujo de datos conductual, análisis semántico LLM y escaneo basado en la nube para una cobertura de mejor esfuerzo en capas
• Filtrado de Falsos Positivos - El meta-analizador reduce significativamente el ruido mientras preserva la capacidad de detección
• Listo para CI/CD - Salida SARIF para GitHub Code Scanning, workflow reutilizable de GitHub Actions, códigos de salida para fallos de compilación
• Hook de Pre-commit - Integración con el framework estándar de pre-commit para escanear skills antes de cada commit
• Extensible - Arquitectura de plugins para analizadores personalizados

Únete al Discord de Cisco AI para debatir, compartir comentarios o conectar con el equipo.

Alcance y Limitaciones

Skill Scanner es una herramienta de detección. Identifica patrones de riesgo conocidos y probables, pero no certifica la seguridad.

Limitaciones clave:

• Sin hallazgos ≠ sin riesgo. Un escaneo que devuelve "Sin hallazgos" indica que no se detectaron patrones de amenaza conocidos. No garantiza que una skill sea segura, benigna o esté libre de vulnerabilidades.
• La cobertura es inherentemente incompleta. El escáner combina detección basada en firmas, análisis semántico basado en LLM, análisis de flujo de datos conductual, servicios en la nube opcionales y paquetes de reglas configurables. Si bien este enfoque mejora la cobertura, ninguna herramienta automatizada puede detectar todas las técnicas, especialmente ataques novedosos o de día cero.
• Pueden ocurrir falsos positivos y falsos negativos. Los modos de consenso y el meta-análisis reducen el ruido, pero ninguna configuración elimina todas las clasificaciones incorrectas. Ajuste la política de escaneo según su tolerancia al riesgo.
• La revisión humana sigue siendo esencial. El escaneo automatizado es un componente de una estrategia de defensa en profundidad. Los despliegues de alto riesgo o producción deben combinar los resultados del escáner con revisión manual de código y/o modelado de amenazas.

Documentación

Instalación

Requisitos previos: Python 3.10+ y uv (recomendado) o pip

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

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

# Soporte para AWS Bedrock
pip install cisco-ai-skill-scanner[bedrock]

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

# Soporte para Google Vertex AI
pip install cisco-ai-skill-scanner[vertex]

# Soporte para Azure OpenAI
pip install cisco-ai-skill-scanner[azure]

# Todos los proveedores en la nube
pip install cisco-ai-skill-scanner[all]

Inicio Rápido

Configuración del Entorno (Opcional)

# Para el analizador LLM y el meta-analizador
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, o max
export SKILL_SCANNER_LLM_REASONING_EFFORT="low"

# Para escaneo binario con VirusTotal
export VIRUSTOTAL_API_KEY="your_virustotal_api_key"

# Para Cisco AI Defense
export AI_DEFENSE_API_KEY="your_aidefense_api_key"

Asistente Interactivo

¿No está seguro de qué banderas usar? Ejecute skill-scanner sin argumentos para lanzar el asistente interactivo:

skill-scanner

El asistente le guía a través de la selección de un objetivo de escaneo, analizadores, política y formato de salida, y luego muestra el comando ensamblado antes de ejecutarlo. Ideal para aprender la CLI.

Uso de la CLI

# Escanear una sola skill (analizadores principales: estático + bytecode + pipeline)
skill-scanner scan /path/to/skill

# Escanear con analizador conductual (análisis de flujo de datos)
skill-scanner scan /path/to/skill --use-behavioral

# Escanear con todos los motores
skill-scanner scan /path/to/skill --use-behavioral --use-llm --use-aidefense

# Escanear con meta-analizador para filtrado de falsos positivos
skill-scanner scan /path/to/skill --use-llm --enable-meta

# Escanear con analizador de disparadores para comprobaciones de descripciones vagas
skill-scanner scan /path/to/skill --use-trigger

# Ejecutar el analizador LLM varias veces y conservar los hallazgos acordados por mayoría
skill-scanner scan /path/to/skill --use-llm --llm-consensus-runs 3

# Escanear múltiples skills de forma recursiva
skill-scanner scan-all /path/to/skills --recursive --use-behavioral

# Escanear múltiples skills con detección de solapamiento entre skills
skill-scanner scan-all /path/to/skills --recursive --check-overlap

# Escanear un repositorio de GitHub (abreviatura owner/repo o URL completa)
skill-scanner scan-repo owner/repo
skill-scanner scan-repo https://github.com/owner/repo --use-llm

# Modo indulgente: tolerar skills malformadas en lugar de fallar
skill-scanner scan /path/to/skill --lenient
skill-scanner scan-all /path/to/skills --recursive --lenient

# Modo indulgente con formatos de skill no estándar (sin SKILL.md requerido)
skill-scanner scan .claude/commands/deploy --lenient
skill-scanner scan-all .claude/commands --recursive --lenient

# Usar un nombre de archivo de metadatos personalizado en lugar de SKILL.md
skill-scanner scan /path/to/skill --skill-file README.md

# CI/CD: Fallar la compilación si se encuentran amenazas
skill-scanner scan-all ./skills --fail-on-severity high --format sarif --output results.sarif

# Generar informe HTML interactivo con grupos de correlación de ataques
skill-scanner scan /path/to/skill --use-llm --enable-meta --format html --output report.html

# Usar reglas YARA personalizadas
skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/

# Usar taxonomía personalizada + perfiles de mapeo de amenazas (JSON/YAML)
skill-scanner scan /path/to/skill --taxonomy /path/to/taxonomy.json --threat-mapping /path/to/threat_mapping.json

# Escaneo de hash con VirusTotal con subidas opcionales de archivos desconocidos
skill-scanner scan /path/to/skill --use-virustotal --vt-upload-files

# Usar un ajuste preestablecido de política de escaneo (strict, balanced, permissive)
skill-scanner scan /path/to/skill --policy strict

# Usar un archivo de política organizacional personalizado
skill-scanner scan /path/to/skill --policy my_org_policy.yaml

# Generar un archivo de política para personalizar
skill-scanner generate-policy -o my_org_policy.yaml

# Configurador interactivo de políticas (TUI)
skill-scanner configure-policy

El modo de consenso conserva un hallazgo solo cuando aparece en más de la mitad de las ejecuciones configuradas. Cuando esos votos discrepan sobre la severidad, gana la severidad observada más alta, independientemente del orden de las respuestas. Las ejecuciones fallidas y las ejecuciones exitosas que omiten el hallazgo no emiten voto pero permanecen en el denominador. Esto hace que la selección de severidad sea estable para hallazgos acordados por mayoría. No hace que una muestra individual de LLM sea determinista, y los campos descriptivos de votos de igual severidad, salida de una sola ejecución y hallazgos no mayoritarios pueden variar entre escaneos.

Nota sobre proveedores de LLM: --llm-provider actualmente acepta anthropic o openai. Para Bedrock, Vertex, Azure, Gemini y otros backends de LiteLLM, establezca cadenas de modelo específicas del proveedor y variables de entorno (consulte la documentación del Analizador LLM).

SDK de Python

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

# Crear escáner con analizadores
scanner = SkillScanner(analyzers=[
    BehavioralAnalyzer(),
])

# Escanear una skill
result = scanner.scan_skill("/path/to/skill")

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

# Nota: is_safe indica que no se detectaron hallazgos HIGH/CRITICAL.
# No garantiza que la skill esté libre de todo riesgo.
if not result.is_safe:
    print("Se detectaron problemas -- revise los hallazgos antes del despliegue")

Analizadores de Seguridad

Opciones de la CLI

Ejemplo de Salida

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

============================================================
Skill: my-skill
============================================================
Estado: [OK] Sin hallazgos
Severidad Máxima: NINGUNA
Total de Hallazgos: 0
Duración del Escaneo: 0.15s

Nota: "Sin hallazgos" significa que el escáner no detectó ningún patrón de amenaza conocido -- no es una garantía de que la skill esté libre de todo riesgo. Consulte Alcance y Limitaciones.

GitHub Actions

Escanee skills automáticamente en cada push o PR usando el workflow reutilizable:

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

Los resultados aparecen como anotaciones en línea en los PRs mediante GitHub Code Scanning. Consulte la guía completa para integración LLM, configuración de secretos y configuración de protección de ramas.

Hook de Pre-commit

Escanee skills antes de cada commit usando el framework pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/cisco-ai-defense/skill-scanner
    rev: v1.0.0  # use la etiqueta de la última versión
    hooks:
      - id: skill-scanner

O instale el hook integrado directamente:

skill-scanner-pre-commit --install

El hook mapea los archivos modificados a su SKILL.md más cercano y escanea cada skill afectada una vez. Durante un commit normal, lee el diff en el área de preparación. En CI, compare dos revisiones para que no se requiera un índice en el área de preparación:

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

Ambas revisiones deben existir en el checkout. Para escanear cada skill configurada, invoque el hook directamente:

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

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

Contribuciones

¡Agradecemos las contribuciones! Consulte CONTRIBUTING.md para las pautas.

Licencia

Apache 2.0 - Consulte LICENSE para más detalles.

Copyright 2026 Cisco Systems, Inc. y sus afiliados

GitHub • Discord • PyPI