leitwacht-agent

https://leitwacht.eu — offizielle Quelle: https://gitlab.com/leitwacht/leitwacht-agent. Issues, MRs und Diskussionen leben auf GitLab.

Pre-1.0. Die 0.x-Serie ist vor-stabil; Nebenversionen können Breaking Changes an APIs, Umgebungsvariablen-Namen, Helm-values.yaml-Schlüsseln und dem Regel-Datei-Schema mit sich bringen, bis 1.0 erscheint. Verwenden Sie in der Produktion feste Image-Digests (keine Floating-Tags). Siehe CHANGELOG.md für Upgrade-Hinweise.

Der Data-Plane-Agent für das leitwacht GitLab Runner Egress-Control-System. eBPF + nftables + ein DNS-Proxy im Network Namespace koppeln an jeden CI-Runner-Container an und erzwingen die Egress-Policy. CE (dieses Repository) liest seine Regeln aus einer lokalen YAML-Datei und ist vollständig eigenständig – kein Backend, keine Heimtelefonie, keine Registrierung.

Eine separat lizenzierte Enterprise Edition (gitlab.com/leitwacht/leitwacht) fügt eine verwaltete Control Plane hinzu (Regel-Erstellungs-UI, Multi-Tenancy, Audit, GitLab-Integration). Der EE-Agent importiert agentcore/ aus diesem Repository und ersetzt den YAML-Lader durch einen gRPC-Regelstrom.

Layout

agentcore/                   data-plane primitives (MPL-2.0)
  enforcer/                  eBPF + nftables + DNS proxy + LSM cred/proc_mem
  watcher/                   container-lifecycle event source (containerd, docker)
  handler/                   lifecycle handler — edition-neutral
  policy/                    ResolvedPolicy + Source interface + loader
  advisory/                  plain-Go advisory type + Sink interface
  violation/                 plain-Go violation reporting Sink interface
  wildcard/                  domain-pattern matching helpers
  version/                   build-version stamp (set via -ldflags)
  cmd/
    leitwacht-initc/          pod init container that gates entrypoints on agent attach

ce/                          Community Edition daemon (MPL-2.0)
  cmd/agent-ce/              the binary
  config/                    env-driven daemon settings
  ruleyaml/                  YAML rule loader + fsnotify hot-reload
  sinks/                     stdout NDJSON / Prometheus / webhook
  helm/agent-ce/             Helm chart
  SCHEMA.md                  YAML rule schema (v1)

examples/
  rules.yaml                 starter rule set

docs/
  EVENT_FLOW.md              watcher → handler → enforcer flow + tunables (with mermaid)

Container scope

leitwacht-agent überprüft nur Container, die das GitLab Runner Managed Label com.gitlab.gitlab-runner.managed=true tragen. Container ohne dieses Label – alles, was Sie von Hand hochfahren, Sidecars, Anwendungs-Workloads – werden vollständig ignoriert (keine Ereignisse, keine Durchsetzung, keine Verstöße). Dies ist beabsichtigt: leitwacht ist die Data Plane für den CI-Runner-Egress, und Nicht-Runner-Workloads sollten nicht unbemerkt abgefangen werden. Nicht-Runner-Anwendungsfälle liegen außerhalb des Umfangs von v0.1.0.

Bekannte Einschränkungen (v0.1.0)

• Nur IPv4. Die eBPF-Programme und der DNS-Proxy setzen auf IPv4-Verkehr durch; IPv6-Egress wird an der Netns-Grenze unabhängig von der Policy verworfen. CI-Jobs, die IPv6-Konnektivität benötigen, können leitwacht-Enforcement nicht nutzen, bis dies behoben ist.
• Nur Linux x86_64. arm64-Runner werden noch nicht unterstützt (CI liefert amd64-Images; arm64 folgt, sobald wir eBPF-Artefakte für diese Architektur haben).
• Nur GitLab Runner Workloads. Siehe „Container scope“ oben.

Quickstart

# 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"

Die vollständige Schema-Referenz für rules.yaml befindet sich in ce/SCHEMA.md.

Lizenz

agentcore/ und ce/ werden unter der Mozilla Public License 2.0 vertrieben – siehe LICENSE. MPL-2.0 ist eine Datei-Level-Copyleft-Lizenz: Sie dürfen diese Dateien in eigenen Produkten (kommerziell oder nicht) verwenden, modifizieren und weiterverteilen, aber alle Änderungen, die Sie an MPL-2.0-lizenzierten Dateien vornehmen, müssen unter derselben Lizenz verfügbar gemacht werden.

Das Enterprise Edition Backend auf gitlab.com/leitwacht/leitwacht wird unter einer anderen Lizenz vertrieben. Die beiden Repositorys werden vom selben Team gemeinsam entwickelt.

Mitwirken

Issues und Merge Requests im kanonischen GitLab-Repository (https://gitlab.com/leitwacht/leitwacht-agent). Sicherheitsprobleme sollten dem Prozess in SECURITY.md folgen. Workflow- und Stilnotizen finden Sie in CONTRIBUTING.md.

Bauen

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

Die eBPF-Objekte (*_bpfel.o) sind eingecheckt, da ihre Neuerstellung clang + Kernel-Header erfordert; CI-Builds verlassen sich auf die eingecheckten Artefakte. Um lokal auf Linux neu zu generieren:

go generate ./agentcore/enforcer/