# DevSecOps

Fase 2 del lab: integrar tooling de seguridad al pipeline de Gitea
Actions, empezando por un solo repo de referencia — el frontend de ARI
Shopping (`workloads/ecommerce`, `.gitea/workflows/build.yaml`) — antes
de replicarlo a `commerce-backend` y `docs-portal`.

Cinco herramientas, cada una respondiendo una pregunta distinta:

| Herramienta | Pregunta que responde | Modo |
|---|---|---|
| [Gitleaks](gitleaks.md) | ¿Hay un secreto commiteado? | **Bloquea** |
| [Trivy — imagen](trivy.md) | ¿La imagen tiene una CVE conocida? | CRITICAL **bloquea**, HIGH informa |
| [Trivy — IaC](trivy.md) | ¿El manifiesto de Kubernetes es inseguro? | Informa |
| [Semgrep (SAST)](sast.md) | ¿El código tiene un patrón inseguro conocido? | Informa (auditoría) |
| [Syft (SBOM)](sbom.md) | ¿Qué paquetes exactos quedaron en la imagen? | Informa (inventario) |
| [Cosign](cosign.md) | ¿Esta imagen es exactamente la que armó el pipeline? | **Bloquea** (smoke test) |

## El pipeline completo

```mermaid
flowchart TD
    subgraph J1["job: gitleaks (push + pull_request)"]
        A1[checkout] --> A2["gitleaks detect --no-git"]
    end

    A2 -- "secreto encontrado" --> XA["❌ pipeline detenido<br/>build nunca arranca"]
    A2 -- "limpio" --> B0

    subgraph J2["job: build (solo push a main, needs: gitleaks)"]
        B0[checkout + validaciones de código] --> B1["Trivy IaC<br/>(frontend.yaml)"]
        B1 -.informa.-> B2["Semgrep SAST<br/>(audit mode)"]
        B2 -.informa.-> B3[login registry]
        B3 --> B4["docker build<br/>(push: false, load: true)"]
        B4 --> B5["Trivy imagen<br/>CRITICAL"]
        B5 -- "CRITICAL con fix" --> XB["❌ detenido<br/>no se sube la imagen"]
        B5 -- "sin CRITICAL" --> B6["Trivy imagen<br/>HIGH (informa)"]
        B6 --> B7["Syft → SBOM<br/>(CycloneDX + SPDX)"]
        B7 --> B8["docker push"]
        B8 --> B9["cosign sign"]
        B9 --> B10["cosign verify<br/>(smoke test)"]
        B10 -- "firma inválida" --> XC["❌ detenido"]
        B10 -- "firma válida" --> B11["actualizar frontend.yaml<br/>(GitOps, Argo CD sincroniza)"]
    end
```

## Por qué este orden

- **Gitleaks corre en un job aparte, antes que todo lo demás** — incluso
  antes que el checkout completo del job de build. Si hay un secreto,
  no tiene sentido gastar minutos de build en un commit que hay que
  rechazar igual. Es el único check que corre también en `pull_request`,
  no solo en push a `main`.
- **Trivy IaC y Semgrep corren antes del build de Docker.** Ninguno de
  los dos necesita la imagen construida — analizan manifiestos y código
  fuente respectivamente — así que si algo llamativo apareciera ahí, se
  sabe temprano, sin esperar el build (que es el paso más lento del
  pipeline).
- **Trivy imagen corre después del build pero antes del push.** Por eso
  el build usa `push: false, load: true`: la imagen queda en el daemon
  local del runner, escaneable, pero no sale hacia el registry hasta
  pasar el gate de CRITICAL.
- **Syft (SBOM) corre sobre la imagen ya validada**, antes del push —
  documenta exactamente lo que se está por publicar.
- **Cosign firma después del push exitoso** (no tiene sentido firmar
  algo que no llegó al registry) y se verifica en el mismo pipeline como
  smoke test.

## Qué pasa si cada uno falla

| Si falla... | El pipeline... |
|---|---|
| Gitleaks | Se detiene ahí mismo. El job `build` nunca arranca (`needs: gitleaks`). Nada se construye. |
| Trivy IaC | No se detiene — el hallazgo queda en el log, informativo. |
| Semgrep | No se detiene — mismo criterio: primera vuelta en modo auditoría. |
| Trivy imagen (CRITICAL) | Se detiene después del build, antes del push. La imagen con la CVE nunca llega al registry. |
| Trivy imagen (HIGH) | No se detiene — se reporta para revisar en conjunto. |
| Syft | Si el propio comando falla (no si "encuentra algo" — un SBOM no tiene hallazgos que bloqueen), el pipeline se detiene por error real de la herramienta. |
| Cosign sign/verify | Se detiene. Si la imagen se firmó pero no verifica, algo está mal con las llaves o con la imagen — no se continúa con la promoción GitOps. |

## Qué falta después de esta primera vuelta

- Revisar en conjunto los hallazgos de Trivy IaC y Semgrep (hoy
  informativos) y decidir cuáles pasan a bloquear.
- Decidir si Trivy imagen sube el umbral de bloqueo a HIGH una vez que
  el backlog de CVEs conocidas esté bajo control.
- Admission controller en el cluster que verifique la firma de Cosign
  antes de dejar correr un Pod (ver [cosign.md](cosign.md)) — hoy la
  verificación es solo un smoke test dentro del propio pipeline.
- Replicar este mismo patrón a `commerce-backend` (Medusa) y
  `docs-portal`, adaptando lo que corresponda a cada stack.