security-scan

Habilidad Security Scan

Audita la configuración de tu Claude Code en busca de problemas de seguridad utilizando AgentShield.

Cuándo activarla

• Al configurar un nuevo proyecto de Claude Code
• Después de modificar .claude/settings.json, CLAUDE.md o configuraciones de MCP
• Antes de confirmar cambios en la configuración
• Al integrarte a un nuevo repositorio con configuraciones existentes de Claude Code
• Revisiones periódicas de higiene de seguridad

Qué escanea

Archivo	Comprobaciones
CLAUDE.md	Secretos codificados, instrucciones de ejecución automática, patrones de inyección de prompts
settings.json	Listas de permitidos demasiado permisivas, listas de denegados faltantes, banderas de omisión peligrosas
mcp.json	Servidores MCP riesgosos, secretos de entorno codificados, riesgos de cadena de suministro de npx
hooks/	Inyección de comandos mediante interpolación, exfiltración de datos, supresión silenciosa de errores
agents/*.md	Acceso irrestricto a herramientas, superficie de inyección de prompts, especificaciones de modelo faltantes

Requisitos previos

AgentShield debe estar instalado. Verifica e instala si es necesario:

# Verificar si está instalado
npx ecc-agentshield --version

# Instalar globalmente (recomendado)
npm install -g ecc-agentshield

# O ejecutar directamente mediante npx (sin necesidad de instalación)
npx ecc-agentshield scan .

Uso

Escaneo básico

Ejecuta contra el directorio .claude/ del proyecto actual:

# Escanear proyecto actual
npx ecc-agentshield scan

# Escanear una ruta específica
npx ecc-agentshield scan --path /ruta/a/.claude

# Escanear con filtro de severidad mínima
npx ecc-agentshield scan --min-severity medium

Formatos de salida

# Salida en terminal (predeterminada) — informe coloreado con calificación
npx ecc-agentshield scan

# JSON — para integración con CI/CD
npx ecc-agentshield scan --format json

# Markdown — para documentación
npx ecc-agentshield scan --format markdown

# HTML — informe autónomo con tema oscuro
npx ecc-agentshield scan --format html > informe-seguridad.html

Auto-corrección

Aplica correcciones seguras automáticamente (solo aquellas marcadas como auto-corregibles):

npx ecc-agentshield scan --fix

Esto hará:

• Reemplazar secretos codificados por referencias a variables de entorno
• Ajustar permisos comodín a alternativas con ámbito limitado
• Nunca modificar sugerencias solo manuales

Análisis profundo con Opus 4.6

Ejecuta el pipeline adversarial de tres agentes para un análisis más profundo:

# Requiere ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY=tu-clave
npx ecc-agentshield scan --opus --stream

Esto ejecuta:

1. Atacante (Red Team) — encuentra vectores de ataque
2. Defensor (Blue Team) — recomienda endurecimiento
3. Auditor (Veredicto Final) — sintetiza ambas perspectivas

Inicializar configuración segura

Crea desde cero una configuración segura de .claude/:

npx ecc-agentshield init

Crea:

• settings.json con permisos con ámbito y lista de denegados
• CLAUDE.md con mejores prácticas de seguridad
• mcp.json como plantilla

Acción de GitHub

Añade a tu pipeline de CI:

- uses: affaan-m/agentshield@v1
  with:
    path: '.'
    min-severity: 'medium'
    fail-on-findings: true

Niveles de severidad

Calificación	Puntaje	Significado
A	90-100	Configuración segura
B	75-89	Problemas menores
C	60-74	Requiere atención
D	40-59	Riesgos significativos
F	0-39	Vulnerabilidades críticas

Interpretación de resultados

Hallazgos críticos (corregir inmediatamente)

• Claves de API o tokens codificados en archivos de configuración
• Bash(*) en la lista de permitidos (acceso irrestricto a shell)
• Inyección de comandos en hooks mediante interpolación ${file}
• Servidores MCP que ejecutan shell

Hallazgos altos (corregir antes de producción)

• Instrucciones de ejecución automática en CLAUDE.md (vector de inyección de prompts)
• Listas de denegados faltantes en permisos
• Agentes con acceso innecesario a Bash

Hallazgos medios (recomendados)

• Supresión silenciosa de errores en hooks (2>/dev/null, || true)
• Hooks de seguridad PreToolUse faltantes
• Auto-instalación npx -y en configuraciones de servidores MCP

Hallazgos informativos (conciencia)

• Descripciones faltantes en servidores MCP
• Instrucciones prohibitivas correctamente marcadas como buena práctica

Enlaces

• GitHub: github.com/affaan-m/agentshield
• npm: npmjs.com/package/ecc-agentshield