Inicio rápido

De cero a ver un hallazgo corregido y verificado, en unos 15 minutos. Los pasos marcados opcional se pueden dejar para después.

1. Arrancar (5 min)

Necesitas Docker (Engine 24+ con Compose v2.24+), make y git. make doctor comprueba que todo está.

git clone --branch v0.12.2 https://github.com/Pitangus-Dev/pitangus.git
cd pitangus
make setup PREBUILT=1
make up

make setup PREBUILT=1 usa las imágenes publicadas y firmadas en lugar de construirlas (omítelo para construirlas desde el código). La primera vez las descarga junto con los motores, unos 800 MB: menos de un minuto con una conexión rápida, unos 2 minutos a 50 Mbps (medido desde cero: cerca de 1 minuto a 150 Mbps, 3 en un portátil con WSL2). Con una VPN o un proxy corporativo la primera descarga puede tardar mucho más: mira solucion-problemas.md. Al terminar muestra la URL (http://127.0.0.1:8766) y un código de configuración de un solo uso: con él creas el administrador en el panel. Si lo pierdes, make setup-code lo vuelve a mostrar.

Justo después, el panel te pide activar el segundo factor (TOTP) con tu app de autenticación: es obligatorio para los administradores (PITANGUS_REQUIRE_TOTP, ver configuracion.md) y no se abre nada más hasta que lo actives. Guarda los códigos de respaldo que te muestra.

El panel sigue el idioma de tu navegador; puedes cambiarlo cuando quieras desde la barra lateral o la pantalla de inicio de sesión. Los comentarios en PRs, los avisos, Jira, los informes y la salida de la CLI usan PITANGUS_DEFAULT_LOCALE (en por defecto, ver configuracion.md).

2. Verlo funcionar sin conectar nada (2 min)

make demo

Analiza de verdad, con los mismos motores del panel, los ejemplos vulnerables a propósito que trae el repositorio (código en siete lenguajes, dependencias con CVE, un secreto y un Dockerfile) e importa un modelo de amenazas de ejemplo. En el panel verás el activo «demo · ejemplos vulnerables»:

• Resumen: hallazgos por severidad, explotación activa (KEV) y lo que hay que atender primero.
• Hallazgos: despliega uno y mira Cómo corregirlo (el comando o el ejemplo de código). «Reverificar» funciona en tus repositorios.
• Amenazas: el diagrama, las amenazas y el informe PDF.

Con make demo IMAGE=nginx:1.21 también se analiza una imagen pública (Trivy + Grype, un par de minutos).

3. Conectar tus repositorios de GitHub (5 min)

En Integraciones → Proveedores de código, el panel te guía para crear la GitHub App de tu servidor con los permisos justos (lectura de código, comentarios y estados en PRs). Al final la instalas en los repositorios que quieras: mejor Only select repositories para empezar. Detalle en github-app.md.

Sin GitHub (GitLab, Bitbucket, Azure DevOps o una carpeta local): usa scan en la terminal o en CI.

4. Primer análisis y primera corrección

1. Nuevo análisis → Análisis de código, elige uno o varios repositorios (o una organización entera) y lanza.
2. En Hallazgos, empieza por lo marcado como KEV o crítico. Cada hallazgo trae Cómo corregirlo.
3. Aplica la corrección, súbela a la rama principal y pulsa Reverificar: al terminar el análisis te dice «Corregido ✓» o «Sigue presente».

Si decides no corregir algo, regístralo en el triage (riesgo aceptado o falso positivo) con su motivo y una fecha de caducidad: queda como evidencia y no vuelve a molestar.

5. Que trabaje solo (opcional, recomendado)

• Pull requests y rama principal: en Pull requests, un administrador activa la vigilancia de tus repositorios. Cada PR se revisa solo (solo cuenta lo que introduce) y, tras un merge, la rama principal se reanaliza.
• Avisos nuevos a diario: activos por defecto. Una vez al día se contrastan tus dependencias con los avisos publicados después del último análisis, sin conexión.
• Avisos a tu canal: en Integraciones → Avisos, añade Slack, Teams o un webhook para enterarte sin abrir el panel. Para que los mensajes enlacen al hallazgo, define PITANGUS_PUBLIC_URL.

6. Más adelante (opcional)

• Equipo: invita a más personas en Usuarios (rol miembro o administrador).
• Jira: en Integraciones, para convertir hallazgos en incidencias sin duplicados.
• Imágenes privadas: credenciales de solo lectura en Integraciones → Registros de contenedores.
• Auditorías: en Hallazgos, Más formatos → Evidencia para auditoría (SOC 2, ISO)… genera el PDF (o Informe de los seleccionados con los que marques).
• Actualizaciones: instalaste una versión fija, así que make update por sí solo se queda en ella. Cuando salga una nueva (Releases): git fetch --tags && git checkout v<nueva> && make update (instalacion.md).
• Desde otra máquina: ponlo detrás de HTTPS (ver el README); sin HTTPS fuera de 127.0.0.1 no arranca.

¿Algo no funciona? solucion-problemas.md o make doctor.