GitLab Runner Leitwacht

فرض تقييد الشبكة الخارجية لحاويات CI/CD الخاصة بـ GitLab Runner. يمنع Leitwacht هجمات سلسلة التوريد من تسريب الأسرار عن طريق التحكم في ما يمكن لكل حاوية مهمة الوصول إليه على الشبكة.

كيف يعمل

Leitwacht هو وكيل مستقل يعمل جنبًا إلى جنب مع GitLab Runner على كل عقدة. يتداخل مع أحداث بدء تشغيل الحاويات، ويُرفق آليات فرض السياسات، ويُبلغ عن جميع نشاطات الشبكة إلى الباك إند المركزية. لا يلزم إجراء أي تعديلات على GitLab Runner.

مكدس الفرض (لكل حاوية)

Container Process
    |
    | DNS query (port 53)
    v
nftables redirect ──> DNS Proxy (:15353)
                         |
                         |── Allowlist check (FQDN match)
                         |── Block: NXDOMAIN response
                         |── Allow: forward to upstream, add resolved IPs to eBPF allow map
                         |── Record: domain, resolved IPs, PID, process name
                         v
                    Upstream DNS (CoreDNS / external)
    
Container Process
    |
    | TCP/UDP egress (any port)
    v
eBPF cgroup-skb/egress filter
    |── IP in allow map? ──> ALLOW (counted)
    |── IP in trusted CIDRs? ──> ALLOW (pod net, svc net)
    |── Cloud metadata (169.254.169.254)? ──> BLOCK (always)
    |── DoT (port 853)? ──> BLOCK (always)
    |── IPv6 (non-loopback)? ──> BLOCK (always)
    |── Default ──> BLOCK (drop event to ringbuf)

المشاركة على مستوى البود (Kubernetes)

جميع الحاويات في بود K8s تشترك في مساحة شبكة واحدة. ينشئ Leitwacht NetnsContext واحدًا لكل بود يمتلك الحالة المشتركة (وكيل DNS، قواعد nftables، خرائط eBPF). تحصل كل حاوية على ارتباط cgroup-skb الخاص بها بحيث لا يمكن لأي حاوية شقيقة تجاوز الفلتر.

