Si planeas ejecutar `skillspector mcp`, instala el extra de MCP en el momento de la instalación:```bash
uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

### Docker (no se requiere Python)

Ejecuta SkillSpector sin instalar Python construyéndolo localmente desde el [Dockerfile](https://github.com/nvidia/skillspector/blob/main/Dockerfile) incluido. La imagen está basada en la imagen oficial de Docker Python `3.12-slim-bookworm`.

**Construir la imagen:**```bash
make docker-build
# or: docker build -t skillspector .

**Escanear con análisis LLM** pasando credenciales con un archivo `.env` local:```bash
cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

git clone https://github.com/example/netscan.git
cd netscan
pip install -r requirements.txt
python setup.py install

pip install netscan

docker pull example/netscan:latest
docker run -it --rm example/netscan --help

netscan 192.168.1.1

netscan 192.168.1.0/24

netscan 192.168.1.1 -p 22,80,443,8080

netscan 192.168.1.1 -p 1-1000

netscan 192.168.1.1 -O

netscan 192.168.1.1 -sS

netscan 192.168.1.1 -sU

netscan 192.168.1.1 -oJ results.json
netscan 192.168.1.1 -oX results.xml
netscan 192.168.1.1 -oT results.txt

netscan 192.168.1.0/24 -p 22,80,443

netscan 192.168.1.1 -O -p 1-1000

netscan 192.168.1.0/24 -oJ results.json

O pasa las credenciales directamente desde el entorno de tu 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 escaneos estáticos repetidos:```bash
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm

#### Límites de tamaño

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

- **Límite por ingesta**: `INGEST_MAX_BYTES` (100 MiB) — se aplica a las descargas por URL en streaming, al tamaño total sin comprimir de los archivos zip y al uso de disco posterior al clonado de repositorios Git.
- **Límite por miembro de zip**: `INGEST_MAX_ZIP_MEMBERS` (10,000) — limita la cantidad de entradas en un único zip.

Ten 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```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

Admite detección multilingüe (zh/ja/ko) y salida en terminal/JSON/Markdown.

Para escaneos con LLM con mayor concurrencia, configure múltiples claves de API siguiendo
[`.env.example`](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/.env.example) — el grupo mejora el rendimiento
y la resiliencia, siempre que las claves no compartan un límite de tasa a nivel de cuenta.

Consulte la [guía de contribución](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/docs) para más detalles.

> **Nota sobre el soporte de LLM:** La configuración predeterminada apunta a DeepSeek como la
> opción pública más económica. Se
> [espera que DeepSeek-Chat se descontinúe](https://api-docs.deepseek.com/), y el colaborador
> no dispone de hardware para probar con modelos locales. El escáner por lotes se
> probó originalmente con endpoints compatibles con OpenAI — la falta de soporte de
> salida estructurada de DeepSeek requirió parches manuales de análisis JSON. Si puedes
> contribuir con un backend más universal (Ollama, vLLM u otro proveedor),
> los PR son muy bienvenidos.

### Suprimir falsos positivos (baseline)

Suprime los hallazgos conocidos/aceptados para que la puntuación de riesgo refleje solo los
problemas no triados y los reescaneos muestren solo hallazgos *nuevos*. Consulte la
[guía de supresión](https://github.com/nvidia/skillspector/blob/main/docs/SUPPRESSION.md) para la referencia 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

Ejecuta SkillSpector como un servidor de [Model Context Protocol](https://modelcontextprotocol.io)
para que cualquier agente compatible con MCP (Claude Code, Codex CLI, Gemini CLI) o entorno de ejecución remoto
pueda invocar el escaneo como una herramienta y **condicionar la instalación de skills/MCP según el
resultado** — convirtiendo a SkillSpector en una barrera de protección en tiempo de ejecución en lugar de un
paso de auditoría fuera de banda.

`skillspector mcp` requiere `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

