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

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: web_fetch del repo GitHub, GitHub API vía web_fetch.

Recopilar:

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.

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.

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

Override rules (anulan el scoring numérico)

• Sin licencia → AVOID automático
• AGPL/SSPL → AVOID automático (salvo uso interno sin SaaS)
• Secrets hardcodeados en el repo → AVOID automático
• Único maintainer + último commit >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.

Limitaciones

Declarar estas limitaciones al entregar el informe:

• No ejecuta código ni descubre vulnerabilidades desconocidas. No es análisis estático ni pentest. Analiza lo publicado: código, manifiestos, workflows, licencia, historial. Una puerta trasera escrita para parecer código normal no se detecta así.
• No sustituye revisión humana cuando el repo va a tocar datos sensibles. El score prioriza dónde mirar; no autoriza a no mirar.
• El score refleja el repo el día en que se midió. Recomendar re-ejecución antes de decisiones importantes.

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
• 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