How knox1837/k-guard works
1. Repository purpose
- K-Guard is an end-to-end runtime monitoring and visualization pipeline for Linux.
- Its core architecture is a kernel-space eBPF sensor feeding a user-space event stream, which is then turned into a live behavioral graph for inspection.
2. Kernel instrumentation layer
- src/kernel/kguard.bpf.c is the eBPF program loaded into the kernel.
- This is the boundary where low-level runtime events are captured with kernel context, using the generated vmlinux.h BTF header and libbpf tooling.
- Architecturally, this layer is responsible for observing system behavior and emitting structured events upward, without doing presentation or heavy analysis.
3. User-space collection and emission
- src/user/monitor.c is the compiled user-space companion binary.
- The README’s execution flow shows sudo ./monitor | python3 src/user/graphengine.py, which implies monitor acts as the producer of event records on stdout.
- This process is the bridge between kernel probes and Python-side processing.
4. Graph construction and live topology engine
- src/user/graphengine.py is the main orchestration and transformation layer.
- It consumes the monitor’s event stream, translates runtime observations into graph entities/edges, and maintains the evolving topology using NetworkX.
- This is the central “model” layer: it converts raw telemetry into an in-memory behavioral graph.
5. Persistence and visualization output
- The graph engine auto-saves updates every few seconds and produces kguard_interactive_graph.html.
- That output is the stable visualization artifact: the live graph can be reopened in a browser independently of the running monitor.
- This means the architecture includes both a streaming runtime path and a file-based exported view.
6. Provenance/data modeling
- src/user/provenance.py likely defines the event/provenance structures used by the Python pipeline.
- In architectural terms, this is the semantic layer that maps raw kernel observations into process/file/network/resource lineage or similar provenance relationships.
- It helps separate event parsing from graph-building logic.
7. GUI and operator-facing tools
- kguard_gui.py and view_graph.py appear to be convenience front ends around the generated graph output.
- These are not the monitoring core; they sit on top of the exported visualization/artifacts to provide a human-facing experience.
- They likely serve as alternative entry points for opening or interacting with the topology.
8. ML/analytics sidecar
- ml_detector.py suggests an optional analysis component that consumes monitoring or provenance data for anomaly detection or classification.
- It is best viewed as a downstream analytics subsystem, separate from the real-time capture-to-graph path.
- If used, it would sit beside the visualization engine rather than inside the kernel event pipeline.
9. Build and runtime dependencies
- The repository depends on clang, llvm, libbpf, libelf, bpftool, and Python packages from requirements.txt.
- Makefile coordinates compiling the kernel/user components and likely handles the eBPF build pipeline.
- The generated vmlinux.h is an important architecture dependency: it ties the probe code to the running kernel’s BTF metadata.
10. Key boundary summary
- The main boundary is kernel space vs. user space:
- kernel eBPF program captures events,
- user-space monitor transports them,
- Python graph engine interprets and visualizes them.
- A second boundary is live stream vs. persisted artifact:
- events are processed in real time,
- graph state is periodically saved as an interactive HTML topology.
11. How to diagram it
- The clearest architecture diagram would show:
- Linux kernel + eBPF probe at the left,
- monitor as a streaming bridge,
- graphengine.py with NetworkX as the central processing node,
- exported HTML graph plus GUI/viewer on the right,
- optional ml_detector.py as a side analytics path.
Main entry points: graphengine.py Graph engine · Makefile Build · kguard.bpf.c eBPF probe · monitor.c Monitor
Components 16
Kernel space
eBPF instrumentation inside the Linux kernel
- eBPF probe · Kernel-space eBPF program that captures runtime events with kernel context.
src/kernel/kguard.bpf.c - libbpf · Library and tooling layer used to load and manage the kernel eBPF program.
- bpftool · Tooling used during the eBPF build and kernel metadata generation flow.
User space
Runtime collection and graph construction
- Monitor · User-space companion binary that receives kernel events and emits a record stream.
src/user/monitor.c - Graph engine · Main Python orchestration layer that consumes the event stream and maintains the live behavioral graph.
src/user/graphengine.py - Provenance · Semantic data model for translating raw observations into lineage and relationship records.
src/user/provenance.py - NetworkX · In-memory graph library used by the Python engine to build and update topology.
- CLC daemon · Additional user-space daemon component adjacent to the main monitoring pipeline.
src/user/clc_daemon.py - Build · Coordinates compilation of the kernel eBPF program, user-space binary, and supporting assets.
Makefile - Python deps · Python package requirements for the graphing and analysis components.
requirements.txt - README · Documents the runtime pipeline and how to launch the streaming monitor into the graph engine.
README.md - Clang/LLVM · Compilation toolchain used for building the eBPF and user-space components.
Visualization
Persisted graph output and front ends
- HTML graph · Auto-saved interactive graph file that can be reopened independently of the live process.
- GUI · Convenience graphical front end for viewing the generated graph.
kguard_gui.py - Graph viewer · Command-line or lightweight viewer for opening the exported graph artifact.
view_graph.py
Analytics
Optional downstream analysis
- ML detector · Optional analysis component for anomaly detection or classification on monitoring data.
ml_detector.py
Connections 20
- eBPF probe → Monitor: kernel events · The probe emits structured runtime observations that the monitor transports upward.
- Monitor → Graph engine: event stream · The monitor writes event records that the Python engine consumes as its live input.
- Graph engine → Provenance: parse model · The engine maps raw records into provenance-aware entities and relationships.
- Provenance → NetworkX: graph objects · Provenance structures are materialized into graph nodes and edges.
- NetworkX → HTML graph: autosave · The in-memory topology is periodically written out as an interactive HTML artifact.
- HTML graph → GUI: open graph · The GUI consumes the saved artifact for human inspection.
- HTML graph → Graph viewer: load graph · The viewer opens the persisted graph for offline inspection.
- Graph engine → ML detector: telemetry feed · Optional analytics can consume the same monitoring/provenance data stream.
- Build → eBPF probe: build probe · The build system compiles the kernel eBPF program.
- Build → Monitor: build binary · The build system compiles the user-space monitor companion.
- Build → Graph engine: package app · The build flow prepares the Python graph engine and related runtime assets.
- Build → Clang/LLVM: toolchain · Compilation relies on the Clang/LLVM toolchain.
- eBPF probe → libbpf: load/manage · The eBPF program is loaded and managed through libbpf.
- eBPF probe → bpftool: btf support · Kernel BTF metadata generation and inspection support the probe build.
- Python deps → Graph engine: python deps · Python package dependencies support the graph engine runtime.
- Python deps → ML detector: python deps · The same dependency set supports the optional analytics component.
- README → Monitor: run flow · The documented execution path starts the monitor as the event producer.
- README → Graph engine: pipe input · The documented pipeline pipes monitor output into the graph engine.
- README → HTML graph: saved output · The README describes the persisted interactive graph artifact.
- CLC daemon → Graph engine: adjacent service · A related user-space daemon sits alongside the main topology engine.