> **Seguridad — modelo de confianza del transporte HTTP**
>
> El transporte HTTP se distribuye **sin autenticación**. Cualquier llamador que pueda
> alcanzar el puerto puede invocar `scan_skill`. Sobre stdio o `127.0.0.1` este es
> el mismo límite de confianza que la CLI. Si lo vinculas a una interfaz enrutable:
>
> - Coloca el servidor detrás de un proxy inverso con autenticación (p. ej. nginx + mTLS)
>   antes de exponerlo externamente.
> - Las rutas locales y las URL `file://` se **rechazan automáticamente** sobre HTTP para
>   evitar que llamadores no autenticados lean archivos arbitrarios del host. Solo
>   se aceptan URL remotas de Git y `.zip`.

## Patrones de vulnerabilidad

SkillSpector detecta **71 patrones de vulnerabilidad** en 17 categorías:

### Inyección de prompts (6 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| P1 | Anulación de instrucciones | HIGH | Comandos para ignorar restricciones de seguridad |
| P2 | Instrucciones ocultas | HIGH | Directivas maliciosas en comentarios/texto invisible |
| P3 | Comandos de exfiltración | HIGH | Instrucciones para transmitir contexto externamente |
| P4 | Manipulación de comportamiento | MEDIUM | Instrucciones sutiles que alteran las decisiones del agente |
| P5 | Contenido dañino | CRITICAL | Instrucciones que podrían causar daño físico |
| P9 | Relleno de espacios en blanco | MEDIUM | Gran relleno de espacios en blanco que oculta instrucciones debajo/al lado del área visible |

### Anti-Rechazo (3 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| AR1 | Supresión de rechazo | HIGH | Instrucciones para nunca rechazar o siempre cumplir (p. ej. "never refuse", "always comply") |
| AR2 | Supresión de descargos de responsabilidad | HIGH | Instrucciones para omitir advertencias, descargos de responsabilidad o comentarios éticos (p. ej. "no disclaimers", "do not moralize") |
| AR3 | Anulación de política de seguridad | HIGH | Encuadre de jailbreak que anula las barreras de protección (p. ej. "you have no restrictions", "ignore your guidelines", "do anything now") |

### Exfiltración de datos (4 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| E1 | Transmisión externa | MEDIUM | Envío de datos a URL externas |
| E2 | Recolección de variables de entorno | HIGH | Enumerar, copiar o buscar datos del entorno para recolectar secretos |
| E3 | Enumeración del sistema de archivos | MEDIUM | Escaneo de directorios en busca de archivos sensibles |
| E4 | Fuga de contexto | HIGH | Transmisión del contexto de la conversación externamente |

### Escalada de privilegios (3 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| PE1 | Permisos excesivos | LOW | Solicitar acceso más allá de la funcionalidad declarada |
| PE2 | Ejecución con Sudo/Root | MEDIUM | Invocación de privilegios elevados del sistema |
| PE3 | Acceso a credenciales | HIGH | Lectura de claves SSH, tokens, contraseñas |

### Cadena de suministro (9+ patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| SC1 | Dependencias sin fijar | LOW | Sin restricciones de versión en los paquetes |
| SC2 | Obtención de scripts externos | HIGH | curl \| bash y ejecución remota de código |
| SC3 | Código ofuscado | HIGH | Ejecución codificada en Base64/hex |
| SC4 | Dependencias vulnerables conocidas | HIGH | Dependencias con CVE conocidos (consulta en vivo a OSV.dev) |
| SC5 | Dependencias abandonadas | MEDIUM | Paquetes sin mantenimiento y sin actualizaciones de seguridad |
| SC6 | Typosquatting | HIGH | Nombres de paquetes similares a paquetes populares |
| SC8 | Bytecode de Python incluido | HIGH | `__pycache__` / `.pyc` presente (el descubrimiento lo omite; omisión de bytecode malicioso) |
| SC9 | Artefacto ejecutable oculto | HIGH | Ejecutable anidado en un contenedor de documento o artefacto oculto/disfrazado |

