leitwacht-agent

https://leitwacht.eu — исходный код: https://gitlab.com/leitwacht/leitwacht-agent. Вопросы, MR-ы и обсуждения ведутся на GitLab.

Pre-1.0. Серия 0.x является предварительной; minor-релизы могут содержать критические изменения в API, именах переменных окружения, ключах helm values.yaml и схеме файлов правил до выхода версии 1.0. Фиксируйте образы по дайджестам (а не по плавающим тегам) в продакшне. См. CHANGELOG.md для примечаний к обновлению.

Агент плоскости данных для системы контроля исходящего трафика leitwacht GitLab Runner. Система. eBPF + nftables + DNS-прокси внутри netns подключаются к каждому контейнеру раннера и применяют политику исходящего трафика. CE (этот репозиторий) считывает свои правила из локального YAML-файла и полностью автономен — без бэкенда, без отправки данных, без регистрации.

Отдельно лицензируемая Enterprise Edition (gitlab.com/leitwacht/leitwacht) добавляет управляемую панель управления (интерфейс создания правил, мультиарендность, аудит, интеграция с GitLab). Агент EE импортирует agentcore/ из этого репозитория и заменяет загрузчик YAML на поток правил через gRPC.

Структура

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)

Область действия контейнера

leitwacht-agent проверяет только контейнеры, имеющие управляющую метку GitLab Runner com.gitlab.gitlab-runner.managed=true. Контейнеры без этой метки — всё, что вы запускаете вручную, sidecar-контейнеры, рабочие нагрузки приложений — полностью игнорируются (никаких событий, никакого принуждения, никаких нарушений). Это сделано намеренно: leitwacht — плоскость данных для CI раннеров исходящего трафика, и не-раннерные рабочие нагрузки не должны молча перехватываться. Сценарии использования не-раннеров выходят за рамки v0.1.0.

Известные ограничения (v0.1.0)

• Только IPv4. Программы eBPF и DNS-прокси работают только с IPv4-трафиком; исходящий IPv6 отбрасывается на границе netns независимо от политики. Задачи CI, требующие IPv6-соединения, не могут использовать контроль leitwacht, пока это не будет исправлено.
• Только Linux x86_64. arm64-раннеры пока не поддерживаются (CI поставляет amd64-образы; arm64 будет добавлен после создания eBPF-артефактов для этой архитектуры).
• Только рабочие нагрузки GitLab Runner. См. "Область действия контейнера" выше.

Быстрый старт

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

Полная справка по схеме для rules.yaml находится в ce/SCHEMA.md.

Лицензия

agentcore/ и ce/ распространяются под Mozilla Public License 2.0 — см. LICENSE. MPL-2.0 — это лицензия copyleft на уровне файлов: вы можете использовать, изменять и распространять эти файлы в своих продуктах (коммерческих или иных), но любые изменения, внесённые вами в файлы под лицензией MPL-2.0, должны быть доступны под той же лицензией.

Бэкенд Enterprise Edition на gitlab.com/leitwacht/leitwacht распространяется под другой лицензией. Два репозитория совместно разрабатываются одной командой.

Вклад

Вопросы и запросы на слияние в каноническом GitLab-репозитории (https://gitlab.com/leitwacht/leitwacht-agent). Проблемы безопасности следует сообщать в соответствии с процессом, описанным в SECURITY.md. Рабочий процесс и замечания по стилю находятся в CONTRIBUTING.md.

Сборка

Только Linux (eBPF + nftables): GOOS=linux GOARCH=amd64 go build ./...

Объекты eBPF (*_bpfel.o) закоммичены, потому что их перегенерация требует clang и заголовочные файлы ядра; сборки CI полагаются на закоммиченные артефакты. Чтобы перегенерировать локально на Linux:

go generate ./agentcore/enforcer/