# knox1837/k-guard architecture

> Architecture diagram of the GitHub repository knox1837/k-guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/knox1837/k-guard
- Repository: https://github.com/knox1837/k-guard

## Overview

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: [`src/user/graphengine.py`](https://github.com/knox1837/k-guard/blob/main/src/user/graphengine.py) (Graph engine), [`Makefile`](https://github.com/knox1837/k-guard/tree/main/Makefile) (Build), [`src/kernel/kguard.bpf.c`](https://github.com/knox1837/k-guard/blob/main/src/kernel/kguard.bpf.c) (eBPF probe), [`src/user/monitor.c`](https://github.com/knox1837/k-guard/blob/main/src/user/monitor.c) (Monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_kernel["Kernel space"]
  node_kernel_bpf["eBPF probe<br/>kernel sensor<br/>[kguard.bpf.c]"]
  node_libbpf(("libbpf<br/>ebpf runtime"))
  node_bpftool(("bpftool<br/>kernel tool"))
end

subgraph group_user["User space"]
  node_monitor["Monitor<br/>stdout bridge<br/>[monitor.c]"]
  node_graph_engine["Graph engine<br/>topology runtime<br/>[graphengine.py]"]
  node_provenance["Provenance<br/>event model<br/>[provenance.py]"]
  node_networkx(("NetworkX<br/>graph library"))
  node_clc_daemon["CLC daemon<br/>[clc_daemon.py]"]
  node_makefile["Build"]
  node_requirements["Python deps<br/>runtime deps<br/>[requirements.txt]"]
  node_readme["README<br/>workflow spec<br/>[README.md]"]
  node_clang_llvm(("Clang/LLVM<br/>toolchain"))
end

subgraph group_viz["Visualization"]
  node_html_graph["HTML graph<br/>persisted artifact"]
  node_gui["GUI<br/>front end<br/>[kguard_gui.py]"]
  node_viewer["Graph viewer<br/>[view_graph.py]"]
end

subgraph group_analytics["Analytics"]
  node_ml_detector["ML detector<br/>analytics<br/>[ml_detector.py]"]
end

node_kernel_bpf -->|"kernel events"| node_monitor
node_monitor -->|"event stream"| node_graph_engine
node_graph_engine -->|"parse model"| node_provenance
node_provenance -->|"graph objects"| node_networkx
node_networkx -->|"autosave"| node_html_graph
node_html_graph -->|"open graph"| node_gui
node_html_graph -->|"load graph"| node_viewer
node_graph_engine -.->|"telemetry feed"| node_ml_detector
node_makefile -->|"build probe"| node_kernel_bpf
node_makefile -->|"build binary"| node_monitor
node_makefile -->|"package app"| node_graph_engine
node_makefile -.->|"toolchain"| node_clang_llvm
node_kernel_bpf -.->|"load/manage"| node_libbpf
node_kernel_bpf -.->|"btf support"| node_bpftool
node_requirements -.->|"python deps"| node_graph_engine
node_requirements -.->|"python deps"| node_ml_detector
node_readme -.->|"run flow"| node_monitor
node_readme -.->|"pipe input"| node_graph_engine
node_readme -.->|"saved output"| node_html_graph
node_clc_daemon -.->|"adjacent service"| node_graph_engine

click node_kernel_bpf "https://github.com/knox1837/k-guard/blob/main/src/kernel/kguard.bpf.c"
click node_monitor "https://github.com/knox1837/k-guard/blob/main/src/user/monitor.c"
click node_graph_engine "https://github.com/knox1837/k-guard/blob/main/src/user/graphengine.py"
click node_provenance "https://github.com/knox1837/k-guard/blob/main/src/user/provenance.py"
click node_gui "https://github.com/knox1837/k-guard/blob/main/kguard_gui.py"
click node_viewer "https://github.com/knox1837/k-guard/blob/main/view_graph.py"
click node_ml_detector "https://github.com/knox1837/k-guard/blob/main/ml_detector.py"
click node_clc_daemon "https://github.com/knox1837/k-guard/blob/main/src/user/clc_daemon.py"
click node_makefile "https://github.com/knox1837/k-guard/tree/main/Makefile"
click node_requirements "https://github.com/knox1837/k-guard/blob/main/requirements.txt"
click node_readme "https://github.com/knox1837/k-guard/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_kernel_bpf,node_libbpf,node_bpftool toneBlue
class node_monitor,node_graph_engine,node_provenance,node_networkx,node_clc_daemon,node_makefile,node_requirements,node_readme,node_clang_llvm toneAmber
class node_html_graph,node_gui,node_viewer toneMint
class node_ml_detector toneRose
```

## Components

### Kernel space

eBPF instrumentation inside the Linux kernel

- [eBPF probe](https://github.com/knox1837/k-guard/blob/main/src/kernel/kguard.bpf.c): kernel sensor · Kernel-space eBPF program that captures runtime events with kernel context. · `src/kernel/kguard.bpf.c`
- **libbpf**: ebpf runtime · Library and tooling layer used to load and manage the kernel eBPF program.
- **bpftool**: kernel tool · Tooling used during the eBPF build and kernel metadata generation flow.

### User space

Runtime collection and graph construction

- [Monitor](https://github.com/knox1837/k-guard/blob/main/src/user/monitor.c): stdout bridge · User-space companion binary that receives kernel events and emits a record stream. · `src/user/monitor.c`
- [Graph engine](https://github.com/knox1837/k-guard/blob/main/src/user/graphengine.py): topology runtime · Main Python orchestration layer that consumes the event stream and maintains the live behavioral graph. · `src/user/graphengine.py`
- [Provenance](https://github.com/knox1837/k-guard/blob/main/src/user/provenance.py): event model · Semantic data model for translating raw observations into lineage and relationship records. · `src/user/provenance.py`
- **NetworkX**: graph library · In-memory graph library used by the Python engine to build and update topology.
- [CLC daemon](https://github.com/knox1837/k-guard/blob/main/src/user/clc_daemon.py): service · Additional user-space daemon component adjacent to the main monitoring pipeline. · `src/user/clc_daemon.py`
- [Build](https://github.com/knox1837/k-guard/tree/main/Makefile): build system · Coordinates compilation of the kernel eBPF program, user-space binary, and supporting assets. · `Makefile`
- [Python deps](https://github.com/knox1837/k-guard/blob/main/requirements.txt): runtime deps · Python package requirements for the graphing and analysis components. · `requirements.txt`
- [README](https://github.com/knox1837/k-guard/blob/main/README.md): workflow spec · Documents the runtime pipeline and how to launch the streaming monitor into the graph engine. · `README.md`
- **Clang/LLVM**: toolchain · Compilation toolchain used for building the eBPF and user-space components.

### Visualization

Persisted graph output and front ends

- **HTML graph**: persisted artifact · Auto-saved interactive graph file that can be reopened independently of the live process.
- [GUI](https://github.com/knox1837/k-guard/blob/main/kguard_gui.py): front end · Convenience graphical front end for viewing the generated graph. · `kguard_gui.py`
- [Graph viewer](https://github.com/knox1837/k-guard/blob/main/view_graph.py): viewer · Command-line or lightweight viewer for opening the exported graph artifact. · `view_graph.py`

### Analytics

Optional downstream analysis

- [ML detector](https://github.com/knox1837/k-guard/blob/main/ml_detector.py): analytics · Optional analysis component for anomaly detection or classification on monitoring data. · `ml_detector.py`

## Connections

- 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.