### Agencia excesiva (5 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| EA1 | Acceso irrestricto a herramientas | HIGH | Acceso sin restricciones a herramientas sin limitaciones |
| EA2 | Toma de decisiones autónoma | HIGH | Decisiones de alto impacto sin intervención humana |
| EA3 | Expansión de alcance | MEDIUM | Capacidades que se extienden más allá del propósito declarado |
| EA4 | Acceso ilimitado a recursos | MEDIUM | Sin límites de velocidad ni cuotas en el consumo de recursos |
| EA5 | Selección de modelo o proveedor externo | MEDIUM/HIGH | Fijaciones de modelo/proveedor o invocaciones de shell de CLI de codificación que pueden cambiar cuentas de facturación |

### Manejo de salida (3 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| OH1 | Inyección de salida no validada | HIGH | Salida del modelo usada sin sanitización |
| OH2 | Salida entre contextos | MEDIUM | La salida fluye entre límites de confianza sin validación |
| OH3 | Salida ilimitada | MEDIUM | Sin límites en el tamaño de salida o la tasa de generación |

### Fuga del prompt del sistema (3 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| P6 | Fuga directa | HIGH | Instrucciones que exponen prompts del sistema o reglas internas |
| P7 | Extracción indirecta | MEDIUM | Extracción mediante reformulación, traducción o canales laterales |
| P8 | Exfiltración basada en herramientas | HIGH | Prompts del sistema exfiltrados mediante escrituras de archivos o solicitudes de red |

### Envenenamiento de memoria (3 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| MP1 | Inyección de contexto persistente | HIGH | Contenido diseñado para persistir entre interacciones |
| MP2 | Relleno de la ventana de contexto | MEDIUM | Contenido de relleno que desplaza las restricciones de seguridad |
| MP3 | Manipulación de memoria | HIGH | Alteración de la memoria del agente o del estado almacenado |

### Uso indebido de herramientas (3 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| TM1 | Abuso de parámetros de herramientas | HIGH | Parámetros manipulados para un comportamiento no previsto (shell=True, --force) |
| TM2 | Abuso de encadenamiento | HIGH | Cadenas de herramientas que eluden las verificaciones de seguridad individuales |
| TM3 | Valores predeterminados inseguros | MEDIUM | Valores predeterminados demasiado permisivos (TLS deshabilitado, sin autenticación) |

### Agente descontrolado (2 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| RA1 | Automodificación | CRITICAL | Modificación del propio código o configuración en tiempo de ejecución |
| RA2 | Persistencia de sesión | HIGH | Persistencia no autorizada mediante trabajos cron o scripts de inicio |

### Abuso de disparadores (3 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| TR1 | Disparador demasiado amplio | MEDIUM | Patrones de disparador que coinciden con palabras comunes |
| TR2 | Disparador de comando en la sombra | HIGH | Disparadores que eclipsan comandos integrados u otras habilidades |
| TR3 | Disparador de cebo por palabra clave | MEDIUM | Disparadores genéricos diseñados para maximizar la activación |

### AST de comportamiento (9 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| AST1 | Llamada a exec() | CRITICAL | exec() directo que permite la ejecución de código arbitrario |
| AST2 | Llamada a eval() | HIGH | eval() directo que evalúa expresiones arbitrarias |
| AST3 | Importación dinámica | HIGH | \_\_import\_\_() que carga módulos arbitrarios en tiempo de ejecución |
| AST4 | Llamada a subprocess | HIGH | Ejecución de comandos externos mediante subprocess |
| AST5 | os.system / familia exec | HIGH | Comandos de shell mediante el módulo os |
| AST6 | Llamada a compile() | MEDIUM | Creación de objetos de código a partir de cadenas |
| AST7 | getattr() dinámico | MEDIUM | Acceso arbitrario a atributos con nombres no literales |
| AST8 | Cadena de ejecución peligrosa | CRITICAL | exec/eval combinado con fuente dinámica (red, datos codificados) |
| AST9 | Sumidero de getattr() reflexivo | HIGH | exec reflexivo mediante `getattr(os,'system')` / `getattr(builtins,'exec')` que evade AST1/AST5 |

