Detectar problemas de seguridad mientras Claude escribe código

El plugin security guidance hace que Claude revise sus propios cambios de código en busca de vulnerabilidades comunes mientras trabaja y corrija lo que encuentra en la misma sesión. El plugin detecta problemas como inyección, deserialización insegura y APIs DOM inseguras antes de que el código llegue a una solicitud de extracción, reduciendo cuánta revisión de seguridad recae en los revisores humanos posteriores. Una vez instalado, el plugin se ejecuta automáticamente. No hay nada que invocar y ningún comando separado que recordar. El plugin es el compañero en sesión de Code Review, que se ejecuta en solicitudes de extracción. Este plugin reduce lo que llega al PR. Code Review atrapa lo que hace. Para ver cómo el plugin se superpone con revisión bajo demanda y escaneo de CI, consulte Cómo se ajusta esto con otras herramientas de seguridad.

Requisitos previos

Claude Code CLI versión 2.1.144 o posterior
Python 3.8 o posterior en su PATH. El plugin intenta python3, python y py -3 en ese orden

Instalar el plugin

En una sesión de Claude Code, instale desde el marketplace oficial de Anthropic:

/plugin install security-guidance@claude-plugins-official

Luego actívelo en la sesión actual:

/reload-plugins

La instalación se escribe en su configuración de usuario, por lo que el plugin se carga en cada nueva sesión local que inicie en esta máquina. Las sesiones que ya estaban en ejecución necesitan /reload-plugins para cargarlo.

Habilitar en sesiones en la nube y repositorios compartidos

Los plugins con alcance de usuario no se transfieren a Claude Code en la web, porque esas sesiones se ejecutan en la infraestructura de Anthropic en lugar de su máquina. Para habilitar el plugin allí, o para activarlo para todos los que clonan un repositorio, declárelo en la configuración del proyecto registrada:

.claude/settings.json

{
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true
  }
}

Los administradores pueden habilitar el plugin en toda la organización configurando enabledPlugins en configuración administrada.

Qué verifica el plugin

El plugin revisa el trabajo de Claude en tres puntos, cada uno a una profundidad diferente:

En cada edición de archivo: una coincidencia de patrón rápida para llamadas riesgosas, sin llamada de modelo
Al final de cada turno: una revisión de modelo de fondo de todo lo que ese turno cambió
En cada confirmación o inserción que Claude realiza: una revisión agéntica más profunda que lee el código circundante

Puede extender cada capa agregando sus propias reglas. Las verificaciones integradas no se pueden eliminar individualmente, pero puede deshabilitar cada capa de forma independiente.

En cada edición de archivo

Cuando Claude escribe en un archivo, el plugin escanea el nuevo contenido en busca de patrones conocidos riesgosos. Esta es una coincidencia de patrón sin llamada de modelo, por lo que no agrega costo de uso. Categorías de patrones de ejemplo:

Ejecución de código dinámico: eval(, new Function, os.system, child_process.exec
Deserialización insegura: pickle
Inyección DOM: dangerouslySetInnerHTML, .innerHTML =, document.write
Archivos de flujo de trabajo: ediciones bajo .github/workflows/, que pueden otorgar permisos a nivel de repositorio

La verificación se ejecuta después de que la edición se realiza y agrega la advertencia al contexto de Claude para el siguiente paso. Cada advertencia se activa una vez por patrón por archivo por sesión, por lo que las coincidencias repetidas en el mismo archivo no inundan la conversación. Puede agregar sus propios patrones a esta capa con un archivo security-patterns.yaml.

Al final de cada turno

Un turno es una ronda de respuesta de Claude: usted envía un mensaje, Claude trabaja y responde, y el turno termina. Después de cada turno, el plugin calcula un diff de git de todo lo que cambió en el árbol de trabajo durante el turno, incluidos los cambios de las herramientas de edición de Claude, comandos Bash y subagentos, y lo envía a una revisión de Claude separada enfocada en seguridad. La revisión se ejecuta en segundo plano, por lo que la respuesta de Claude no se retrasa. Si la revisión encuentra problemas, Claude se vuelve a solicitar con los hallazgos y los aborda como seguimiento. Esto detecta problemas que una coincidencia de cadena no puede, como:

Omisión de autorización
Referencias directas a objetos inseguras
Inyección
Falsificación de solicitud del lado del servidor
Criptografía débil

Usted ve tanto el hallazgo como la resolución de Claude directamente en su sesión. La revisión cubre hasta 30 archivos modificados por turno y se activa como máximo tres veces seguidas antes de ceder el control a usted.

En cada confirmación o inserción que Claude realiza

Cuando Claude ejecuta git commit o git push a través de su herramienta Bash, el plugin ejecuta una revisión agéntica más profunda del cambio en segundo plano. Esta revisión lee el código circundante, incluidos los llamadores, desinfectantes y archivos relacionados, para decidir si un hallazgo es real antes de informarlo. El contexto adicional mantiene los falsos positivos bajos en patrones que se ven peligrosos en aislamiento pero son seguros en su base de código. Esta capa se activa solo en confirmaciones e inserciones que Claude realiza a través de su herramienta Bash. Las confirmaciones que ejecuta desde su propio shell, incluido el escape de shell ! dentro de una sesión, no se revisan. Las revisiones de confirmación e inserción se limitan a 20 por hora móvil.

Independencia de revisión y límites

El plugin no le pide a la misma instancia de Claude que escribió el código que se califique a sí misma. La verificación por edición es una coincidencia de cadena determinista sin modelo involucrado. Las revisiones de fin de turno y confirmación se ejecutan como una llamada de Claude separada con un contexto nuevo y un mensaje enfocado en seguridad: el revisor comienza desde el diff, no tiene inversión en el enfoque original y solo se le instruye para encontrar problemas. Ninguna de las capas bloquea escrituras o confirmaciones. Los hallazgos llegan a Claude que escribe como instrucciones, Claude los aborda en la conversación, y el modelo de revisión puede perder problemas. Trate el plugin como una capa de defensa en profundidad, no como una solución de seguridad completa. Consulte Cómo se ajusta esto con otras herramientas de seguridad.

Agregue sus propias reglas

El plugin tiene dos puntos de extensión: un archivo de orientación Markdown para las revisiones respaldadas por modelo, y un archivo de patrones YAML o JSON para la coincidencia de cadena por edición. Ambos son aditivos. Puede agregar verificaciones pero no puede deshabilitar las integradas desde estos archivos.

Agregue orientación para las revisiones respaldadas por modelo

Cree .claude/claude-security-guidance.md en su proyecto y describa su modelo de amenaza y lista de verificación de revisión en lenguaje simple. Las revisiones respaldadas por modelo lo cargan como contexto adicional junto con la lista de verificación de vulnerabilidades integrada. El siguiente ejemplo es para un servicio web con rutas de administrador con puerta de rol y una política de registro de datos de cliente:

.claude/claude-security-guidance.md

# Security guidance for this repo

- Do not log `customer_id` or `account_number` at INFO level or above.
- All routes under `/admin` must call `require_role("admin")` before any database read.
- Use `crypto.timingSafeEqual` for token comparison instead of `===`.

Estas reglas son orientación para el revisor, no guardrails deterministas. El plugin expone las violaciones como hallazgos para que Claude las corrija, pero no bloquea escrituras ni garantiza que se detecte cada violación. La orientación es solo aditiva: una regla que dice ignorar una clase de vulnerabilidad no suprime esos hallazgos. Para aplicación estricta, empareje el plugin con un hook que bloquee la edición o una verificación de CI.

Agregue patrones personalizados por edición

Cree .claude/security-patterns.yaml para agregar reglas de regex o subcadena a la verificación de patrón por edición. Estos se ejecutan como coincidencias de cadena deterministas junto con los patrones integrados:

.claude/security-patterns.yaml

patterns:
  - rule_name: internal_api_key
    substrings: ["sk_live_", "AKIA"]
    reminder: "Hardcoded API key prefix. Load credentials from the secret manager."
  - rule_name: tenant_unfiltered_query
    regex: "\\.objects\\.all\\(\\)"
    paths: ["src/tenants/**"]
    reminder: "Multi-tenant code must filter by org_id."

Campo	Tipo	Descripción
`rule_name`	string	Identificador mostrado en la advertencia
`reminder`	string	Texto de advertencia agregado al contexto de Claude, limitado a 1 KB
`regex`	string	Regex de Python coincidido contra el contenido editado
`substrings`	list	Subcadenas literales; proporcione esto o `regex`
`paths`	list	Patrones glob opcionales; la regla se aplica solo a archivos coincidentes
`exclude_paths`	list	Patrones glob opcionales para omitir

El plugin también lee .claude/security-patterns.yml y .claude/security-patterns.json con el mismo esquema. JSON funciona en cualquier instalación de Python. Los formularios YAML requieren que PyYAML sea importable, que el plugin no instala para usted. El plugin carga hasta 50 reglas personalizadas y omite regexes que parecen propensas a retroceso catastrófico.

Ubicaciones de búsqueda de archivos de reglas

El plugin busca claude-security-guidance.md y security-patterns.yaml en las mismas ubicaciones, independientemente de cómo se habilitó el plugin:

Alcance	Ruta	Notas
Usuario	`~/.claude/claude-security-guidance.md`	Se aplica a cada proyecto en su máquina
Proyecto	`.claude/claude-security-guidance.md`	Registrado con el repositorio
Proyecto local	`.claude/claude-security-guidance.local.md`	Ignorado por Git, para anulaciones personales

El plugin carga todas las ubicaciones que existen y las concatena, con un límite combinado de 8 KB para el archivo de orientación. Los administradores pueden distribuir reglas en toda la organización empujando el archivo de alcance de usuario a ~/.claude/ a través de la administración de dispositivos. Las mismas rutas se aplican a security-patterns.yaml.

Costo de uso

La verificación de patrón por edición no realiza llamada de modelo y no agrega costo. Las revisiones de fin de turno y confirmación cada una gasta uso de modelo adicional que cuenta hacia su uso como cualquier otra solicitud de Claude. La revisión de confirmación es agéntica y puede tomar varios turnos de modelo por confirmación. El aumento se escala con la frecuencia con que Claude edita archivos y confirma en la sesión. Ambas revisiones respaldadas por modelo usan Claude Opus 4.7 de forma predeterminada. Configure SECURITY_REVIEW_MODEL para elegir un modelo diferente para la revisión de fin de turno y SG_AGENTIC_MODEL para la revisión de confirmación. El plugin está disponible en todos los planes.

Deshabilitar o desinstalar

Para desactivar capas individuales mientras mantiene el resto, configure la variable de entorno coincidente:

Variable	Efecto
`ENABLE_PATTERN_RULES=0`	Deshabilitar la verificación de patrón por edición
`ENABLE_STOP_REVIEW=0`	Deshabilitar la revisión de diff de fin de turno
`ENABLE_COMMIT_REVIEW=0`	Deshabilitar la revisión de confirmación e inserción
`ENABLE_CODE_SECURITY_REVIEW=0`	Deshabilitar todas las revisiones respaldadas por modelo a la vez
`SECURITY_GUIDANCE_DISABLE=1`	Deshabilitar el plugin completamente sin desinstalar

Para pausar el plugin en su alcance de usuario:

/plugin disable security-guidance@claude-plugins-official

Para eliminarlo de su alcance de usuario:

/plugin uninstall security-guidance@claude-plugins-official

Si el plugin se habilitó a través del .claude/settings.json de un proyecto, deshabilitarlo desde /plugin escribe una anulación a su .claude/settings.local.json en lugar de editar el archivo registrado, por lo que el plugin permanece desactivado para usted mientras que los compañeros de equipo no se ven afectados. Si se habilitó a través de configuración administrada, solo un administrador puede deshabilitarlo.

Cómo se integra el plugin con Claude Code

El plugin se construye completamente en hooks, el mecanismo para ejecutar su propio código en puntos específicos del bucle de Claude. Se registra:

Evento de hook	Propósito
`SessionStart`	Inicializar el entorno de Python del plugin
`UserPromptSubmit`	Capturar la línea de base del árbol de trabajo contra la que el diff de revisión de fin de turno se compara
`PostToolUse` en `Edit`, `Write` y `NotebookEdit`	Coincidencia de patrón por edición
`Stop`	Revisión de diff de fin de turno, ejecutada en segundo plano
`PostToolUse` en `Bash`, filtrado a `git commit` y `git push`	Revisión de confirmación e inserción, ejecutada en segundo plano

Si construye sus propios hooks, el código fuente del plugin es un ejemplo funcional de ejecutar una llamada de modelo separada desde un hook y alimentar el resultado de vuelta a la sesión.

Cómo se ajusta esto con otras herramientas de seguridad

El plugin es una capa en un enfoque de defensa en profundidad. Detecta problemas lo antes posible, mientras el código aún está en el editor, pero no es una garantía y no reemplaza verificaciones posteriores. Una pila típica:

Etapa	Herramienta	Qué cubre
En sesión	Plugin de orientación de seguridad	Vulnerabilidades comunes en código que Claude escribe, corregidas en la misma sesión
Bajo demanda	`/security-review`	Paso de seguridad único en la rama actual, ejecutado cuando lo solicita
En solicitud de extracción	Code Review, planes de equipo y empresa	Revisión de corrección y seguridad multiagente con contexto completo de base de código
En CI	Sus analizadores estáticos existentes y escáneres de dependencias	Reglas específicas del idioma, verificaciones de cadena de suministro y aplicación de políticas que el plugin no intenta

Cada etapa posterior atrapa lo que las anteriores pierden. El valor del plugin es reducir el volumen que llega a ellas, no eliminar la necesidad de ellas.

Recursos relacionados

Para profundizar en los temas que toca esta página:

Code Review: configurar la revisión multiagente en tiempo de PR
Automatizar flujos de trabajo con hooks: construir sus propias verificaciones en los mismos puntos del ciclo de vida
Descubrir e instalar plugins: explorar otros plugins oficiales

Documentation Index

​Requisitos previos

​Instalar el plugin

​Habilitar en sesiones en la nube y repositorios compartidos

​Qué verifica el plugin

​En cada edición de archivo

​Al final de cada turno

​En cada confirmación o inserción que Claude realiza

​Independencia de revisión y límites

​Agregue sus propias reglas

​Agregue orientación para las revisiones respaldadas por modelo

​Agregue patrones personalizados por edición

​Ubicaciones de búsqueda de archivos de reglas

​Costo de uso

​Deshabilitar o desinstalar

​Cómo se integra el plugin con Claude Code

​Cómo se ajusta esto con otras herramientas de seguridad

​Recursos relacionados