kestrel

رؤية على مستوى النواة مثل Falco، مع واجهة حيّة لا توفرها الأدوات المبنية على النواة.

بدء سريع · المواصفات · العروض · خارطة الطريق

يتبع Kestrel أحداث النواة (تنفيذ العمليات، الوصول إلى الملفات، اتصالات الشبكة) عبر وكيل eBPF ويبثّها إلى تطبيق ويب SvelteKit يعرض موجز نشاط حيّ، وشجرة عمليات، ونظرة عامة على المضيف، ومحرك تنبيهات قائم على القواعد. راجع SPEC.md لوثيقة المنتج/البنية الكاملة وAGENTS.md للدليل التشغيلي.

لماذا وُجد هذا المشروع

النظام البيئي لـ eBPF مصمَّم على هيئة خلفيات/واجهات سطر أوامر/مشغّلات Kubernetes. يشتهر Falco — المعيار الحاصل على تخرّج CNCF — بعدم توفير أي واجهة مستخدم خاصة به. الفجوة بين «النواة تُصدر بيانات غنية» و«إنسان يستطيع قراءتها فعلًا» هي الموضع الأمثل على مستوى التطوير الكامل الذي يعيش فيه هذا المشروع. في الإصدار v1، مضيف واحد عمدًا (وليس Kubernetes) وللمراقبة فقط (بدون إنفاذ).

البنية

flowchart TB
    subgraph host["Linux host · VM in dev, VPS in prod · kernel ≥ 5.8"]
        direction TB
        probes["eBPF probes (C)<br/>execve · openat · connect"]
        agent["Go agent — cilium/ebpf<br/>decode · enrich · batch"]
        ingest["/api/ingest<br/>Zod-validated at the boundary"]
        rules["rule engine"]
        hub["live hub"]
        db[("Postgres<br/>events · rules · alerts")]
        dash["SvelteKit dashboard<br/>live feed · tree · overview"]

        probes -- "ring buffer" --> agent
        agent -- "HTTP POST · JSON (Zod contract)" --> ingest
        ingest --> db
        ingest --> rules
        ingest --> hub
        hub -- "SSE" --> dash
    end

قيد النشر الرئيسي: يحتاج الوكيل إلى نواة حقيقية، لذا لا يمكنه العمل على Cloudflare Workers (عزلات V8، بلا نواة). يضع v1 الوكيل + التطبيق + Postgres على مضيف واحد. راجع SPEC.md §2.

هيكل المستودع

الحالة

المرحلة 3 — قيد التقدم. اكتملت متطلبات المرحلة 2 الأساسية (الموجز الحيّ، شجرة العمليات، نظرة عامة على المضيف) وجرى التحقق منها مباشرةً في الجهاز الافتراضي: يقتفي وكيل eBPF (execve + exit، cilium/ebpf) أثر نواة حقيقية ويبثّ الأحداث إلى التطبيق، ويزرع الشجرة بلقطة /proc عند بدء التشغيل. حتى الآن في المرحلة 3: اكتسب الوكيل مجسّات فتح الملفات (openat) والاتصالات الصادرة (security_socket_connect) (تم التحقق من الترجمة؛ اختبار الحمل معلّق في الجهاز الافتراضي)، وتم بناء خريطة الشبكة (8.3) — رسم بياني D3 قائم على القوى بين العمليات والوجهات. التالي: مراقب الملفات الحساسة (8.4) ومحرك القواعد + التنبيهات (8.5). يبقى عمل المجسّات في الجهاز الافتراضي للتطوير، ولا يُنفَّذ على المضيف أبدًا.

عروض لوحة المعلومات

العمق في عروض قليلة يتفوق على الاتساع السطحي — ستة عروض واضحة، مبنية بترتيب الأولوية (المتطلبات الأساسية أولًا).

خارطة الطريق

• المرحلة 1 (التطبيق): مخطط الأحداث · الاستيعاب · محور SSE · الموجز الحيّ · الاختبارات
• المرحلة 1 (الوكيل): مجس execve ← ring buffer ← cilium/ebpf ← /api/ingest (في الجهاز الافتراضي)
• المرحلة 2: مجس exit + لقطة /proc · شجرة العمليات · نظرة عامة على المضيف
• [~] المرحلة 3: ✅ مجسّات الملفات والاتصالات · ✅ خريطة الشبكة · ◻️ مراقب الملفات · ◻️ محرك القواعد + التنبيهات · ◻️ ذاكرة تخزين مؤقتة لشجرة العمليات على الخادم · ◻️ اختبارات الخصائص وتسليم الأحداث
• المرحلة 4: جهاز افتراضي Nix للتطوير · اختبار تكامل النواة nixosTest · CI عبر GitHub Actions
• المرحلة 5: نشر VPS (Terraform)، وكيل + تطبيق + Postgres على نفس المضيف
• المرحلة 6 (طموحة): خط زمني/سجل تاريخي · «اشرح هذا التنبيه» عبر LLM · الإنفاذ · مضيفات متعددة · DaemonSet لـ k8s

