Detectar problemas de seguridad mientras Claude escribe código

Instale el plugin security-guidance para que Claude revise sus propios cambios de código en busca de vulnerabilidades y las corrija en la misma sesión.

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
• Un repositorio git para el directorio en el que trabaja. Las revisiones de fin de turno y confirmación se comparan con el estado de git y se omiten silenciosamente fuera de un repositorio. La verificación de patrón por edición funciona en cualquier lugar

En la primera ejecución, el plugin crea un entorno virtual bajo ~/.claude/security/ e instala el Claude Agent SDK en él, lo que requiere pip y acceso a la red. Si esa instalación falla, la revisión de confirmación vuelve a una revisión de un solo disparo en lugar de la agéntica. En Windows, se omite el paso del entorno virtual, por lo que la revisión de confirmación agéntica se ejecuta solo si claude-agent-sdk ya es importable y de lo contrario vuelve de la misma manera.

Instalar el plugin

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

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

La instalación solicita un alcance. Elija alcance de usuario para escribir el plugin en su configuración de usuario, de modo que se cargue en cada nueva sesión local que inicie en esta máquina. Si Claude Code informa que el marketplace no se encuentra, ejecute /plugin marketplace add anthropics/claude-plugins-official primero, luego reintente la instalación.

Luego actívelo en la sesión actual con /reload-plugins, que aplica cambios de plugin pendientes sin un reinicio:

/reload-plugins

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:

{
  "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, sanitizadores 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. Si los hallazgos de la revisión de confirmación duplican lo que la revisión de fin de turno ya informó, Claude no se vuelve a solicitar, por lo que una confirmación limpia no produce salida visible de esta capa.

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:

# 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:

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."

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:

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, limitada a 20 revisiones por hora móvil. Espere aproximadamente una llamada de revisión por turno que cambie archivos y una revisión más profunda por confirmación, ambas sujetas a los límites anteriores.

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:

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:

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:

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.

Solución de problemas

El plugin escribe diagnósticos de tiempo de ejecución en ~/.claude/security/log.txt. Verifique allí primero si las revisiones no aparecen.

Razones comunes por las que una capa de revisión se omite sin un mensaje en la conversación:

• El directorio no es un repositorio git: las revisiones de fin de turno y confirmación requieren estado de git y se omiten fuera de un repositorio
• La sesión no tiene autenticación de Anthropic: las revisiones respaldadas por modelo se omiten y solo se ejecuta la verificación de patrón por edición
• Un archivo security-patterns.yaml está presente pero PyYAML no es importable: el archivo se ignora. Use security-patterns.json en su lugar

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