kestrel

Falco의 커널 수준 가시성에, 커널 네이티브 도구들이 제공하지 않는 라이브 UI를 더했습니다.

빠른 시작 · 스펙 · 뷰 · 로드맵

Kestrel은 eBPF 에이전트로 커널 이벤트(프로세스 실행, 파일 접근, 네트워크 연결)를 추적하고, 이를 실시간 활동 피드, 프로세스 트리, 호스트 개요, 규칙 기반 알림 엔진을 렌더링하는 SvelteKit 웹 앱으로 스트리밍합니다. 전체 제품/아키텍처 문서는 SPEC.md, 운영 가이드는 AGENTS.md를 참조하세요.

왜 필요한가

eBPF 생태계는 백엔드/CLI/Kubernetes 오퍼레이터 중심입니다. CNCF 졸업 표준인 Falco는 유명하게도 자체 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 격리 환경, 커널 없음)에서는 실행할 수 없습니다. v1은 에이전트 + 앱 + Postgres를 단일 호스트에 함께 배치합니다. SPEC.md §2를 참조하세요.

저장소 구성

현재 상태

Phase 3 — 진행 중. Phase 2 필수 기능(실시간 피드, 프로세스 트리, 호스트 개요)은 완료되었고 VM에서 라이브로 검증되었습니다: eBPF 에이전트(execve + exit, cilium/ebpf)가 실제 커널을 추적하여 이벤트를 앱으로 스트리밍하고, 시작 시 /proc 스냅샷으로 트리를 초기화합니다. 지금까지의 Phase 3: 에이전트에 파일 열기(openat) 및 외부 연결(security_socket_connect) 프로브가 추가되었고(컴파일 검증 완료, VM에서 부하 테스트 대기 중), **네트워크 맵(8.3)**이 구축되었습니다 — D3 포스 기반 프로세스↔대상 그래프입니다. 다음 단계: 민감 파일 모니터(8.4)와 규칙 엔진 + 알림(8.5)입니다. 프로브 작업은 항상 개발 VM에서만 수행되며 호스트에서는 절대 수행되지 않습니다.

대시보드 뷰

적은 수의 뷰에 깊이를 주는 것이 얕게 폭을 넓히는 것보다 낫습니다 — 여섯 개의 깔끔한 뷰를 우선순위 순서대로(필수 기능 우선) 구축했습니다.

로드맵

• Phase 1 (앱): 이벤트 스키마 · 수집 · SSE 허브 · 실시간 피드 · 테스트
• Phase 1 (에이전트): execve 프로브 → 링 버퍼 → cilium/ebpf → /api/ingest (VM 내)
• Phase 2: exit 프로브 + /proc 스냅샷 · 프로세스 트리 · 호스트 개요
• [~] Phase 3: ✅ 파일 + 연결 프로브 · ✅ 네트워크 맵 · ◻️ 파일 모니터 · ◻️ 규칙 엔진 + 알림 · ◻️ 서버 측 프로세스 트리 캐시 · ◻️ 속성 및 이벤트 전달 테스트
• Phase 4: Nix 개발 VM · nixosTest 커널 통합 테스트 · GitHub Actions CI
• Phase 5: VPS 배포(Terraform), 에이전트 + 앱 + Postgres 동일 호스트 배치
• Phase 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(WASM으로 컴파일된 Postgres)입니다: 네이티브 빌드가 필요 없고, 별도 서버가 필요 없으며, 프로덕션 Postgres와 동일한 SQL 방언을 사용합니다. 데이터는 app/kestrel-pgdata/에 저장되며(gitignore 대상), 테스트는 임시 인메모리 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 검증기 — 무료. 커널은 프로브를 로드하기 전에 모든 프로브가 메모리 안전, 경계성, 종료성을 충족함을 증명합니다 — 시스템에서 가장 위험한 코드가 로드 시점에 무료로 검증됩니다.
• 속성 기반 테스트 (Phase 3). fast-check가 적대적/비정상 이벤트로 Zod 이벤트 계약을 시험하고 규칙 엔진 불변식을 검증합니다: 오탐 없음, 결정적 판정, 비정상 입력은 경계에서 거부됩니다.
• 이벤트 전달 정확성 (Phase 3). 이벤트별 시퀀스 번호 + 클라이언트 누락/중복 감지기 + 수집 플러드 테스트가 모든 이벤트가 수집 → SSE를 정확히 한 번 통과함을 검증합니다. (공식 TLA+ 모델이 고려되었으나 의도적으로 보류되었습니다 — 단일 호스트 규모에서는 타당성이 없습니다.)

현재: Vitest 유닛 테스트(스키마, 수집, 개요, 프로세스 트리, 네트워크 그래프) + 에이전트의 procscan 파서와 이벤트 decode 헬퍼. /app에서 pnpm test, /agent에서 go test ./...를 실행하세요.

설계 트레이드오프

• 단일 호스트 vs 클러스터 — 의도적인 범위 선택; 멀티 호스트는 먼 훗날의 목표입니다 (SPEC.md §8.11).
• 관찰 전용 vs 집행 — v1은 프로세스를 종료하지 않습니다; 인라인 차단의 리스크 기준은 훨씬 더 높습니다 (SPEC.md §8.10).
• cilium/ebpf vs libbpfgo — 순수 Go, CGO_ENABLED=0, bpf2go 워크플로우.
• PGlite/Postgres vs SQLite vs ClickHouse — 모든 곳에서 Postgres 방언을 사용합니다; 약 100만 개 이벤트 미만에서는 충분하며, 그 이상의 규모에서는 ClickHouse를 재검토합니다 (SPEC.md §10).
• 무료로 얻는 검증 — eBPF 검증기는 커널이 로드하기 전에 모든 프로브가 메모리 안전, 경계성, 종료성을 지닌다는 것을 정적으로 증명합니다. 시스템에서 가장 위험한 코드가 로드 시점에 비용 없이 검증됩니다 (SPEC.md §6).