Pentest Pipeline Template

Template público de GitHub Actions para escanear tu API o app en CI: secretos, dependencias, vulnerabilidades web y performance. Se enchufa desde cualquier repo con un uses: no hace falta clonar nada.

Quickstart

Creá .github/workflows/pentest.yml en tu repo:

name: Pentest
on:
  workflow_dispatch:        # botón "Run workflow"
  schedule:
    - cron: "0 3 * * 1"     # todos los lunes 03:00 UTC opcional

jobs:
  pentest:
    uses: codeaseguro/pipeline-template-pentesting/.github/workflows/pentest-template.yml@v1
    with:
      target_url: "https://staging.mi-api.example.com"        # tu app accesible por URL
      openapi_url: "https://staging.mi-api.example.com/docs-json"  # opcional (Swagger)
    secrets: inherit

Con eso ya corren, sin configurar nada más: Gitleaks, npm audit, Nuclei y ZAP.

flowchart LR
A["Tu repo\n(.github/workflows/pentest.yml)"] -->|"uses: @v1"| B["codeaseguro/pipeline-template-pentesting\npentest-template.yml"]
B --> C[Gitleaks]
B --> D[npm audit]
B --> E[Nuclei]
B --> F["ZAP baseline"]
B --> G["ZAP API scan"]
B --> H["business_logic\n(opt-in)"]
C & D & E & F & G & H --> I["Artifacts\n(reportes en la corrida)"]

Loading

Qué incluye

Job	Herramienta	Necesita	Funciona solo
gitleaks	Gitleaks	tu repo	sí
npm_audit	npm audit	package.json en tu repo	sí
nuclei	Nuclei	target_url	sí
zap_baseline	OWASP ZAP (pasivo)	target_url	sí
zap_api_scan	OWASP ZAP (activo)	openapi_url	sí
business_logic	script propio	scripts/business-logic-checks.sh en tu repo	opt-in

business_logic depende de un script específico de tu API (endpoints, roles). Copiá scripts/business-logic-checks.sh a tu proyecto y adaptá los endpoints. Si el archivo no está, el job avisa y se saltea (no rompe el build).

Inputs

Input	Default	Descripción
target_url	(requerido)	URL base a escanear
openapi_url	""	Spec OpenAPI/Swagger (vacío = se saltea ZAP API scan)
nuclei_tags	exposure,misconfiguration,cve	Familias de checks
nuclei_severity	medium,high,critical	Severidades a reportar
run_gitleaks / run_npm_audit / run_nuclei / run_zap_baseline / run_zap_api_scan	true	Prender/apagar cada scanner
run_business_logic	false	Prender el job con script propio
fail_on_findings	false	true = el job falla ante hallazgos · false = solo reporta (artifacts)
node_version	20	Node para npm audit
business_logic_script	scripts/business-logic-checks.sh	Ruta a tu script

Todos los reportes quedan como artifacts de la corrida (pestaña Actions → run → Artifacts).

Ejemplo más completo (staging efímero, business logic, k6): examples/caller-example.yml.

⚠️ Uso responsable

Escaneá solo objetivos que controlás (staging / entornos aislados). Nuclei y ZAP hacen tráfico agresivo: contra producción podés gatillar rate-limits o que el proveedor bloquee tu VPS. Ojo con endpoints que tocan la DB (ej: /health).

Versionado

Referenciá una ref estable en tu uses: — @v1 (recomendado), @main (último) o un @<SHA> (inmutable).

---

Apéndice: hacer lo mismo a mano (localmente)

Pasos para realizar pentesting a API REST

Requisitos

• Docker instalado localmente
• nuclei -> Scanner de vulnerabilidades webs (Nuclei es excelente: miles de checks CVE/misconfig.)
• OWSAP/ZAP -> Proxy / Interceptor, para interceptar, modificar y requetir requests. ZAP tiene scanners automaticos.

Importante Para hacer esta prueba se recomienda usar entornos aislados y no productivos, por ejemplo localmente. Si lo haces contra tu propia API productiva el servidor puede bloquearte por detectar scans agresivos y de esa forma terminar bloqueando la VPS que aloja tu API. En local podes reproducir errores, ver logs, restear base de datos.

Instalacion

brew install nuclei nuclei -update-templates # baja las ~9000 plantillas de detección

ZAP usamos la imagen oficial de Docker docker pull zaproxy/zap-stable

Nuclei escaneo automatico

Nuclei corre miles de checks (CVEs, misconfigs, headers, secretos expuestos) contra una URL:

• -u = objetivo · -tags = qué familias de checks · -stats = progreso.
• Primero le pasamos estos tags nuclei -u http://localhost:3000 -tags exposure,misconfiguration,cve -stats
• Despues podemos probar todo nuclei -u http://localhost:3000

Esto dara un reporte lo que se genere con severidad mediuim+ es a lo que tenemos que darle atención.

• Guardamos el reporte en formato .txt nuclei -u http://localhost:3000 -o nuclei-report.txt

ZAP (el escaneo web + proxy)

• Ejecutarlo en modo fast, dara un reporte HTML:

  zaproxy/zap-stable zap-baseline.py \
  -t http://host.docker.internal:3000 -r zap-report.html

• --network host = para que el contenedor vea tu localhost:3000.
• -r zap-report.html = genera el reporte en la carpeta actual.
• El baseline es pasivo (no ataca), ideal para arrancar sin riesgo.

Modo completo (API scan activo):

Aclaración: vale la pena tener OpenAPI de Swagger para la documentacíon de la API

docker run --rm -v $(pwd):/zap/wrk/:rw --network host \
  zaproxy/zap-stable zap-api-scan.py \
  -t http://host.docker.internal:3000/docs-json -f openapi -r zap-api-report.html

• El -f openapi le dice que lea la spec de tu Swagger para conocer todos los endpoints.

ZAP/Nuclei encuentran misconfigs, pero la lógica de negocio la testeás a mano.

Escanners Gitleaks - npm audit

• Gitleak Herramienta open source para validar secretos o credenciales expuestas.
• npm audit para escanear vulnerabilidades

Las pruebas de performance (k6) se movieron a su propio template: pipeline-template-test-performance.