README_ES.md

GitHub Advanced Security (GHAS) - Integración con DefectDojo

---

¡Hola developer 👋🏻! Este repositorio es una Prueba de Concepto (PoC) para integrar GitHub Advanced Security (GHAS) con DefectDojo. He intentado hacerlo lo más simple posible para que puedas adaptarlo fácilmente a tus necesidades.

📑 Tabla de Contenidos

• GitHub Advanced Security (GHAS) - Integración con DefectDojo
  • 📑 Tabla de Contenidos
  • ✨ Características
  • 🆕 Mejoras Recientes
  • 🛠️ Tecnologías
  • 📋 Requisitos Previos
  • 🚀 Instalación
    • Paso 1: Clonar este repositorio
    • Paso 2: Configurar DefectDojo
    • Paso 3: Crear Producto y Engagement en DefectDojo
    • Paso 4: Exponer DefectDojo con un túnel
    • Paso 5: Configurar Secrets en GitHub
    • Paso 6: Crear una GitHub App (Opcional)
  • 💻 Uso
    • Importar Alertas de Dependabot
    • Importar Alertas de Code Scanning
    • Importar Alertas de Secret Scanning
  • 📁 Estructura del Proyecto
  • 🌐 Sígueme en Mis Redes Sociales

✨ Características

• Integración completa con GHAS: Importa los tres tipos de alertas de GitHub Advanced Security a DefectDojo
• Workflows automatizados: GitHub Actions listos para usar
• Alertas de Dependabot: Importación usando el formato GitHub Vulnerability Scan
• Alertas de Code Scanning: Importación de resultados de CodeQL usando formato SARIF
• Alertas de Secret Scanning: Creación de hallazgos directamente vía API de DefectDojo
• Aplicación Flask de ejemplo: Incluye una aplicación Flask vulnerable para pruebas

🆕 Mejoras Recientes

• Ejecución manual de workflows: Todos los workflows ahora soportan workflow_dispatch para ejecución manual
• Parámetros configurables:
  • engagement_id para los workflows de CodeQL y Dependabot (por defecto: 1)
  • test_id para el workflow de Secret Scanning (por defecto: 1)
• GitHub Actions actualizadas:
  • actions/checkout → v6
  • actions/upload-artifact → v7
  • github/codeql-action → v4

🛠️ Tecnologías

• Python 3.8+ - Lenguaje de programación principal
• Flask - Framework web para la aplicación vulnerable de ejemplo
• GitHub Actions - Automatización CI/CD
• GitHub Advanced Security - Escaneo de seguridad (Dependabot, CodeQL, Secret Scanning)
• DefectDojo - Plataforma de gestión de vulnerabilidades
• Docker - Soporte de contenedores

📋 Requisitos Previos

• Git
• Docker y Docker Compose
• GitHub CLI (opcional)
• Un repositorio de GitHub con GHAS habilitado
• Una GitHub App con permiso read:security_events (para alertas de secrets y dependabot)

🚀 Instalación

Paso 1: Clonar este repositorio

git clone https://github.com/0GiS0/import-ghas-to-defectdojo.git
cd import-ghas-to-defectdojo

Paso 2: Configurar DefectDojo

Clona y ejecuta DefectDojo localmente:

git clone https://github.com/DefectDojo/django-DefectDojo.git
cd django-DefectDojo
docker compose up -d
docker compose logs initializer | grep "Admin password:"

Después puedes acceder a DefectDojo en http://localhost:8080 con el usuario admin y la contraseña que aparece en los logs.

Paso 3: Crear Producto y Engagement en DefectDojo

Necesitas un Product y un Engagement creados en DefectDojo. Puedes crearlos usando la API. Consulta el archivo requests/create_defectDojo_artifacts.http para ver ejemplos.

Paso 4: Exponer DefectDojo con un túnel

Usa un servicio de túneles como pinggy.io o ngrok:

# Usando pinggy.io
ssh -p 443 -R0:localhost:8080 qr@a.pinggy.io

# Usando ngrok
ngrok http 8080

Paso 5: Configurar Secrets en GitHub

Añade los siguientes secrets a tu repositorio de GitHub:

Secret	Descripción
DEFECTDOJO_URL	La URL expuesta por el túnel
DEFECTDOJO_TOKEN	Token de API de DefectDojo (créalo en tu perfil de usuario)

Puedes hacerlo de forma sencilla usando la GitHub CLI:

gh secret set DEFECTDOJO_URL -b "http://bshzi-95-61-255-152.a.free.pinggy.link"
gh secret set DEFECTDOJO_TOKEN -b "3060b62a0d94b990d4e2c0c9acbae96eae413b4e"

Para generar el token de API en DefectDojo, ve a tu perfil de usuario (en la esquina superior derecha) y verás tu Api Key. Cópiala y úsala como valor para DEFECTDOJO_TOKEN.

Paso 6: Crear una GitHub App (Opcional)

Para obtener alertas de secrets y dependabot, crea una GitHub App con el permiso read:security_events. Sigue la documentación oficial.

🎉 ¡Felicidades! ¡Ya estás listo para empezar!

💻 Uso

Importar Alertas de Dependabot

Las alertas de Dependabot se importan usando el formato GitHub Vulnerability Scan (disponible desde DefectDojo 2.4.0).

El workflow .github/workflows/send_dependabot_security_alerts.yml obtiene las alertas vía API GraphQL y las envía a DefectDojo:

curl -X POST "$DEFECTDOJO_URL/import-scan/" \
  -H "Authorization: Token $DEFECTDOJO_TOKEN" \
  -F 'product_name=TU_NOMBRE_DE_PRODUCTO' \
  -F 'engagement=ID_DEL_ENGAGEMENT' \
  -F 'scan_type=Github Vulnerability Scan' \
  -F 'file=@dependabot-security-alerts.json'

Importar Alertas de Code Scanning

Las alertas de Code Scanning (CodeQL) se importan usando el formato SARIF.

El workflow .github/workflows/codeql_and_defectdojo.yml ejecuta el análisis de CodeQL y sube los resultados:

curl -X POST "$DEFECTDOJO_URL/import-scan/" \
  -H "Authorization: Token $DEFECTDOJO_TOKEN" \
  -F 'product_name=TU_NOMBRE_DE_PRODUCTO' \
  -F 'engagement=ID_DEL_ENGAGEMENT' \
  -F 'scan_type=SARIF' \
  -F 'file=@results/python.sarif'

Importar Alertas de Secret Scanning

Las alertas de Secret Scanning se crean directamente como hallazgos (findings) vía la API de DefectDojo.

El workflow .github/workflows/send_secrets_to_defectdojo.yml:

1. Obtiene los secrets desde la API REST de GitHub
2. Transforma los datos al formato de DefectDojo usando jq
3. Crea los hallazgos vía POST a /api/v2/findings/

# Obtener secrets desde GitHub
curl -H "Authorization: Bearer $TOKEN" \
  https://api.github.com/repos/OWNER/REPO/secret-scanning/alerts > secrets.json

# Transformar y enviar a DefectDojo
curl -X POST "$DEFECTDOJO_URL/findings/" \
  -H "Authorization: Token $DEFECTDOJO_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$FINDING_DATA"

📁 Estructura del Proyecto

import-ghas-to-defectdojo/
├── .github/
│   ├── dependabot.yml
│   └── workflows/
│       ├── codeql_and_defectdojo.yml      # CodeQL + subida SARIF
│       ├── get_alerts.yml                  # Obtener alertas GHAS
│       ├── send_dependabot_security_alerts.yml
│       └── send_secrets_to_defectdojo.yml
├── flask_webgoat/                          # App Flask vulnerable de ejemplo
│   ├── actions.py
│   ├── auth.py
│   ├── status.py
│   ├── ui.py
│   ├── users.py
│   └── templates/
├── requests/                               # Ejemplos de peticiones HTTP
│   ├── create_defectDojo_artifacts.http
│   ├── defectDojo.http
│   ├── ghas_alerts_requests.http
│   └── send_*.http
├── app.py
├── Dockerfile
├── requirements.txt
└── README.md

🌐 Sígueme en Mis Redes Sociales

Si te ha resultado útil este proyecto, no olvides seguirme en mis redes sociales:

---

¡Happy hacking! 🐱‍👤