تشغيل التطبيق (تطوير)

cd app
pnpm install
pnpm dev            # http://localhost:5173

يعمل التطبيق على المضيف؛ ويعمل الوكيل في الجهاز الافتراضي للتطوير ويرسل الأحداث إليه. لرؤية موجز مملوء بدون الوكيل، فعِّل المولّد الاصطناعي: KESTREL_SYNTHETIC=1 pnpm dev.

pnpm check          # svelte-check (types)
pnpm test           # vitest — schema + ingest unit tests
pnpm build          # production build (adapter-node)

قاعدة بيانات التطوير/الاختبار هي PGlite (Postgres مُجمَّع إلى WASM): لا بناء أصلي، ولا خادم منفصل، وبنفس لهجة SQL الخاصة بـ Postgres الإنتاجي. تُحفظ في app/kestrel-pgdata/ (مستثناة من git)؛ وتستخدم الاختبارات قاعدة بيانات مؤقتة في الذاكرة.

جرّب خط الأنابيب يدويًا

# stream events (leave running in one terminal)
curl -N http://localhost:5173/api/stream

# post an event (in another) — appears live in the stream and the browser
curl -X POST http://localhost:5173/api/ingest -H 'content-type: application/json' \
  -d '[{"host":"demo","type":"exec","pid":42,"comm":"bash","cmdline":"bash -i"}]'

الاختبار والتحقق

ثلاث طبقات، تتماشى مع مكان وجود كل فئة من الأخطاء (التفاصيل الكاملة في SPEC.md §6–§7):

• مُتحقق eBPF — مجاني. تُثبت النواة أن كل مجس آمن للذاكرة ومحدود وينتهي قبل تحميله — أخطر كود في النظام، يُتحقق منه وقت التحميل بلا مقابل.
• اختبارات قائمة على الخصائص (المرحلة 3). يقود fast-check عقد Zod للأحداث بأحداث عدائية/مشوّهة ويؤكد ثوابت محرك القواعد: لا تطابق كاذب، وأحكام حتمية، ورفض المدخلات المشوّهة عند الحدود.
• صحة تسليم الأحداث (المرحلة 3). أرقام تسلسلية لكل حدث + كاشف فجوات/تكرار من جهة العميل + اختبار فيض الاستيعاب يؤكدون أن كل حدث يعبر ingest ← SSE مرة واحدة بالضبط. (تم النظر في نموذج TLA+ رسمي وتأجيله عمدًا — غير مبرر عند حجم مضيف واحد.)

حاليًا: اختبارات وحدات Vitest (المخطط، الاستيعاب، النظرة العامة، شجرة العمليات، رسم الشبكة) + محلل procscan في الوكيل وأدوات decode المساعدة للأحداث. نفّذ pnpm test داخل /app، وgo test ./... داخل /agent.

مقايضات التصميم

• مضيف واحد مقابل عنقود (cluster) — خيار نطاق متعمَّد؛ المضيفات المتعددة هدف بعيد جدًا (SPEC.md §8.11).
• المراقبة فقط مقابل الإنفاذ — لا يقتل v1 أي عملية أبدًا؛ معيار المخاطرة للحظر المضمّن أعلى بكثير (SPEC.md §8.10).
• cilium/ebpf مقابل libbpfgo — Go خالص، CGO_ENABLED=0، سير عمل bpf2go.
• PGlite/Postgres مقابل SQLite مقابل ClickHouse — لهجة Postgres في كل مكان؛ جيدة حتى ~1M من الأحداث، وأعد النظر في ClickHouse بعد ذلك (SPEC.md §10).
• تحقق مجاني — يُثبت مُتحقق eBPF إحصائيًا أن كل مجس آمن للذاكرة ومحدود وينتهي قبل أن تحمّله النواة. أخطر كود في النظام يُتحقق منه وقت التحميل بتكلفة صفرية (SPEC.md §6).