kestrel

Falco की कर्नेल-स्तरीय दृश्यता, उस लाइव UI के साथ जो कर्नेल-नेटिव टूल्स साथ नहीं देते।

त्वरित शुरुआत · स्पेक · दृश्य · रोडमैप

Kestrel कर्नेल इवेंट्स (प्रोसेस exec, फ़ाइल एक्सेस, नेटवर्क कनेक्शन) को एक eBPF एजेंट के ज़रिए ट्रेस करता है और उन्हें एक SvelteKit वेब ऐप पर स्ट्रीम करता है, जो लाइव गतिविधि फ़ीड, प्रोसेस ट्री, होस्ट ओवरव्यू और एक नियम-आधारित अलर्ट इंजन प्रस्तुत करता है। पूरा उत्पाद/आर्किटेक्चर दस्तावेज़ SPEC.md में और परिचालन मार्गदर्शिका AGENTS.md में देखें।

यह क्यों मौजूद है

eBPF इकोसिस्टम बैकएंड/CLI/Kubernetes-ऑपरेटर के आकार का है। Falco — CNCF-ग्रेजुएटेड मानक — प्रसिद्ध रूप से अपना कोई UI शिप नहीं करता। "कर्नेल समृद्ध डेटा उत्सर्जित करता है" और "एक इंसान वास्तव में उसे पढ़ सकता है" के बीच का अंतर वह फुल-स्टैक स्वीट स्पॉट है जिसमें यह प्रोजेक्ट रहता है। 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 isolates, कोई कर्नेल नहीं) पर नहीं चल सकता। v1 एजेंट + ऐप + Postgres को एक ही होस्ट पर co-locate करता है। SPEC.md §2 देखें।

रिपॉज़िटरी संरचना

स्थिति

चरण 3 — प्रगति पर है। चरण 2 की अनिवार्य चीज़ें (लाइव फ़ीड, प्रोसेस ट्री, होस्ट ओवरव्यू) पूरी हैं और VM में लाइव सत्यापित हैं: eBPF एजेंट (execve + exit, cilium/ebpf) एक वास्तविक कर्नेल को ट्रेस करता है और इवेंट्स को ऐप पर स्ट्रीम करता है, स्टार्टअप पर /proc स्नैपशॉट के साथ ट्री को सीड करता है। अब तक चरण 3: एजेंट ने फ़ाइल-ओपन (openat) और आउटबाउंड-कनेक्शन (security_socket_connect) प्रोब जोड़े हैं (कम्पाइल-सत्यापित; VM में लोड-टेस्ट बाकी), और नेटवर्क मैप (8.3) बन चुका है — एक D3 फ़ोर्स-डायरेक्टेड प्रोसेस↔डेस्टिनेशन ग्राफ। आगे: सेंसिटिव-फ़ाइल मॉनिटर (8.4) और रूल इंजन + अलर्ट्स (8.5)। प्रोब का काम डेव VM में ही रहता है, कभी होस्ट पर नहीं।

डैशबोर्ड दृश्य

कुछ दृश्यों पर गहराई, सतही चौड़ाई से बेहतर है — छह स्पष्ट दृश्य, प्राथमिकता क्रम में बनाए गए (पहले अनिवार्य चीज़ें)।

रोडमैप

• चरण 1 (ऐप): इवेंट स्कीमा · इन्जेस्ट · SSE हब · लाइव फ़ीड · टेस्ट
• चरण 1 (एजेंट): execve प्रोब → रिंग बफर → cilium/ebpf → /api/ingest (VM में)
• चरण 2: exit प्रोब + /proc स्नैपशॉट · प्रोसेस ट्री · होस्ट ओवरव्यू
• [~] चरण 3: ✅ फ़ाइल + कनेक्ट प्रोब · ✅ नेटवर्क मैप · ◻️ फ़ाइल मॉनिटर · ◻️ रूल इंजन + अलर्ट्स · ◻️ सर्वर-साइड प्रोसेस-ट्री कैश · ◻️ प्रॉपर्टी + इवेंट-डिलीवरी टेस्ट
• चरण 4: Nix डेव VM · nixosTest कर्नेल इंटीग्रेशन टेस्ट · GitHub Actions CI
• चरण 5: VPS डिप्लॉय (Terraform), एजेंट + ऐप + Postgres co-located
• चरण 6 (स्ट्रेच): टाइमलाइन/हिस्ट्री · LLM "इस अलर्ट को समझाओ" · एन्फोर्समेंट · मल्टी-होस्ट · k8s DaemonSet

ऐप चलाना (डेव)

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

ऐप होस्ट पर चलता है; एजेंट डेव VM में चलता है और इवेंट्स उसे भेजता है। एजेंट के बिना भरी हुई फ़ीड देखने के लिए, सिंथेटिक जनरेटर ऑप्ट-इन करें: 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 में कम्पाइल): कोई नेटिव बिल्ड नहीं, कोई अलग सर्वर नहीं, prod Postgres जैसा ही SQL डायलेक्ट। यह app/kestrel-pgdata/ में पर्सिस्ट करता है (gitignored); टेस्ट एक अस्थायी इन-मेमोरी DB इस्तेमाल करते हैं।

पाइपलाइन को हाथ से आज़माएँ

# 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 इवेंट कॉन्ट्रैक्ट को adversarial/मैलफॉर्म्ड इवेंट्स के साथ चलाता है और रूल-इंजन इनवेरिएंट्स की पुष्टि करता है: कोई फ़ॉल्स मैच नहीं, निर्धारक वर्डिक्ट्स, मैलफॉर्म्ड इनपुट बाउंड्री पर रिजेक्ट।
• इवेंट-डिलीवरी सहीपन (चरण 3)। प्रति-इवेंट सीक्वेंस नंबर + एक क्लाइंट गैप/डुप डिटेक्टर + एक इन्जेस्ट-फ्लड टेस्ट यह सुनिश्चित करता है कि हर इवेंट इन्जेस्ट → SSE को ठीक एक बार पार करे। (एक औपचारिक TLA+ मॉडल पर विचार किया गया था और जानबूझकर टाल दिया गया — सिंगल-होस्ट वॉल्यूम पर उचित नहीं।)

वर्तमान में: Vitest यूनिट्स (स्कीमा, इन्जेस्ट, ओवरव्यू, प्रोसेस ट्री, नेटवर्क ग्राफ़) + एजेंट के procscan पार्सर और इवेंट decode हेल्पर्स। /app में pnpm test चलाएँ, /agent में go test ./...।

डिज़ाइन ट्रेडऑफ़

• सिंगल-होस्ट बनाम क्लस्टर — जानबूझकर स्कोप चॉइस; मल्टी-होस्ट एक दूर का स्ट्रेच है (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)।