### Seguimiento de contaminación (5 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| TT1 | Flujo de contaminación directo | HIGH | Los datos fluyen directamente desde una fuente hasta un sumidero sin sanitización |
| TT2 | Flujo de contaminación mediado por variables | MEDIUM | Los datos fluyen desde la fuente hasta el sumidero a través de variables intermedias |
| TT3 | Cadena de exfiltración de credenciales | CRITICAL | Las credenciales (variables de entorno, secretos) fluyen hacia sumideros de salida de red |
| TT4 | Lectura de archivos a exfiltración de red | HIGH | El contenido de los archivos fluye hacia sumideros de salida de red |
| TT5 | Entrada externa a ejecución de código | CRITICAL | La entrada de red o del usuario fluye hacia sumideros exec/eval/subprocess |

### Firmas YARA (4 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| YR1 | Coincidencia de malware | CRITICAL | Coincidencia de regla YARA para firmas de malware conocidas |
| YR2 | Coincidencia de webshell | CRITICAL | Coincidencia de regla YARA para patrones de webshell |
| YR3 | Coincidencia de criptominero | HIGH | Coincidencia de regla YARA para indicadores de minería de criptomonedas |
| YR4 | Coincidencia de herramienta de hackeo / exploit | HIGH | Coincidencia de regla YARA para herramientas de hackeo o código de exploit |

### MCP de privilegio mínimo (4 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| LP1 | Capacidad subdeclarada | HIGH | El código usa capacidades no listadas en los permisos declarados |
| LP2 | Permiso comodín | MEDIUM | La lista de permisos contiene comodines (\*, all, full, any) |
| LP3 | Declaración de permiso faltante | MEDIUM | Sin campo de permisos pero el código tiene capacidades detectables |
| LP4 | Permiso sobredimensionado | LOW | Permiso declarado pero no se encontró la capacidad de código correspondiente |

### Envenenamiento de herramientas MCP (4 patrones)

| ID | Patrón | Severidad | Descripción |
|----|---------|----------|-------------|
| TP1 | Instrucciones ocultas | HIGH | Directivas ocultas en metadatos (comentarios HTML, caracteres de ancho cero, base64, URI de datos) |
| TP2 | Engaño Unicode | HIGH | Homoglifos, anulaciones RTL, identificadores de escritura mixta en metadatos de herramientas |
| TP3 | Inyección en descripción de parámetros | MEDIUM | Patrones de inyección en definiciones de parámetros (anulaciones, tokens del sistema, valores predeterminados maliciosos) |
| TP4 | Discrepancia entre descripción y comportamiento | MEDIUM | La descripción declarada de la herramienta no coincide con el comportamiento real del código (impulsado por LLM) |

Todos los patrones detectados se enumeran en las tablas anteriores.

## Puntuación de riesgo

### Cálculo de la puntuación

- **Problemas CRITICAL**: +50 puntos
- **Problemas HIGH**: +25 puntos
- **Problemas MEDIUM**: +10 puntos
- **Problemas LOW**: +5 puntos
- **Scripts ejecutables**: multiplicador de 1.3x

### Niveles de severidad

| Puntuación | Severidad | Recomendación |
|-------|----------|----------------|
| 0-20 | LOW | SAFE |
| 21-50 | MEDIUM | CAUTION |
| 51-80 | HIGH | DO NOT INSTALL |
| 81-100 | CRITICAL | DO NOT INSTALL |

## Ejemplo de salida

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

## Integración de SkillSpector

SkillSpector está diseñado para ser controlado por otras herramientas (canalizaciones de CI, puertas de instalación, integraciones de editores). Su código de salida y su salida JSON son un contrato estable.

