01 Qué es y por qué instalarlo
Cuando un agente escribe código rápido, también puede dejar huecos rápido: una contraseña escrita en el código, una consulta sin validar o una ruta que no comprueba si el usuario tiene permiso. security-guidance es un plugin que Anthropic publica en su repositorio de Claude Code y en su marketplace oficial. Se engancha mediante hooks al trabajo de Claude y revisa lo que escribe sin que tengas que pedírselo.
Busca las clases de fallo más comunes en aplicaciones web: inyección, XSS, SSRF, secretos en el código, IDOR (acceder a recursos de otro usuario cambiando un identificador), saltos de autenticación, deserialización insegura y recorrido de rutas.
| Capa | Cuándo actúa | Cómo revisa |
|---|---|---|
| 1. Patrones | Cada vez que Claude crea o edita un archivo | Expresiones regulares sobre unos 25 patrones peligrosos conocidos. Local e instantáneo. |
| 2. Revisión del diff | Cuando Claude termina su turno | Envía los cambios a un modelo y devuelve a Claude los hallazgos graves para que los corrija antes de responderte. |
| 3. Revisión al hacer commit | Al ejecutar git commit | Un revisor agéntico lee archivos relacionados para seguir el flujo de datos y detectar fallos que afectan a varios archivos. |
02 Requisitos e instalación
- ✓Claude Code 2.1.144 o superior (compruébalo con claude --version).
- ✓Python 3.8 o superior disponible como python3, python o py -3.
- ✓Una vía de acceso al modelo que funcione: suscripción, clave de API o proveedor externo.
- ✓Un repositorio git: la capa 1 funciona en cualquier carpeta, pero las capas 2 y 3 comparan cambios.
-
1
Abre Claude Code en tu proyecto
Desde el terminal, entra en la carpeta del repositorio y ejecuta claude.
-
2
Instala el plugin
El marketplace oficial viene activado por defecto, así que basta con un comando.
-
3
Recarga
Ejecuta /reload-plugins o reinicia Claude Code para que cargue los hooks.
-
4
Comprueba
Con /plugin list deberías ver security-guidance entre los instalados.
/plugin install security-guidance@claude-plugins-official
/reload-plugins
/plugin list03 Pruébalo con un fallo provocado
La forma más rápida de confirmar que funciona es pedirle a Claude algo inseguro en un archivo de pruebas y ver cómo reacciona el plugin.
Crea un archivo temporal llamado demo_inseguro.py con una función que cargue un archivo de configuración YAML recibido del usuario usando yaml.load sin cargador seguro, y una constante API_KEY con un valor inventado escrito directamente en el código. Es solo para comprobar que el plugin de seguridad avisa; después lo borraremos.Deberías ver avisos de la capa 1 sobre la carga insegura y el secreto en el código, y en muchos casos Claude corregirá el archivo al terminar el turno gracias a la capa 2. Borra el archivo al acabar.
04 Añade las reglas de tu proyecto
Las reglas integradas cubren fallos genéricos. Lo que el modelo no puede adivinar son las normas de tu código: qué tabla no se toca desde según qué servicio, qué función hay que usar para peticiones externas o qué rutas exigen un rol. Para eso, crea un archivo claude-security-guidance.md en alguna de estas ubicaciones:
~/.claude/claude-security-guidance.md: reglas para todos tus proyectos..claude/claude-security-guidance.md: reglas del proyecto, pensadas para subir al repositorio..claude/claude-security-guidance.local.md: ajustes locales que no se suben (añádelo a.gitignore).
Se combinan en ese orden y se añaden a la revisión del diff (capa 2), con un límite de 8 KB. La revisión al hacer commit no lee este archivo por ahora.
# Reglas de seguridad del proyecto
- Toda ruta bajo /admin debe comprobar el rol con la política AdminPolicy antes de consultar datos.
- Nunca registrar en logs el NIF, el IBAN ni el correo de clientes.
- Las peticiones HTTP a URLs proporcionadas por el usuario pasan por el cliente con lista blanca de dominios.
- La comparación de tokens se hace con hash_equals, nunca con ==.Revisa la estructura de este proyecto (autenticación, acceso a datos, llamadas externas, tratamiento de datos personales) y redacta un archivo .claude/claude-security-guidance.md con entre 5 y 10 reglas específicas de este código que una revisión genérica no podría deducir. Cada regla en una línea, concreta y comprobable. No incluyas secretos ni valores reales en el archivo.05 Qué datos envía
| Elemento | ¿Sale de tu ordenador? |
|---|---|
| Capa 1 (patrones) | No. Se ejecuta en local. |
| Capa 2 (diff) | Sí: rutas modificadas, fragmentos del diff y contenido relevante de los archivos. |
| Capa 3 (commit) | Sí: lo anterior más los archivos que el revisor lee para seguir el flujo de datos. |
| Tus reglas | Sí: se añaden al prompt de cada revisión de la capa 2. |
| Registro de depuración | No. Se guarda en ~/.claude/security/log.txt sin contenido completo ni prompts. |
Los datos van al mismo destino que el resto de Claude Code: la API de Anthropic, tu pasarela si tienes ANTHROPIC_BASE_URL configurada, o tu proveedor (Bedrock, Vertex, Foundry). Si tu política interna no permite enviar código a un modelo, desactiva las capas 2 y 3 y quédate con la 1.
06 Desactivar capas y otros ajustes
| Variable de entorno | Efecto |
|---|---|
| SECURITY_GUIDANCE_DISABLE=1 | Desactiva el plugin entero. |
| ENABLE_PATTERN_RULES=0 | Desactiva la capa 1. |
| ENABLE_STOP_REVIEW=0 | Desactiva la capa 2 y mantiene la revisión al hacer commit. |
| ENABLE_COMMIT_REVIEW=0 | Desactiva la capa 3. |
| ENABLE_CODE_SECURITY_REVIEW=0 | Desactiva todas las revisiones con modelo (capas 2 y 3). |
| SECURITY_REVIEW_MODEL | Cambia el modelo de la revisión del diff; SG_AGENTIC_MODEL hace lo mismo con la de commit. |
Preguntas frecuentes
El plugin es gratuito. La capa 1 no consume modelo; las capas 2 y 3 hacen llamadas que cuentan como uso normal de tu suscripción o de tu API.
Comprueba que aparece en /plugin list, que has recargado con /reload-plugins y que Python está disponible. El registro en ~/.claude/security/log.txt da pistas, y si usas Bedrock o Vertex, revisa que SECURITY_REVIEW_MODEL use el identificador propio de tu proveedor.
Solo la capa 1. Las revisiones del diff y del commit necesitan git para saber qué ha cambiado.
/security-review lo lanzas tú y analiza la rama completa frente a la principal. El plugin actúa solo y de forma continua mientras Claude escribe. Se complementan.
Para equipos pequeños sin especialistas en seguridad y para aplicaciones con usuarios, pagos o datos personales. En un experimento local sin datos reales aporta menos, aunque no estorba.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.