Reticulum: Escáner de Seguridad Avanzado para Infraestructura en la Nube

Actualización (15 oct 2026): artículo reescrito para Reticulum v2.0.0, publicada el 2 de julio de 2026, que reimplementa la herramienta en Rust. La versión anterior describía una implementación previa e incluía pip install reticulum, que no funciona: Reticulum no está publicado en PyPI. Todo lo que sigue sale del README, la documentación y la release v2.0.0 del repositorio.

Reticulum es un proyecto open source de Plexicus, con licencia MIT, que mantengo yo. A pesar del título, no es un escáner: no busca vulnerabilidades. Toma lo que ya han encontrado Trivy, Semgrep o cualquier herramienta que genere SARIF y recalcula la prioridad de cada hallazgo según cómo está desplegado el servicio afectado: si se llega a él desde internet, si corre con privilegios, si tiene capacidades peligrosas o una identidad en la nube.

El problema: la severidad no sabe dónde corre el código

Un escáner puntúa el paquete o el patrón de código, no el despliegue. El mismo CVE recibe la misma severidad en una API pública que en un worker interno sin Ingress. El README lo resume así: una vulnerabilidad MEDIUM en un servicio de autenticación público y privilegiado puede ser crítica, y una HIGH en un worker interno y aislado puede esperar.

La documentación de puntuación lo ilustra con un caso que se reproduce con los fixtures del repositorio. CVE-2023-37920 (certifi) tiene severidad 9.8, es decir, una puntuación base de 98:

ServicioContexto detectadoCálculoResultado
admin-apiIngress (×1,3), LoadBalancer (×1,3), privilegiado (+20), token de service account montado (+5)98 × 1,3 × 1,3 + 25 = 190,6, recortado a 100100, P0_BLEEDING
internal-workerSolo ClusterIP (×0,5)98 × 0,549, P3_MEDIUM

Mismo CVE, 51 puntos de diferencia.

Cómo funciona

Reticulum procesa el repositorio en tres fases (arquitectura).

1. Descubrimiento. Cada Dockerfile (también Dockerfile.<nombre> y <nombre>.Dockerfile) define un servicio, que es la unidad a la que se asignan los hallazgos. Además lee charts de Helm (Chart.yaml y las variantes de values: values.yaml, values-*.yaml, prod.yaml…), manifiestos de Kubernetes sin Helm (Deployment, StatefulSet, DaemonSet, ReplicaSet, Job, CronJob, Pod) y ficheros docker-compose. Después enlaza cada servicio con su unidad de configuración por nombre, por directorio o porque el values.yaml menciona el servicio (fuentes).

2. Exposición. Un motor de reglas en YAML evalúa los values de Helm, los metadatos del chart, los manifiestos y los servicios de Compose, y construye un perfil de riesgo por unidad con cinco indicadores: isPublic, isPrivileged, hasDangerousCaps, hasInternetEgress y mountServiceToken. En los manifiestos de Kubernetes no se limita a buscar cadenas: resuelve los selectores de etiquetas y las referencias a backends para trazar la ruta completa. Esta es la salida real sobre el fixture tests/monorepo-08:

Ingress/web-ingress → Service/web-svc → Deployment/web-frontend
Service/postgres-svc (LoadBalancer) → StatefulSet/postgres-db
NetworkPolicy/batch-egress egress 0.0.0.0/0 ← Deployment/internal-batch

En Compose, un puerto publicado como "8080:80" cuenta como público; uno ligado a 127.0.0.1 no.

3. Puntuación. La severidad base de cada hallazgo sale de properties.security-severity del SARIF (0–10) o, si no está, del nivel de la regla o del resultado; se multiplica por 10. Sobre esa base se aplican los multiplicadores del perfil (exposición), luego las sumas (privilegios, capacidades, IAM), se restan 10 puntos si no hay versión corregida (el hallazgo es menos accionable, no menos real) y se recorta a 0–100 (cálculo completo).

