Fault detection and integrity monitoring for kernel isolation structures
docs: add README.md for 18 packages missing documentation
Add READMEs for: ocaml-fdir, ocaml-initramfs, ocaml-jailhouse,
ocaml-linkedin, ocaml-openamp, ocaml-pid1, ocaml-rpmsg, ocaml-sbom,
ocaml-slack, ocaml-vz, ocaml-zephyr, space, space-block, space-ground,
space-net, space-sim, space-test, space-wire.
+48
+48
README.md
+48
README.md
···
1
+
# fdir
2
+
3
+
Integrity monitoring for kernel isolation structures.
4
+
5
+
Periodic integrity checker that takes known-good snapshots of kernel isolation
6
+
structures (page tables, seccomp filters, cgroup configs, memory mappings) at
7
+
boot and detects radiation-induced corruption by comparing against them on a
8
+
configurable timer. Designed for space-grade Linux systems where single-event
9
+
upsets can silently corrupt kernel state.
10
+
11
+
The library hashes `/proc/self/maps`, `/proc/self/status`, and
12
+
`/proc/self/cgroup` using SHA-256 and runs as an Eio daemon fiber that
13
+
periodically re-checks against the baseline. Anomalies are classified by
14
+
severity (Log, Isolate, Restart, Degrade, Safe_mode) based on how many
15
+
subsystems have diverged.
16
+
17
+
## Installation
18
+
19
+
```
20
+
opam install fdir
21
+
```
22
+
23
+
## Usage
24
+
25
+
```ocaml
26
+
Eio_main.run @@ fun env ->
27
+
Eio.Switch.run @@ fun sw ->
28
+
let clock = Eio.Stdenv.clock env in
29
+
let fs = Fdir.Procfs.live () in
30
+
let baseline = Fdir.snapshot ~clock fs in
31
+
let config = Fdir.Config.v ~interval:30.0 () in
32
+
Fdir.start_daemon ~sw ~clock ~config ~baseline ~fs
33
+
~on_anomaly:Fdir.default_handler ()
34
+
```
35
+
36
+
## API
37
+
38
+
- **`Procfs`** -- Data source abstraction. `Procfs.live ()` reads from real
39
+
`/proc`; `Procfs.mock` provides canned data for testing.
40
+
- **`snapshot`** -- Takes a SHA-256 snapshot of all monitored subsystems.
41
+
- **`check`** -- Compares current state against a baseline snapshot, returning
42
+
`Ok` or `Anomaly` with a list of divergent subsystems.
43
+
- **`Config`** -- Configures the check interval (default 30s) and which
44
+
subsystems to monitor (Memory_maps, Seccomp, Cgroups).
45
+
- **`start_daemon`** -- Forks an Eio daemon fiber that runs periodic checks
46
+
and invokes a handler on anomalies.
47
+
- **`default_handler`** -- Returns `Log` for 1 anomaly, `Degrade` for 2, and
48
+
`Safe_mode` for 3+.