leitwacht-agent

https://leitwacht.eu — fonte di verità: https://gitlab.com/leitwacht/leitwacht-agent. Issue, MR e discussioni risiedono su GitLab.

Pre-1.0. La serie 0.x è pre-stabile; le release minori possono introdurre modifiche sostanziali a API, nomi di variabili d'ambiente, chiavi di values.yaml di Helm e schema dei file di regole fino al rilascio della 1.0. In produzione, fissate i digest delle immagini (non tag volatili). Consultate CHANGELOG.md per le note di aggiornamento.

L'agente del piano dati per il sistema di controllo dell'egresso dei runner GitLab di leitwacht. eBPF + nftables + un proxy DNS all'interno della netns si collegano a ogni contenitore runner CI e applicano la politica di egresso. La CE (questo repo) legge le regole da un file YAML locale ed è completamente autonoma — nessun backend, nessuna comunicazione esterna, nessuna registrazione.

Un'Edizione Enterprise con licenza separata (gitlab.com/leitwacht/leitwacht) aggiunge un piano di controllo gestito (interfaccia utente per la creazione di regole, multi-tenancy, audit, integrazione con GitLab). L'agente EE importa agentcore/ da questo repo e sostituisce il caricatore YAML con un flusso di regole gRPC.

Struttura

agentcore/                   Primitivi del piano dati (MPL-2.0)
  enforcer/                  eBPF + nftables + proxy DNS + LSM cred/proc_mem
  watcher/                   Sorgente di eventi del ciclo di vita dei contenitori (containerd, docker)
  handler/                   Gestore del ciclo di vita — neutro rispetto all'edizione
  policy/                    ResolvedPolicy + interfaccia Source + caricatore
  advisory/                  Tipo advisory in Go puro + interfaccia Sink
  violation/                 Interfaccia Sink per la segnalazione di violazioni in Go puro
  wildcard/                  Helper per il pattern matching dei domini
  version/                   Timbro della versione del build (impostato tramite -ldflags)
  cmd/
    leitwacht-initc/         Contenitore init del pod che blocca i punti di ingresso fino al collegamento dell'agente

ce/                          Demone dell'Edizione Community (MPL-2.0)
  cmd/agent-ce/              Il binario
  config/                    Impostazioni del demone guidate da variabili d'ambiente
  ruleyaml/                  Caricatore di regole YAML + hot-reload tramite fsnotify
  sinks/                     stdout NDJSON / Prometheus / webhook
  helm/agent-ce/             Chart Helm
  SCHEMA.md                  Schema delle regole YAML (v1)

examples/
  rules.yaml                 Set di regole di esempio

docs/
  EVENT_FLOW.md              Flusso watcher → handler → enforcer + parametri regolabili (con mermaid)

Ambito del contenitore

leitwacht-agent ispeziona solo i contenitori che portano l'etichetta gestita dal runner GitLab com.gitlab.gitlab-runner.managed=true. I contenitori senza questa etichetta — qualsiasi cosa avviata manualmente, sidecar, carichi di lavoro applicativi — vengono completamente ignorati (nessun evento, nessuna applicazione, nessuna violazione). Questa è una scelta deliberata: leitwacht è il piano dati per l'egresso dei runner CI, e i carichi di lavoro non runner non dovrebbero essere intercettati silenziosamente. I casi d'uso non runner non rientrano nell'ambito della v0.1.0.

Limitazioni note (v0.1.0)

• Solo IPv4. I programmi eBPF e il proxy DNS applicano il controllo sul traffico IPv4; il traffico IPv6 in uscita viene bloccato al confine della netns indipendentemente dalla politica. I lavori CI che richiedono connettività IPv6 non possono utilizzare l'applicazione di leitwacht fino a quando non verrà risolto questo problema.
• Solo Linux x86_64. I runner arm64 non sono ancora supportati (CI fornisce immagini amd64; arm64 seguirà quando avremo artefatti eBPF per quell'architettura).
• Solo carichi di lavoro dei runner GitLab. Vedi "Ambito del contenitore" sopra.

Avvio rapido

# Build (CGO_ENABLED=0 permette la cross-compilazione pulita da host non Linux).
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build ./...

# Immagine contenitore
docker build -f Dockerfile.agent-ce -t leitwacht/agent-ce:dev .

# Installazione Helm (Kubernetes). dnsUpstream è obbligatorio — puntatelo al
# risolutore DNS del vostro cluster, non a uno pubblico, in modo che i servizi
# interni continuino a risolversi e le query non fuoriescano.
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"

Il riferimento completo allo schema per rules.yaml si trova in ce/SCHEMA.md.

Licenza

agentcore/ e ce/ sono distribuiti sotto la Mozilla Public License 2.0 — vedi LICENSE. MPL-2.0 è una licenza copyleft a livello di file: potete utilizzare, modificare e ridistribuire questi file nei vostri prodotti (commerciali o meno), ma qualsiasi modifica apportata ai file con licenza MPL-2.0 deve essere resa disponibile sotto la stessa licenza.

Il backend dell'Edizione Enterprise su gitlab.com/leitwacht/leitwacht è distribuito sotto una licenza diversa. I due repository sono co-sviluppati dallo stesso team.

Contribuire

Issue e merge request sul repo GitLab canonico (https://gitlab.com/leitwacht/leitwacht-agent). I problemi di sicurezza devono seguire la procedura in SECURITY.md. Le note sul flusso di lavoro e lo stile si trovano in CONTRIBUTING.md.

Compilazione

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

Gli oggetti eBPF (*_bpfel.o) sono impegnati nel repository perché per rigenerarli servono clang e gli header del kernel; le build CI si basano sugli artefatti impegnati. Per rigenerarli localmente su Linux:

go generate ./agentcore/enforcer/