leitwacht-agent

https://leitwacht.eu — fuente de verdad: https://gitlab.com/leitwacht/leitwacht-agent. Issues, MRs, y discusiones residen en GitLab.

Pre-1.0. La serie 0.x es preestable; las versiones menores pueden incluir cambios disruptivos en APIs, nombres de variables de entorno, claves de values.yaml de Helm y el esquema de archivos de reglas hasta que 1.0 se publique. Fija los digest de imagen (no etiquetas flotantes) en producción. Consulta CHANGELOG.md para notas de actualización.

El agente del plano de datos para el sistema de control de egreso de GitLab Runner leitwacht. eBPF + nftables + un proxy DNS dentro del netns se adjuntan a cada contenedor de runner de CI y aplican la política de egreso. CE (este repositorio) lee sus reglas de un archivo YAML local y es completamente independiente — sin backend, sin telemetría, sin registro.

Una Edición Enterprise con licencia separada (gitlab.com/leitwacht/leitwacht) añade un plano de control gestionado (UI de creación de reglas, multiinquilino, auditoría, integración con GitLab). El agente EE importa agentcore/ de este repositorio y reemplaza el cargador de YAML con un flujo de reglas gRPC.

Layout

agentcore/                   primitivas del plano de datos (MPL-2.0)
  enforcer/                  eBPF + nftables + proxy DNS + LSM cred/proc_mem
  watcher/                   fuente de eventos del ciclo de vida del contenedor (containerd, docker)
  handler/                   manejador del ciclo de vida — neutral a la edición
  policy/                    ResolvedPolicy + interfaz Source + cargador
  advisory/                  tipo advisory en Go puro + interfaz Sink
  violation/                 interfaz Sink de reporte de violaciones en Go puro
  wildcard/                  ayudantes de coincidencia de patrones de dominio
  version/                   sello de versión de compilación (se establece mediante -ldflags)
  cmd/
    leitwacht-initc/          contenedor init del pod que bloquea puntos de entrada hasta que el agente se adjunte

ce/                          Daemon de la Community Edition (MPL-2.0)
  cmd/agent-ce/              el binario
  config/                    ajustes del daemon impulsados por variables de entorno
  ruleyaml/                  cargador de reglas YAML + recarga en caliente con fsnotify
  sinks/                     stdout NDJSON / Prometheus / webhook
  helm/agent-ce/             Chart de Helm
  SCHEMA.md                  esquema de archivo de reglas YAML (v1)

examples/
  rules.yaml                 conjunto de reglas inicial

docs/
  EVENT_FLOW.md              flujo watcher → handler → enforcer + parámetros ajustables (con mermaid)

Alcance del contenedor

leitwacht-agent solo inspecciona contenedores que portan la etiqueta gestionada de GitLab Runner com.gitlab.gitlab-runner.managed=true. Los contenedores sin esta etiqueta — cualquier cosa que levantes manualmente, sidecars, cargas de trabajo de aplicación — se ignoran por completo (sin eventos, sin aplicación, sin violaciones). Esto es deliberado: leitwacht es el plano de datos para el egreso de runner de CI, y las cargas de trabajo que no son runner no deben ser interceptadas silenciosamente. Los casos de uso que no son Runner están fuera del alcance de v0.1.0.

Limitaciones conocidas (v0.1.0)

Solo IPv4. Los programas eBPF y el proxy DNS aplican en tráfico IPv4; el egreso IPv6 se descarta en el límite del netns independientemente de la política. Los trabajos de CI que requieran conectividad IPv6 no pueden usar la aplicación de leitwacht hasta que esto se solucione.
Solo Linux x86_64. Los runners arm64 aún no son compatibles (CI envía imágenes amd64; arm64 llegará una vez que tengamos artefactos eBPF para esa arquitectura).
Solo cargas de trabajo de GitLab Runner. Ver "Alcance del contenedor" arriba.

Inicio rápido

# Build (CGO_ENABLED=0 lets non-Linux hosts cross-compile cleanly).
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build ./...

# Container image
docker build -f Dockerfile.agent-ce -t leitwacht/agent-ce:dev .

# Helm install (Kubernetes). dnsUpstream is required — point it at your
# cluster DNS resolver, not a public one, so internal services keep
# resolving and queries don't leak.
KUBE_DNS_IP=$(kubectl -n kube-system get svc kube-dns -o jsonpath='{.spec.clusterIP}')
helm install leitwacht-ce ./ce/helm/agent-ce \
  -n leitwacht --create-namespace \
  --set-file rules=examples/rules.yaml \
  --set "dnsUpstream=${KUBE_DNS_IP}:53"

La referencia completa del esquema para rules.yaml se encuentra en ce/SCHEMA.md.

Licencia

agentcore/ y ce/ se distribuyen bajo la Licencia Pública de Mozilla 2.0 — consulta LICENSE. MPL-2.0 es una licencia copyleft a nivel de archivo: puedes usar, modificar y redistribuir estos archivos en tus propios productos (comerciales o no), pero cualquier cambio que realices en archivos con licencia MPL-2.0 debe estar disponible bajo la misma licencia.

El backend de la Edición Enterprise en gitlab.com/leitwacht/leitwacht se distribuye bajo una licencia diferente. Los dos repositorios son co-desarrollados por el mismo equipo.

Contribuir

Los issues y merge requests en el repositorio canónico de GitLab (https://gitlab.com/leitwacht/leitwacht-agent). Los problemas de seguridad deben seguir el proceso en SECURITY.md. Las notas sobre flujo de trabajo y estilo están en CONTRIBUTING.md.

Compilación

Solo Linux (eBPF + nftables): GOOS=linux GOARCH=amd64 go build ./...

Los objetos eBPF (*_bpfel.o) están confirmados porque regenerarlos requiere clang + cabeceras del kernel; las compilaciones CI dependen de los artefactos confirmados. Para regenerar localmente en Linux:

go generate ./agentcore/enforcer/

LeitWacht Agent v0.9.0

Categorías