leitwacht-agent

https://leitwacht.eu — fonte da verdade: https://gitlab.com/leitwacht/leitwacht-agent. Issues, MRs e discussões ficam no GitLab.

Pré-1.0. A série 0.x é pré-estável; versões menores podem trazer mudanças que quebram compatibilidade nas APIs, nomes de env-vars, chaves do values.yaml do Helm e esquema do arquivo de regras até o lançamento da 1.0. Fixe em digests de imagem (não tags flutuantes) em produção. Veja CHANGELOG.md para notas de atualização.

O agente do plano de dados para o sistema de controle de egresso do GitLab Runner da leitwacht. eBPF + nftables + um proxy DNS no namespace de rede são anexados a cada contêiner do runner de CI e aplicam a política de egresso. A CE (este repositório) lê suas regras de um arquivo YAML local e é totalmente independente — sem backend, sem telefonar para casa, sem registro.

Uma Enterprise Edition licenciada separadamente (gitlab.com/leitwacht/leitwacht) adiciona um plano de controle gerenciado (IU de criação de regras, multi-inquilino, auditoria, integração com GitLab). O agente EE importa agentcore/ deste repositório e substitui o carregador YAML por um fluxo de regras gRPC.

Layout

agentcore/                   primitivas do plano de dados (MPL-2.0)
  enforcer/                  eBPF + nftables + proxy DNS + LSM cred/proc_mem
  watcher/                   fonte de eventos do ciclo de vida do contêiner (containerd, docker)
  handler/                   manipulador do ciclo de vida — neutro de edição
  policy/                    ResolvedPolicy + interface Source + carregador
  advisory/                  tipo advisory em Go puro + interface Sink
  violation/                 interface Sink de relatório de violação em Go puro
  wildcard/                  auxiliares de correspondência de padrões de domínio
  version/                   carimbo de versão de build (definido via -ldflags)
  cmd/
    leitwacht-initc/          contêiner de init do pod que bloqueia pontos de entrada até o anexo do agente

ce/                          Daemon Community Edition (MPL-2.0)
  cmd/agent-ce/              o binário
  config/                    configurações do daemon orientadas por env
  ruleyaml/                  carregador de regras YAML + hot-reload via fsnotify
  sinks/                     stdout NDJSON / Prometheus / webhook
  helm/agent-ce/             Chart Helm
  SCHEMA.md                  esquema de regras YAML (v1)

examples/
  rules.yaml                 conjunto inicial de regras

docs/
  EVENT_FLOW.md              fluxo watcher → handler → enforcer + ajustes (com mermaid)

Escopo do contêiner

O leitwacht-agent inspeciona apenas contêineres que possuem o rótulo gerenciado do GitLab Runner com.gitlab.gitlab-runner.managed=true. Contêineres sem este rótulo — qualquer coisa que você iniciar manualmente, sidecars, cargas de trabalho de aplicação — são ignorados completamente (sem eventos, sem aplicação, sem violações). Isso é proposital: leitwacht é o plano de dados para egresso do runner de CI, e cargas de trabalho que não são runners não devem ser interceptadas silenciosamente. Casos de uso que não são Runner estão fora do escopo para v0.1.0.

Limitações conhecidas (v0.1.0)

Apenas IPv4. Os programas eBPF e o proxy DNS aplicam a política no tráfego IPv4; o egresso IPv6 é descartado na fronteira do namespace de rede independentemente da política. Trabalhos de CI que exigem conectividade IPv6 não podem usar a aplicação do leitwacht até que isso seja resolvido.
Apenas Linux x86_64. Runners arm64 ainda não são suportados (a CI envia imagens amd64; arm64 virá assim que tivermos artefatos eBPF para essa arquitetura).
Apenas cargas de trabalho do GitLab Runner. Veja "Escopo do contêiner" acima.

Início rápido

# Build (CGO_ENABLED=0 permite que hosts não-Linux façam cross-compile limpo).
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build ./...

# Imagem do contêiner
docker build -f Dockerfile.agent-ce -t leitwacht/agent-ce:dev .

# Instalação Helm (Kubernetes). dnsUpstream é obrigatório — aponte-o para o
# resolvedor DNS do seu cluster, não para um público, para que serviços internos
# continuem resolvendo e consultas não vazem.
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"

A referência completa do esquema para rules.yaml está em ce/SCHEMA.md.

Licença

agentcore/ e ce/ são distribuídos sob a Licença Pública Mozilla 2.0 — veja LICENSE. MPL-2.0 é uma licença copyleft em nível de arquivo: você pode usar, modificar e redistribuir estes arquivos em seus próprios produtos (comerciais ou não), mas quaisquer alterações que você fizer em arquivos licenciados sob MPL-2.0 devem ser disponibilizadas sob a mesma licença.

O backend da Enterprise Edition em gitlab.com/leitwacht/leitwacht é distribuído sob uma licença diferente. Os dois repositórios são co-desenvolvidos pela mesma equipe.

Contribuindo

Issues e merge requests no repositório GitLab canônico (https://gitlab.com/leitwacht/leitwacht-agent). Problemas de segurança devem seguir o processo em SECURITY.md. Notas sobre workflow e estilo estão em CONTRIBUTING.md.

Compilação

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

Os objetos eBPF (*_bpfel.o) estão mantidos porque regenerá-los requer clang + cabeçalhos do kernel; builds de CI dependem dos artefatos mantidos. Para regenerar localmente no Linux:

go generate ./agentcore/enforcer/

Ler mais

LeitWacht Agent v0.9.0

Categorias