### Códigos de salida

`skillspector scan` finaliza con:

| Código | Significado |
|------|---------|
| `0` | Escaneo completado, `risk_score` ≤ 50 (recomendación `SAFE` o `CAUTION`) |
| `1` | Escaneo completado, `risk_score` > 50 (recomendación `DO_NOT_INSTALL`) |
| `2` | Error (entrada incorrecta, origen ilegible, fallo interno) |

> El código de salida colapsa `SAFE` y `CAUTION` en `0`. Para actuar de forma diferente ante ellos (p. ej., *advertir* ante `CAUTION` pero *bloquear* ante `DO_NOT_INSTALL`), lea el campo `recommendation` de la salida JSON en lugar de confiar en el código de salida.

### Salida legible por máquina

`--format json` produce un informe JSON; sin `--output`/`-o` se escribe en stdout:```bash
skillspector scan ./my-skill/ --format json

- `risk_assessment.severity` ∈ `LOW | MEDIUM | HIGH | CRITICAL`.
- `risk_assessment.recommendation` ∈ `SAFE | CAUTION | DO_NOT_INSTALL`, asignado desde la severidad: `LOW → SAFE`, `MEDIUM → CAUTION`, `HIGH`/`CRITICAL → DO_NOT_INSTALL`.
- `metadata.llm_error` aparece solo cuando se solicitó el análisis LLM pero no estaba disponible.
- `metadata.inference_usage` contiene un registro saneado por cada respuesta del LLM cuando el
  proveedor expone contadores de tokens. Es una lista vacía cuando el uso no está disponible;
  SkillSpector nunca estima tokens faltantes. Los totales de prompt incluyen las lecturas y
  escrituras de caché para que los precios posteriores puedan separar esas particiones de forma segura.
  `model_source` distingue un modelo de proveedor identificado de forma independiente del
  modelo exacto solicitado utilizado cuando la identidad de la respuesta está ausente o es ambigua.
  SkillSpector actualmente no envía controles de caché de prompt de Anthropic, por lo que sus
  solicitudes de escaneo no pueden seleccionar los niveles separados de escritura de caché de 5 minutos o 1 hora;
  los campos de respuesta específicos de TTL se normalizan de forma defensiva en el contador
  agregado de escritura de caché.
- Consulte [Inference usage telemetry](https://github.com/nvidia/skillspector/blob/main/docs/INFERENCE_USAGE.md) para conocer el contrato completo de
  procedencia, contabilidad de caché, privacidad, ingesta fail-closed y precios posteriores.
- La forma completa por incidencia está definida por `Finding.to_dict()` en [models.py](https://github.com/nvidia/skillspector/blob/main/src/skillspector/models.py); confíe en los campos anteriores y trate cualquier campo adicional como best-effort.

Para herramientas de CI/IDE, `--format sarif` emite SARIF 2.1.0.

### Mapeo de gate recomendado

Cuando se utiliza SkillSpector como gate de instalación, asigne la recomendación a una acción:

| `recommendation` | Acción sugerida |
|------------------|------------------|
| `SAFE` | permitir |
| `CAUTION` | solicitar / advertir al usuario |
| `DO_NOT_INSTALL` | bloquear |

SkillSpector calcula la banda de puntuación y la recomendación; cuán estricto es el gate (por ejemplo, si `CAUTION` bloquea en CI) es una decisión de política para la herramienta que lo integra.

## Desarrollo

### Configuración

Todos los objetivos de `make` asumen que ya se ha creado y activado un entorno virtual. El Makefile usa **uv** si está disponible; de lo contrario, **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

## Licencia

Licencia Apache 2.0 - consulte [LICENSE](https://github.com/nvidia/skillspector/blob/main/LICENSE) para más detalles.

## Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lea nuestras guías de contribución y envíe pull requests.

## Soporte

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