leitwacht-agent

https://leitwacht.eu — source de vérité : https://gitlab.com/leitwacht/leitwacht-agent. Les issues, les MR et les discussions se trouvent sur GitLab.

Pré-1.0. La série 0.x est pré-stable ; les versions mineures peuvent apporter des changements cassants aux API, aux noms de variables d'environnement, aux clés values.yaml de Helm et au schéma du fichier de règles jusqu'à la version 1.0. Épinglez les digests d'image (pas les tags flottants) en production. Voir CHANGELOG.md pour les notes de mise à jour.

L'agent du plan de données pour le système de contrôle de sortie du GitLab Runner leitwacht. eBPF + nftables + un proxy DNS in-netns s'attachent à chaque conteneur de runner CI et appliquent la politique de sortie. CE (ce dépôt) lit ses règles à partir d'un fichier YAML local et est entièrement autonome — pas de backend, pas de rappel au domicile, pas d'enrôlement.

Une édition Entreprise sous licence séparée (gitlab.com/leitwacht/leitwacht) ajoute un plan de contrôle géré (interface de création de règles, multi-tenant, audit, intégration GitLab). L'agent EE importe agentcore/ de ce dépôt et remplace le chargeur YAML par un flux de règles gRPC.

Disposition

agentcore/                   primitives du plan de données (MPL-2.0)
  enforcer/                  eBPF + nftables + proxy DNS + LSM cred/proc_mem
  watcher/                   source d'événements du cycle de vie des conteneurs (containerd, docker)
  handler/                   gestionnaire de cycle de vie — neutre pour l'édition
  policy/                    ResolvedPolicy + interface Source + chargeur
  advisory/                  type advisory simple en Go + interface Sink
  violation/                 interface Sink de signalement de violation simple en Go
  wildcard/                  helpers de correspondance de motifs de domaine
  version/                   estampille de version de construction (définie via -ldflags)
  cmd/
    leitwacht-initc/          conteneur init du pod qui ferme les points d'entrée lors de l'attachement de l'agent

ce/                          Démon de l'édition communautaire (MPL-2.0)
  cmd/agent-ce/              le binaire
  config/                    paramètres du démon pilotés par l'environnement
  ruleyaml/                  chargeur de règles YAML + rechargement à chaud via fsnotify
  sinks/                     sortie NDJSON / Prometheus / webhook
  helm/agent-ce/              Chart Helm
  SCHEMA.md                  schéma des règles YAML (v1)

examples/
  rules.yaml                 ensemble de règles de démarrage

docs/
  EVENT_FLOW.md              flux watcher → handler → enforcer + réglables (avec mermaid)

Périmètre des conteneurs

leitwacht-agent inspecte uniquement les conteneurs portant le label géré du GitLab Runner com.gitlab.gitlab-runner.managed=true. Les conteneurs sans ce label — tout ce que vous lancez à la main, sidecars, charges de travail applicatives — sont ignorés entièrement (pas d'événements, pas d'application, pas de violations). Ceci est délibéré : leitwacht est le plan de données pour la sortie des CI runner, et les charges de travail non-runner ne doivent pas être interceptées silencieusement. Les cas d'utilisation non-Runner sont hors du périmètre pour v0.1.0.

Limitations connues (v0.1.0)

• IPv4 seulement. Les programmes eBPF et le proxy DNS appliquent le trafic IPv4 ; la sortie IPv6 est abandonnée à la limite du netns quelle que soit la politique. Les jobs CI qui nécessitent une connectivité IPv6 ne peuvent pas utiliser l'application de leitwacht jusqu'à ce que cela soit traité.
• Linux x86_64 seulement. Les runners arm64 ne sont pas encore supportés (CI fournit des images amd64 ; arm64 suivra une fois que nous aurons des artefacts eBPF pour cette architecture).
• Charges de travail GitLab Runner seulement. Voir "Périmètre des conteneurs" ci-dessus.

Démarrage rapide

# 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 référence complète du schéma pour rules.yaml se trouve dans ce/SCHEMA.md.

Licence

agentcore/ et ce/ sont distribués sous la licence Mozilla Public License 2.0 — voir LICENSE. MPL-2.0 est une licence copyleft au niveau des fichiers : vous pouvez utiliser, modifier et redistribuer ces fichiers dans vos propres produits (commerciaux ou autres), mais toute modification que vous apportez aux fichiers sous licence MPL-2.0 doit être mise à disposition sous la même licence.

Le backend de l'édition Entreprise sur gitlab.com/leitwacht/leitwacht est distribué sous une licence différente. Les deux dépôts sont co-développés par la même équipe.

Contribution

Les issues et les merge requests sur le dépôt GitLab canonique (https://gitlab.com/leitwacht/leitwacht-agent). Les problèmes de sécurité doivent suivre le processus dans SECURITY.md. Les notes de workflow et de style sont dans CONTRIBUTING.md.

Compilation

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

Les objets eBPF (*_bpfel.o) sont commités car leur régénération nécessite clang + les en-têtes du noyau ; les builds CI s'appuient sur les artefacts commités. Pour régénérer localement sur Linux :

go generate ./agentcore/enforcer/