Fault detection and integrity monitoring for kernel isolation structures
ocaml-linkedin: apply dune fmt
Pure formatting changes from `dune fmt`: doc comment placement moves
from above the binding to below it for `type`s, multi-line `match`
expressions collapse onto one line where they fit, and infix operator
applications pick up spaces (`Soup.($?)` -> `Soup.( $? )`). No
semantic changes.
+78
-20
+71
-20
README.md
+71
-20
README.md
···
16
16
17
17
## Installation
18
18
19
+
Install with opam:
20
+
21
+
```sh
22
+
$ opam install fdir
19
23
```
20
-
opam install fdir
24
+
25
+
If opam cannot find the package, it may not yet be released in the public
26
+
`opam-repository`. Add the overlay repository, then install it:
27
+
28
+
```sh
29
+
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
30
+
$ opam update
31
+
$ opam install fdir
21
32
```
22
33
23
34
## Usage
35
+
36
+
### Snapshot at boot, check on demand
37
+
38
+
Take a baseline early in startup, then compare the live state against it
39
+
whenever you want to verify that nothing has drifted:
24
40
25
41
```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 ()
42
+
let () =
43
+
Eio_main.run @@ fun env ->
44
+
let clock = Eio.Stdenv.clock env in
45
+
let fs = Fdir.Procfs.live () in
46
+
let baseline = Fdir.snapshot ~clock fs in
47
+
(* ... application runs, then later: *)
48
+
match Fdir.check ~baseline ~clock fs with
49
+
| Fdir.Ok _ -> ()
50
+
| Fdir.Anomaly { anomalies; _ } ->
51
+
List.iter
52
+
(fun a -> Fmt.epr "drift on %a@." Fdir.pp_subsystem a.Fdir.subsystem)
53
+
anomalies
54
+
```
55
+
56
+
### Monitor continuously
57
+
58
+
`start_daemon` forks an Eio fiber that calls `check` on a timer and invokes
59
+
a handler on anomalies. The handler returns a `severity` that the
60
+
application can use to decide between logging, isolating, restarting, or
61
+
dropping to safe mode.
62
+
63
+
```ocaml
64
+
let () =
65
+
Eio_main.run @@ fun env ->
66
+
Eio.Switch.run @@ fun sw ->
67
+
let clock = Eio.Stdenv.clock env in
68
+
let fs = Fdir.Procfs.live () in
69
+
let baseline = Fdir.snapshot ~clock fs in
70
+
let config = Fdir.Config.v ~interval:30.0 () in
71
+
Fdir.start_daemon
72
+
~sw ~clock ~config ~baseline ~fs
73
+
~on_anomaly:Fdir.default_handler
74
+
()
34
75
```
35
76
77
+
`Fdir.default_handler` returns `Log` for 1 anomaly, `Degrade` for 2, and
78
+
`Safe_mode` for 3+.
79
+
36
80
## API
37
81
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+.
82
+
### Snapshot / check
83
+
84
+
- `Fdir.snapshot ~clock fs` -- SHA-256 snapshot of all monitored subsystems.
85
+
- `Fdir.check ~baseline ~clock fs` -- `Ok` or `Anomaly { anomalies; _ }`
86
+
listing divergent subsystems.
87
+
- `Fdir.Procfs.live ()` reads real `/proc`; `Fdir.Procfs.mock ~maps
88
+
~status ~cgroups` supplies canned data for tests.
89
+
90
+
### Daemon
91
+
92
+
- `Fdir.start_daemon ~sw ~clock ~config ~baseline ~fs ~on_anomaly ()`
93
+
- `Fdir.Config.v ?interval ?subsystems ()` -- defaults are 30s and all
94
+
three subsystems (`Memory_maps`, `Seccomp`, `Cgroups`).
95
+
96
+
### Severity
97
+
98
+
`Log | Isolate | Restart | Degrade | Safe_mode` -- pretty-printed by
99
+
`Fdir.pp_severity`.
+4
dune
+4
dune
+2
dune-project
+2
dune-project