SkillSpector

Escáner de seguridad para skills de agentes de IA. Detecta vulnerabilidades, patrones maliciosos y riesgos de seguridad antes de instalar skills de agentes.

Descripción general

Las skills de agentes de IA (utilizadas por Claude Code, Codex CLI, Gemini CLI, etc.) se ejecutan con confianza implícita y una verificación mínima. En el subconjunto de 31.132 skills analizadas del conjunto de datos de investigación, el 26,1% de las skills contienen vulnerabilidades y el 5,2% muestran una intención probablemente maliciosa.

SkillSpector te ayuda a responder: "¿Es seguro instalar esta skill?"

SkillSpector forma parte del pipeline NVIDIA Verified Skills, que escanea, evalúa y firma las skills de agentes antes de su publicación. Las skills que superan la evaluación se publican en el catálogo de skills de NVIDIA.

Documentación

• Escanear skills de agentes antes de la instalación — Guía alojada: cuándo escanear, cómo leer un informe y cómo controlar las instalaciones.
• Guía de desarrollo — Arquitectura, estructura del paquete y cómo ampliar el pipeline del analizador.
• Límites de recursos de análisis — Límites de bundle, parser, artefactos anidados, ledger y hallazgos con cierre por fallo.
• Extensión de Pi — Instala SkillSpector como herramienta de Pi para escanear skills desde dentro de sesiones de agentes.
• Extensión de OpenCode — Instala SkillSpector como herramienta de OpenCode y comando /skillspector para escanear skills desde dentro de sesiones de agentes.

Características

• Entrada multiformato: Escanea repositorios Git, URLs, archivos zip, directorios o archivos individuales
• 71 patrones de vulnerabilidad en 17 categorías: inyección de prompts, exfiltración de datos, escalada de privilegios, cadena de suministro, agencia excesiva, manejo de salidas, filtración de prompts del sistema, envenenamiento de memoria, uso indebido de herramientas, agente descontrolado, anti-rechazo, abuso de disparadores, código peligroso (AST), seguimiento de taint, firmas YARA, privilegio mínimo de MCP y envenenamiento de herramientas MCP
• Análisis en dos etapas: Análisis estático rápido + evaluación semántica opcional con LLM
• Consultas de vulnerabilidades en vivo: SC4 consulta OSV.dev para obtener datos de CVE en tiempo real con fallback offline automático
• Múltiples formatos de salida: Informes en terminal, JSON, Markdown y SARIF
• Puntuación de riesgo: Puntuación de 0 a 100 con etiquetas de severidad y recomendaciones claras
• Supresión de líneas base / falsos positivos: Acepta hallazgos conocidos mediante una línea base de reglas glob o de huellas digitales para que los reescaneos solo muestren problemas nuevos (docs)

Inicio rápido

Instalación

Aviso sobre software de código abierto: Este proyecto descargará e instalará proyectos de software de código abierto de terceros adicionales. Revisa los términos de licencia de estos proyectos de código abierto antes de usarlos.

Primero crea y activa un entorno virtual (todos los objetivos de make asumen que el venv está activo). Usa uv o pip; el Makefile usa uv si está disponible; de lo contrario, pip.

Instalación rápida con uv (solo CLI):

uv tool install git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector

Si planeas ejecutar skillspector mcp, instala el extra de MCP en el momento de la instalación:

uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

Del origen:

# Clone the repository
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector

# Create and activate virtual environment
uv venv .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate

# Install for production use
make install

# Or install with development dependencies
make install-dev

Docker (no se requiere Python)

Ejecute SkillSpector sin instalar Python compilándolo localmente a partir del Dockerfile incluido. La imagen está basada en la imagen oficial de Docker Python 3.12-slim-bookworm.

Compile la imagen:

make docker-build
# or: docker build -t skillspector .

Escanear un directorio local montando tu directorio actual en /scan, el directorio de trabajo del contenedor:

docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm

Escanear con análisis de LLM pasando credenciales con un archivo .env local:

cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

docker run --rm \
  -v "$PWD:/scan" \
  --env-file .env \
  skillspector scan ./my-skill/

O pasa las credenciales directamente desde el entorno de tu shell:

docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

Escribir un informe en el sistema de archivos del host escribiendo en el directorio montado:

docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD:/scan" \
  skillspector scan ./my-skill/ --no-llm --format json --output report.json

Alias opcional para escaneos estáticos repetidos:

alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm

Uso básico

# Scan a local skill directory
skillspector scan ./my-skill/

# Scan a single SKILL.md file
skillspector scan ./SKILL.md

# Scan a Git repository
skillspector scan https://github.com/user/my-skill

# Scan a zip file
skillspector scan ./my-skill.zip

Límites de tamaño

SkillSpector aplica dos límites independientes sobre las entradas remotas y de archivo para acotar el impacto de las descargas sobredimensionadas y las bombas zip:

• Límite por ingesta: INGEST_MAX_BYTES (100 MiB) — se aplica a las descargas por streaming desde URL, al tamaño total descomprimido de los archivos zip y al uso de disco posterior al clonado de repositorios Git.
• Límite de miembros del zip: INGEST_MAX_ZIP_MEMBERS (10,000) — limita el número de entradas en un único zip.

Tenga en cuenta que el límite de análisis de 1 MB por archivo (MAX_FILE_BYTES) es un límite posterior e independiente: acota lo que los analizadores individuales leerán de un directorio ya ingestado. Los límites de ingesta anteriores acotan cuánto contenido puede llegar al disco en primer lugar. El incumplimiento de cualquiera de los límites de ingesta falla de forma segura con un IngestLimitExceededError.

Formatos de salida

# 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

Escaneo por lotes