Github Security Audit

GitHub Security Audit — Evaluación de Riesgo para Repos

Auditoría sistemática de repositorios GitHub antes de integrarlos en un stack de producción o recomendarlos a clientes. Inspirada en los frameworks de Trail of Bits (supply-chain-risk-auditor, insecure-defaults, sharp-edges) pero adaptada a un flujo agéntico MCP-first.

Filosofía

NO evalúes repos con intuición. Evalúa con datos.
NO busques razones para adoptarlo. Busca razones para NO adoptarlo.
Si no encuentras razones para rechazarlo, entonces puede entrar.

Regla de oro: Un repo que resuelve un problema que tu stack ya cubre NO aporta valor, independientemente de su calidad. Evaluamos primero si hay necesidad real antes de gastar tiempo en el análisis completo.

---

Dos modos de ejecución

| Modo | Comando | Bloques | Tool calls | Uso | |------|---------|---------|------------|-----| | Completo | audit repo | 7 fases | 10-20 | Evaluación integral pre-integración | | Quick | audit repo quick | Fases 0+1+2 | 5-8 | Descarte rápido o primera impresión |

---

PASO 0 — Gate de Necesidad (OBLIGATORIO, antes de CUALQUIER análisis)

Antes de analizar seguridad, responder:

1. ¿Qué problema resuelve este repo? (definir en una frase)
2. ¿Está ese problema ya cubierto en el stack actual? (MCPs, skills, herramientas)
3. ¿Aporta capacidad genuinamente nueva?

Si la respuesta a (2) es SÍ y a (3) es NO → VEREDICTO: SKIP — no continuar. Informar al usuario con la justificación y sugerir la herramienta existente.

Si hay duda razonable o el usuario insiste → continuar con Fase 1.

---

FASE 1 — Salud del Proyecto

Fuentes: webfetch del repo GitHub, GitHub API vía webfetch.

Recopilar:

| Métrica | Cómo obtenerla | Umbral VERDE | Umbral ROJO | |---------|---------------|--------------|-------------| | Stars | Página del repo | >500 | 50 | 60% | 180 días | | Contributors | Tab contributors | >5 | 1 (bus factor) | | Releases | Tab releases | Versionado semántico | Sin releases | | README calidad | Contenido | Docs completas, ejemplos | Sin README o stub | | CI/CD | GitHub Actions / badges | Tests automáticos | Sin CI |

Scoring: Cada métrica 0-10, peso total = 20% del scoring final.

Consultar references/health-scoring.md para tabla de puntuación detallada.

---

FASE 2 — Seguridad del Código

Fuentes: web_fetch de archivos clave del repo.

2.1 Análisis estático (sin ejecutar código)

Revisar vía web_fetch:

• Secrets hardcodeados: buscar en código fuente patrones de API keys, tokens, passwords

(password =, api_key =, secret, token, .env committeados)

• Dependencias conocidas vulnerables: revisar package.json, requirements.txt,

Cargo.toml, go.mod — cruzar versiones con CVEs conocidos vía web_search