Pod (shared netns)
 +-- NetnsContext (1 per pod)
 |    +-- DNS Proxy (1 goroutine pair)
 |    +-- nftables redirect rules
 |    +-- eBPF program + maps
 |    +-- Ringbuf reader
 |
 +-- Container A
 |    +-- CgroupLink (eBPF attached to A's cgroup)
 |    +-- ViolationRecorder
 |
 +-- Container B
      +-- CgroupLink (eBPF attached to B's cgroup)
      +-- ViolationRecorder

التواصل بين الوكيل والباك إند

+------------------+          gRPC           +------------------+
|  Leitwacht Agent  | ──────────────────────> |  Leitwacht Server |
|  (per node)      |                         |  (central)       |
|                  |  GetPolicy(project)     |                  |
|  - Watcher       | <───────────────────── |  - Policy store  |
|  - Enforcer      |                         |  - Violation DB  |
|  - DNS Proxy     |  ReportViolations(job)  |  - REST API      |
|  - Reporter      | ──────────────────────> |  - Frontend SPA  |
|  - Honeypot LSM  |                         |  - Notifications |
|                  |  Heartbeat()            |  - Baselines     |
|                  | ──────────────────────> |  - Anomaly det.  |
+------------------+                         +------------------+

البنية

المكونات

المكون	الوصف
الوكيل (`cmd/agent`)	DaemonSet على عقد Runner. يراقب containerd بحثًا عن حاويات المهام، ويُرفق eBPF + وكيل DNS، ويُبلغ عن الانتهاكات. يتطلب صلاحيات الجذر + Linux.
الخادم (`cmd/server`)	الباك إند المركزي. واجهة REST API للواجهة الأمامية، و gRPC للوكلاء. يخزن السياسات والانتهاكات والخطوط الأساسية. يستخدم Postgres أو SQLite.
الواجهة الأمامية (`frontend/`)	تطبيق SvelteKit SPA. إدارة السياسات، عرض الانتهاكات، إدارة الخطوط الأساسية، كشف الشذوذ، سجل التدقيق.

الحزم الرئيسية

هذا المستودع هو الخادم المصدري (EE) + الوكيل المرخص بـ EE. طبقة شبكة فرض السياسات الموضحة في المخططات أعلاه (eBPF، وكيل DNS، nftables، مراقب containerd) موجودة في وحدة المجتمع المنفصلة بترخيص MPL-2.0 leitwacht-agent، التي يستهلكها هذا المستودع كاعتماد؛ cmd/agent + ee/ هما بناء EE الذي يعيد استخدامها ويوصلها بالباك إند.

الحزمة	الغرض
`internal/agentgrpc`	خادم gRPC: يستقبل تقارير انتهاكات الوكيل، ويقدم تدفقات السياسات والقواعد
`internal/api`	معالجات REST API، برمجيات وسيطة للمصادقة، نطاق RBAC
`internal/auth`	مصادقة OIDC (GitLab)، الجلسات، CSRF
`internal/store`	الوصول إلى بيانات GORM (المشاريع، الانتهاكات، الخطوط الأساسية) + ClickHouse
`internal/license`, `internal/licensemgr`	التحقق من ترخيص EE (Ed25519 JWS) + دورة الحياة وبوابة التكوين (انظر LICENSE)
`internal/notify`	توصيل التنبيهات (البريد الإلكتروني/SES، Slack) + القوالب
`internal/retention`	الاحتفاظ بالبيانات / التقليم
`internal/mcp`, `internal/mcpauth`	خادم MCP + المصادقة
`ee/reporter`	عميل gRPC للوكيل EE يقوم بدفع الانتهاكات والتنبيهات إلى الباك إند
`ee/policycache`, `ee/rulewatcher`, `ee/rulestore`	ذاكرة تخزين مؤقت لسياسات الوكيل EE + مراقبة/تخزين القواعد (BBolt)
`contract/`	وحدة Go مشتركة: مصادر `.proto` + أنواع الاتصالات المولدة `agentpb`

النشر

المتطلبات الأساسية

مجموعة Kubernetes مع وقت تشغيل containerd
GitLab Runner يستخدم مُنفِّذ Kubernetes
FF_NETWORK_PER_BUILD=true على المشغّلات (كل وظيفة تحصل على مساحة شبكة خاصة بها)

مخططات Helm

الخادم (helm/) — منشور كمخطط OCI. يحتاج إلى Postgres + ClickHouse وقليل من الأسرار المنشأة مسبقًا (DSN لقاعدة البيانات، مفاتيح المصادقة). راجع docs/DEPLOY.md لدليل التشغيل الكامل.

helm install leitwacht \
  oci://registry.gitlab.com/leitwacht/leitwacht/charts/leitwacht --version 1.18.0 \
  --set image.tag=1.18.0 \
  --set ingress.domain=example.com --set ingress.hosts[0]=leitwacht.example.com \
  --set grpcIngress.domain=example.com --set grpcIngress.hosts[0]=grpc-leitwacht.example.com \
  --set app.oidcIssuer=https://gitlab.com --set app.oidcClientId=<oauth-app-id> \
  --set clickhouse.embedded.password=<password>

الوكيل (helm/agent/):

helm install leitwacht-agent \
  oci://registry.gitlab.com/leitwacht/leitwacht/charts/leitwacht-agent --version 1.18.0 \
  --set agent.backendAddr="leitwacht.namespace.svc.cluster.local:9090" \
  --set agent.defaultAction=audit \
  --set agent.dnsUpstream="10.96.0.10:53,1.1.1.1:53" \
  --set agent.trustedCIDRs="10.244.0.0/16,10.96.0.0/12"

أوضاع الفرض

الوضع	سياسة DNS	فلتر eBPF	حالة الاستخدام
audit	تمرير الكل، تسجيل الانتهاكات	السماح بالكل، تسجيل الحظر	بناء خط الأساس، الإطلاق الأولي
block	NXDOMAIN للمُدرجين في القائمة البيضاء)	حظر عناوين IP غير المُدرجة في القائمة البيضاء	الفرض في الإنتاج
allow	بدون فرض	بدون فرض	مشاريع معفاة

التطوير

البناء

# الواجهة الخلفية
go build ./cmd/agent
go build ./cmd/server

# الواجهة الأمامية
cd frontend && pnpm install && pnpm build

# إعادة توليد عقد gRPC (قم بتعديل contract/proto/**، ثم:)
cd contract && buf generate proto/

طبقة شبكة eBPF ليست في هذا المستودع — إنها موجودة في وحدة leitwacht-agent (CE). أعد توليد هياكل BPF هناك (راجع ملف Makefile لهذا المستودع: make ebpf-generate).

الاختبار

# اختبارات الوحدة (أي منصة)
go test ./...

# اختبارات التكامل / e2e التي تتطلب حاويات مساعدة (ClickHouse + Postgres) موجودة تحت
# internal/store, internal/api, internal/agentgrpc — قم بتشغيلها أولاً.

# الواجهة الأمامية
cd frontend && pnpm test

الفحص البرمجي

# الواجهة الخلفية
golangci-lint run ./...

# الواجهة الأمامية
cd frontend && pnpm lint

التوثيق

المستند	المحتويات
docs/DEPLOY.md	دليل تشغيل كامل لنشر Kubernetes (الأسرار، ClickHouse، الترحيلات، تثبيت الترخيص، التعريض)
docs/MULTI_ORG.md	إعداد متعدد المؤسسات / متعدد المستأجرين
LICENSE, NOTICE	شروط BSL 1.1 (ترخيص التغيير: MPL-2.0) وفصل ترخيص CE/EE
`leitwacht-agent`	وكيل طبقة شبكة المجتمع MPL-2.0 (فرض eBPF / وكيل DNS / nftables) — المحرك وراء المخططات أعلاه

اقرأ المزيد

LeitWacht v1.21.0

الفئات