PrioridadPuntuaciónSignificado según la documentación
P0_BLEEDING90–100Exposición pública crítica
P1_CRITICAL70–89Riesgo alto
P2_HIGH50–69Riesgo moderado
P3_MEDIUM30–49Interno o mitigado
P4_LOW0–29Informativo

Instalación

La release v2.0.0 publica binarios para Linux y macOS (amd64 y arm64), cada uno con su fichero .sha256 y con las reglas por defecto incluidas. En Linux amd64:

PKG=reticulum-v2.0.0-linux-amd64
curl -fsSLO "https://github.com/plexicus/reticulum/releases/download/v2.0.0/${PKG}.tar.gz"
curl -fsSLO "https://github.com/plexicus/reticulum/releases/download/v2.0.0/${PKG}.tar.gz.sha256"
sha256sum -c "${PKG}.tar.gz.sha256"
tar -xzf "${PKG}.tar.gz"
"./${PKG}/reticulum" --help

En macOS, cambia el sufijo a darwin-arm64 o darwin-amd64 y verifica con shasum -a 256 -c.

Para compilarlo desde el código necesitas la toolchain estable de Rust; el README también describe cómo construir la imagen Docker:

git clone --branch v2.0.0 --depth 1 https://github.com/plexicus/reticulum.git
cd reticulum
cargo build --release          # binario en target/release/reticulum
docker build -t reticulum .    # imagen con las reglas en /app/rules

Reticulum carga las reglas de ./rules o, si no existe, del directorio rules junto al binario. Con --rules <dir> le indicas otra ruta.

Primer análisis

Reticulum necesita un SARIF de entrada. Con Trivy en modo filesystem:

trivy fs --format sarif --output trivy.sarif .
reticulum -p . -s trivy.sarif -o report.json \
  --sarif-output enriched.sarif --graph exposure.mmd

Con la imagen Docker, monta el repositorio en /data:

docker run --rm -v "$PWD:/data" reticulum \
  -p /data -s /data/trivy.sarif -o /data/report.json

Si solo quieres el mapa de exposición, sin hallazgos, usa --scan-only:

reticulum -p . --scan-only -o exposure.json --graph exposure.mmd

Cada ejecución puede generar cuatro salidas:

  • La consola, con cada hallazgo, su puntuación original, la de Reticulum y las reglas que la han cambiado.
  • Un informe JSON (-o): por servicio, el perfil de riesgo con exposurePaths y los hallazgos con baseScore, reticulumScore y priority.
  • El SARIF enriquecido (--sarif-output): el SARIF original con properties.reticulum en cada resultado (score, priority, serviceId, exposure), de modo que GitHub code scanning u otros consumidores de SARIF reciben el contexto.
  • Un diagrama Mermaid (--graph) con la superficie de exposición, que se puede pegar en un README o en un PR.

Para ver el ejemplo de la tabla anterior, desde la raíz del repositorio clonado:

./target/release/reticulum -p tests/monorepo-06 -s tests/fixtures/synthetic-trivy.sarif -o report.json
./target/release/reticulum -p tests/monorepo-08 --scan-only --graph exposure.mmd

Reglas propias

Las reglas son ficheros YAML en rules/, cargados en este orden: exposure/, security/, scoring/, manifest/ y, al final, custom/. Cada regla indica dónde mira (target: values, chart_metadata, manifest o finding), qué condiciones deben cumplirse y qué hace cuando se cumplen (referencia del DSL). Este ejemplo del recetario sube la puntuación de lo que es público y privilegiado a la vez:

id: "custom-crown-jewel"
target: "values"
match:
  - key: "ingress.enabled"
    op: "eq"
    value: true
  - key: "securityContext.privileged"
    op: "eq"
    value: true
action:
  risk_profile:
    score_boost: 30
  tags: ["crown-jewel"]

Las reglas finding sirven para aceptar riesgos de forma revisable, en el propio repositorio. Esta suprime un CVE concreto en un paquete concreto:

id: "accept-CVE-2023-4863-on-thumbnailer"
target: "finding"
match:
  - key: "cve_id"
    op: "eq"
    value: "CVE-2023-4863"
  - key: "package_name"
    op: "eq"
    value: "libwebp"
action:
  finding:
    suppress: true

Una regla con errores no detiene la ejecución: el motor muestra un aviso y sigue con las demás.

Integración en CI

La documentación de integraciones incluye un flujo de GitHub Actions. Esta versión instala el binario de la release con el hash fijado en el propio workflow, fija la action de terceros por SHA (el motivo está en el artículo sobre secuestro de pipelines), sube el SARIF enriquecido a code scanning y falla si queda algún hallazgo P0 o P1:

name: contextual-security
on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  security-events: write   # necesario para subir SARIF
  # actions: read          # solo en repositorios privados

jobs:
  reticulum:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Trivy (filesystem)
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          scan-type: fs
          format: sarif
          output: trivy.sarif

      - name: Instalar Reticulum v2.0.0
        run: |
          cd "$RUNNER_TEMP"
          PKG=reticulum-v2.0.0-linux-amd64
          curl -fsSLO "https://github.com/plexicus/reticulum/releases/download/v2.0.0/${PKG}.tar.gz"
          echo "289da9b2688e7c78eb7482845836504a792cec383c97355cbbb637bfd9d858c6  ${PKG}.tar.gz" | sha256sum -c -
          tar -xzf "${PKG}.tar.gz"
          echo "RETICULUM_HOME=$RUNNER_TEMP/${PKG}" >> "$GITHUB_ENV"

      - name: Priorizar
        run: |
          test -s trivy.sarif
          "$RETICULUM_HOME/reticulum" --rules "$RETICULUM_HOME/rules" \
            -p . -s trivy.sarif -o report.json \
            --sarif-output enriched.sarif --graph exposure.mmd

      - name: Subir a code scanning
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: enriched.sarif

      - name: Fallar si hay P0 o P1
        run: |
          jq -e '[.services[].findings[]? | select(.priority | test("P0|P1"))] | length == 0' \
            report.json || { echo "Hay hallazgos P0/P1"; exit 1; }

El test -s trivy.sarif no es decorativo: en v2.0.0, si el SARIF no existe, Reticulum termina con código 0 y un informe sin hallazgos, así que la puerta pasaría sin haber evaluado nada. El --rules explícito evita que cargue un directorio rules/ que tu repositorio pueda tener para otra herramienta. Si escribes reglas propias, cópialas en $RETICULUM_HOME/rules/custom/ antes de ese paso.

Lo que no cubre

  • No encuentra vulnerabilidades. Reordena las que trae el SARIF; lo que el escáner no ve, Reticulum tampoco.
  • Trabaja con la configuración declarada en el repositorio, no con el estado del clúster. No renderiza plantillas de Helm: analiza los ficheros de values. En v2.0.0 evalúa todas las variantes a la vez, de modo que algo activado solo en values-dev.yaml también cuenta para producción. La rama master ya tiene --env para elegir un entorno, pero todavía no está en una release.
  • Fuentes no soportadas: Kustomize, Terraform y CloudFormation aparecen en la hoja de ruta como fuentes en estudio; v2.0.0 no las lee.
  • Hallazgos sin servicio. En v2.0.0, un resultado cuya ruta no cae dentro de ningún servicio conocido se descarta sin aviso. El commit c7b7ae0 de master lo cuenta en el informe y hace que un SARIF inexistente termine con error; tampoco está en una release.
  • Las puntuaciones son heurísticas. Los multiplicadores y las sumas son valores por defecto que puedes cambiar; un P4 significa “después”, no “seguro”. El propio README pide validar los hallazgos.

Referencias

Blog

¿Hablamos de seguridad?

Charlas, prensa o colaboraciones: escríbeme.