• Permisos excesivos: en GitHub Actions workflows (.github/workflows/*.yml),

buscar permissions: write-all, pull_request_target, secrets en PRs de forks

• Ejecución dinámica peligrosa: eval(), exec(), subprocess.call(shell=True),

dangerouslySetInnerHTML, innerHTML, deserialization no segura

• Configuración insegura por defecto: siguiendo el patrón de Trail of Bits

insecure-defaults — ¿el repo funciona de forma insegura si no configuras nada?

2.2 Dependencias transitivas

• ¿Cuántas dependencias directas tiene?
• ¿Hay dependencias con un solo maintainer?
• ¿Hay dependencias que hayan sido comprometidas anteriormente?

Scoring: 0-10, peso = 25% del scoring final.

Consultar references/security-patterns.md para checklist completo.

---

FASE 3 — Supply Chain

Fuentes: web_search perfil del maintainer, historial del repo.

| Señal | VERDE | ROJO | |-------|-------|------| | Maintainer(s) identificables | Persona/org real, historial público | Cuenta nueva, sin historial | | Organización respaldada | Empresa conocida, funding | Anónimo, sin contexto | | Historial de seguridad | Vulnerabilidades parcheadas rápido | CVEs abiertos, sin respuesta | | Publicación en registros oficiales | npm/PyPI con 2FA, verified publisher | Sin publicación oficial | | Code review en PRs | PRs revisados antes de merge | Push directo a main | | SECURITY.md | Existe con disclosure policy | No existe | | Firmado de commits/releases | GPG signatures | Sin firmar |

Scoring: 0-10, peso = 20% del scoring final.

Consultar references/supply-chain-signals.md para análisis detallado.

---

FASE 4 — Calidad de Código

Fuentes: web_fetch de archivos representativos.

• Test coverage: ¿Mencionado en README/CI? ¿Qué porcentaje?
• Type hints / tipos estáticos: ¿Usa tipado?
• Documentación de API: ¿Docstrings/JSDoc/rustdoc?
• Arquitectura: ¿Modular o monolítico? ¿Separación de concerns?
• Error handling: ¿Try/catch genéricos o manejo específico?
• Logging: ¿Tiene logging estructurado?

Scoring: 0-10, peso = 10% del scoring final.

---

FASE 5 — Licencia y Compatibilidad Legal

Fuentes: web_fetch del archivo LICENSE.

| Licencia | Compatibilidad general | Notas | |----------|---------------------|-------| | MIT, BSD-2, BSD-3 | ✅ Total | Sin restricciones | | Apache-2.0 | ✅ Total | Cláusula de patentes favorable | | CC-BY-4.0, CC-BY-SA-4.0 | ⚠️ Parcial | OK para skills/docs, no para código | | GPL-2.0, GPL-3.0 | ⚠️ Condicional | Copyleft — evaluar si es dependencia o integración | | AGPL-3.0 | ❌ Alto riesgo | Copyleft de red — afecta SaaS | | SSPL, BSL, propietaria | ❌ No usar | Restricciones comerciales | | Sin licencia | ❌ No usar | Copyright por defecto, sin permisos |

Scoring: 0-10, peso = 10% del scoring final.

---

FASE 6 — Superficie de Ataque MCP/Plugin/Skill

Aplica cuando: el repo es un MCP server, plugin de Claude Code, skill, herramienta de integración, o cualquier software que se ejecute con acceso a datos de clientes.

Inspirado en Trail of Bits agentic-actions-auditor y sharp-edges.

Checklist MCP/Plugin

• [ ] ¿Qué permisos pide? (filesystem, red, env vars, secrets)
• [ ] ¿Envía datos a terceros? (telemetría, analytics, APIs externas)
• [ ] ¿Almacena datos localmente? ¿Dónde? ¿Cifrado?
• [ ] ¿Tiene hooks que se ejecuten automáticamente? (pre/post tool use)
• [ ] ¿El código del MCP server es auditable? ¿O es un binario/servicio remoto?
• [ ] ¿Usa eval(), exec() o ejecución dinámica de código proporcionado por el usuario?
• [ ] ¿Valida inputs del LLM antes de ejecutar? (prompt injection surface)
• [ ] ¿Tiene rate limiting?
• [ ] ¿Qué pasa si falla? (fail-open vs fail-secure)

Racionalizaciones a Rechazar

(Inspirado en Trail of Bits "Rationalizations to Reject")

• "Es open source, así que es seguro" → NO. Open source ≠ auditado.
• "Tiene muchas stars" → NO. Stars miden popularidad, no seguridad.
• "Lo usa empresa X" → NO. A menos que empresa X haya hecho auditoría pública.
• "Es solo lectura" → VERIFICAR. ¿Realmente? ¿No escribe logs, caché, temp files?
• "Solo lo usaré internamente" → NO reduce el riesgo si toca datos de clientes.
• "El maintainer parece confiable" → VERIFICAR con datos, no con sensación.

Scoring: 0-10, peso = 15% del scoring final (0% si no aplica, redistribuido).

---

FASE 7 — Señales de Confianza Externas

Fuentes: web_search.

• ¿Ha sido mencionado en publicaciones de seguridad? (positiva o negativamente)
• ¿Tiene auditorías de terceros?
• ¿Aparece en listas curadas de calidad? (awesome-X, Trail of Bits skills-curated)
• ¿Ha sido reportado como malicioso en algún momento?
• ¿Tiene programa de bug bounty o SECURITY.md?

Scoring: 0-10, peso = bonus (no resta, solo suma hasta +5 puntos al total).

---

Cálculo de Scoring Final

SCORE = (F1 × 0.20) + (F2 × 0.25) + (F3 × 0.20) + (F4 × 0.10) + (F5 × 0.10) + (F6 × 0.15) + bonus_F7

Si F6 no aplica:
SCORE = (F1 × 0.24) + (F2 × 0.29) + (F3 × 0.23) + (F4 × 0.12) + (F5 × 0.12) + bonus_F7

Veredicto

| Score | Veredicto | Acción | |-------|-----------|--------| | ≥7.5 | ADOPT 🟢 | Integrar con confianza. Monitorizar actualizaciones. | | 5.0–7.4 | EVALUATE 🟡 | Integrar con precauciones. Documentar riesgos aceptados. Revisar en 90 días. | | 3.0–4.9 | CAUTION 🟠 | Solo si no hay alternativa. Aislar. Auditoría profunda antes de producción. | | 1 año → CAUTION máximo

• Ejecución dinámica no sanitizada en MCP → AVOID automático

---

Entregable

Generar un informe HTML interactivo con:

1. Header: Nombre del repo, URL, fecha, veredicto con badge de color
2. Resumen ejecutivo: 3-5 frases con hallazgos clave
3. Radar chart: Las 7 dimensiones en gráfico radial (o 6 si F6 no aplica)
4. Detalle por fase: Tabla con métricas, valores encontrados, scoring
5. Hallazgos críticos: Lista de issues que requieren atención (si los hay)
6. Racionalizaciones rechazadas: Si durante el análisis se detectaron
7. Veredicto final: Score + veredicto + acción recomendada
8. Comparativa stack: ¿Qué herramienta actual cubre funcionalidad similar?

Guardar en el directorio de trabajo/output.

---

Cuándo usar

• Antes de integrar cualquier repo/librería/MCP/plugin/skill al stack
• Cuando un cliente pregunte sobre la seguridad de una herramienta
• Cuando evalúes una dependencia nueva para un proyecto
• Cuando el usuario comparta un enlace a GitHub preguntando si usarlo
• Para auditar MCPs o skills de terceros antes de instalarlos

Cuándo NO usar

• Para auditorías SEO de sitios web
• Para análisis de código propio (usar tu workflow de dev/test)
• Para crear skills nuevos (usar skill-creator)
• Para evaluar herramientas que no son open source / no tienen repo público

---

Referencias

Consultar bajo demanda:

• references/health-scoring.md — Tabla detallada de scoring por métrica de salud
• references/security-patterns.md — Checklist completo de patrones de seguridad
• references/supply-chain-signals.md — Framework de evaluación de supply chain

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Consultora-AMDT
• Source: Consultora-AMDT/claude-github-security-audit
• License: MIT
• Homepage: https://aunmasdificiltodavia.es

Install and usage instructions live in the source repository linked above.