strawberry/DEVELOPER.md
trvon caf52de559
Add a macOS CI job and document the port
The macos job (macos-15, Homebrew deps, Qt app skipped) builds and
runs meson test. It only runs on GitHub: Forgejo also reads
.github/workflows and has no macOS runner.

README: macOS build, the Linux to macOS backend map, ES requirements
and installed files. API_CONTRACT: macOS socket path and peer
credentials, the endpoint_security and libproc backend values, and
the macOS status fields. DEVELOPER: platform map and the GitHub +
Forgejo remotes. AGENTS: current state of the port, including that
the ES backends have not run live yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 20:53:27 -06:00

283 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Developer Guide
## Architecture
Strawberry uses a **state machine** pattern with TinyFSM to manage daemon lifecycle:
```
┌─────┐ start ┌──────────┐ monitor ┌───────────┐
│Idle │────────→ │Initialize│─────────→ │Monitoring │
└─────┘ └──────────┘ └─────┬─────┘
│ update
↓
┌──────────┐
│Updating │
└─────┬────┘
│
↓
┌──────────┐
│Shutdown │
└──────────┘
```
## Code Structure
### Core Components
**State Machine** (`daemon_states.hpp/cpp`)
- Defines 5 states with type-safe transitions
- Events: StartEvent, MonitorEvent, UpdateRulesEvent, ScanEvent, StopEvent
**Process Monitor** (`process_monitor.hpp/cpp`, `bpf/process_monitor.bpf.c`)
- PIMPL pattern hides BPF implementation details
- libbpf backend hooks `execve` and `execveat` (fexecve/memfd) tracepoints; procfs polling is the fallback
- Every event is resolved through `/proc/<pid>/exe`: `executable_path` is what actually ran, `image_path` pins the inode for hashing/scanning, and `executable_deleted` / `executable_memfd` flag fileless or unlinked images
- Process identity: `make_process_node_id()` builds `process_<pid>_<boot8>_<starttime>` from `/proc/<pid>/stat` field 22 and the boot ID, so PID reuse does not merge unrelated processes (legacy `process_<pid>` when no start time is known)
- BPF timestamps use `CLOCK_BOOTTIME` and are converted to wall clock so both backends share one clock
- Both backends can emit a startup inventory of already-running processes
**YARA Scanner** (`yara_scanner.hpp/cpp`)
- Rule loading and compilation
- Staleness detection via timestamp tracking
- Multiple sources, each feed in its own namespace; file, fd and in-memory buffer scans; `/proc/<pid>/exe` scans
- `scan_process_memory(pid)` via `yr_rules_scan_proc` (needs `CAP_SYS_PTRACE`, or being the parent under yama `ptrace_scope` ≤ 1)
- `YaraMatch::severity` comes from `meta.severity`, else `meta.score` (≥90 critical, ≥70 high, ≥40 medium, else low)
**Detection Pipeline** (`detection_pipeline.hpp/cpp`)
- Refuses to start without compiled rules unless `require_rules=false`, and without a writable database
- Caches scan results by file identity (dev/inode/size/mtime) so repeated execs of the same binary are cheap
- Writes each event's nodes/edges/indicators in one transaction
- Heuristic indicators (`source=heuristic`): `MemfdExecution` (high) and `DeletedExecutable` (low)
- Correlation is batched (`run_pending_correlation()`, every ~2 s from the daemon loop, flushed on shutdown)
- IOC hash set (`ioc_set.hpp`) checked for every image → `IOC_KnownMalwareHash` (`source=ioc`); MD5 is computed from the same in-memory copy for OpenSnitch
- `assess_exec(fd, path)` serves the exec guard (reads the fanotify event fd, never reopens the path; hash-only when prevention is off, to enforce quarantines)
- `record_exec_decision`, `record_behavior`, `scan_process_memory` store `source=prevention|behavior|memory` evidence; memory scans use a separate scanner instance under their own mutex so slow scans never block exec decisions
- `set_detection_callback` reports stored detections to the daemon (auto-containment)
**Policy** (`policy.hpp/cpp`)
- `PolicyStore`: `policy.json` v2 (next to the DB) with feeds (kind `yara|hashes|domains|ips|nets`), allowlist, containment, quarantine, protection settings, history and `removed_defaults`; strict validation of control-socket payloads; `match()` used by the pipeline to suppress allowlisted detections; `generation()` bumps on every save (exec-guard cache key)
- Helpers shared by daemon/CLI/updater: `policy_path_for`, `feeds_dir_for`, `installed_feed_roots`, `read_feed_state`, `request_feed_update`
**Rule updater** (`rule_updater.hpp/cpp`, needs libcurl + libarchive)
- `update_feeds()` behind an injectable `Fetcher` (tests use a fake); GitHub release digest verification, safe extraction, compile check via `YaraScanner::check_rules`, atomic `current` switch, `state.json`, then `reload-rules`
- Run by `strawberry --update-rules` from `strawberry-update.service` (daily timer, path trigger)
**OpenSnitch** (`opensnitch.hpp/cpp`)
- Detects the rules dir and `EnableChecksums`; writes only `strawberry-*.json` (0600, atomic); list rules (`lists.domains/ips/nets`) and per-binary containment rules (`process.path` + `process.hash.md5`); `is_protected_system_path()` is the shared never-auto-block check
**Exec guard** (`exec_guard.hpp/cpp`)
- fanotify `FAN_CLASS_CONTENT` + `FAN_OPEN_EXEC_PERM`, `FAN_MARK_FILESYSTEM` per local mount; reader thread, scan workers, deadline watchdog (fail open), each event answered exactly once; verdict cache keyed by dev/ino/size/mtime + generation; own-pid bypass
- `decide_exec()` is the pure verdict function (unit-tested): quarantine → block in any mode; allowlist → allow; system path → would-block only; enforce/audit otherwise
**Behavior** (`behavior_engine.hpp/cpp`, `file_watch.hpp/cpp`)
- eBPF `behavior_events` ring buffer: `connect` (AF_INET/6), `ptrace` attach/seize, `init_module`/`finit_module`
- `FileWatcher`: fanotify `FAN_REPORT_DFID_NAME` over persistence and drop directories (needs file handles; not overlayfs)
- `BehaviorEngine` rules with injected resolve/is_flagged/ioc_ip/emit: `IOC_Connection`, `FlaggedProcessNetwork`, `PtraceAttach`, `KernelModuleLoad`, `PersistenceWrite`, `DownloadThenExecute`; `resolve_process_ref(pid)` gives the stable node id of a live process
**Daemon response** (`daemon_app.cpp`)
- Auto-containment from the detection callback; blocklist sync after reloads; exec guard lifecycle follows `prevention_mode` (and stays up while anything is quarantined)
- Response verbs: `quarantine`/`quarantine-remove` by hash (path from stored evidence), `scan-memory` and `process-suspend/resume/kill` by stable node id re-verified with `resolve_process_ref`, protected-process refusal list
- Background memory-scan queue (≤ 32, one at a time): memfd/deleted execs, ptrace targets, operator requests
**Resource governor** (`resource_governor.hpp/cpp`, `thread_priority.hpp/cpp`)
- Governor thread (`governor_tick_ms`, default 1 s) samples own CPU (share of affinity/cgroup `cpu.max` capacity), RSS vs budget (profile, capped by cgroup `memory.max`), host PSI `some avg10` (loadavg fallback) and `MemAvailable`
- Level `normal/warning/critical/emergency` with hysteresis (escalate 500 ms; release 150 ms CPU / 1000 ms memory); host busy with a 0.75 release band, severe at 2× a threshold or MemAvailable < 5%
- `admit(WorkClass)`: exec guard always; exec scans deferred only at emergency; background classes deferred while busy/warning, never forced at critical, otherwise forced once per `background_max_deferral_s`
- `guard_should_degrade(bytes)`: hash/IOC/quarantine only for files over the profile cap or under pressure (profile-dependent); degraded results are not cached
- `pace_read(bytes)`: token bucket for background reads (halved under pressure), sleeps in ≤ 200 ms slices
- Parsers are pure functions; sampler, clock and sleeper are injectable (`tests/test_resource_governor.cpp`)
| Profile | pipeline / guard workers | read MB/s | max image / guard full scan | YARA timeout | memory scans | inventory | own CPU high | PSI cpu/io/mem | budget | priority |
|---|---|---|---|---|---|---|---|---|---|---|
| efficient | 1 / 1 | 16 | 64 / 16 MiB | 5 s | 10 s, queue 4 | 200 ms | 10% | 20/15/5 | 256 MiB | nice 19, io idle |
| balanced | 1 / 2 | 48 | 128 / 32 MiB | 10 s | 20 s, queue 8 | 50 ms | 25% | 40/30/10 | 512 MiB | nice 10, io be 7 |
| aggressive | 2 / 2 | ∞ | 256 / 64 MiB | 30 s | 30 s, queue 32 | none | 50% | 70/50/20 | 1 GiB | nice 0 |
**Profiling**
- `PerfStats` (`perf_stats.hpp`): lock-free log2 histograms (exec decision, exec assess, queue wait, image scan, YARA, image size, DB commit, correlation, rule compile, memory scan) → status `timings`
- Tracy: `meson setup -Denable_profiling=true` (needs `tracy` via pkg-config or `meson wrap install tracy`); macros in `profiling.hpp` (`STRAWBERRY_ZONE`, `STRAWBERRY_PLOT`, `STRAWBERRY_THREAD_NAME`) are no-ops otherwise
- Constrained-lane KPI: `make perf-kpi LABEL=x` runs the daemon with the installed YARA Forge rules in a privileged container capped at 2 CPUs / 2 GiB (startup inventory, idle, exec storm under CPU load, large binaries, rule reload) → `build/perf/<stamp>-x/kpi.json`; `scripts/perf_kpi_report.py --compare A B`
**Database** (`database.hpp/cpp`)
- Backed by the event store (`src/store/`): `<db_path>` is a directory with `MANIFEST`, `evidence/` and `telemetry/` zstd segments; queries come from an in-memory view rebuilt on open
- A legacy unqlite-format `database.db` file is imported on the first writer open and kept as `database.db.migrated-<ts>`
- Graph structures: GraphNode and GraphEdge
- Indicator storage with metadata
- Single writer enforced with `flock` on `<db>.lock`; `open_read_only()` for queries never writes back
- `begin_transaction()` / `commit_transaction()` batch writes into one persist
**Hash Utils** (`hash_utils.hpp/cpp`)
- SHA256 and MD5 implementations using OpenSSL
- File and buffer hashing support
**Config** (`config.hpp/cpp`)
- Simple key=value parser
- Default configuration values
## Building
```bash
# Debug build
meson setup builddir --buildtype=debug
meson compile -C builddir
# Release build
meson setup builddir --buildtype=release
meson compile -C builddir
# With tests
meson setup builddir -Denable_tests=true
meson compile -C builddir
meson test -C builddir
```
## Design Patterns
**PIMPL (Pointer to Implementation)**
```cpp
class Component {
private:
class Impl;
std::unique_ptr<Impl> pimpl_;
};
```
Benefits: Hide implementation, reduce compilation dependencies
**State Machine**
```cpp
class MonitoringState : public DaemonState {
void react(ScanEvent const & event) override;
};
```
Benefits: Type-safe transitions, clear state flow
**Observer (Callbacks)**
```cpp
monitor->start([this](const ProcessInfo& info) {
this->handle_process(info);
});
```
Benefits: Decoupled components, flexible event handling
## Testing
Run tests:
```bash
meson test -C builddir --verbose
```
Add new tests to `tests/` directory following existing patterns.
Invariant (property) tests: `tests/test_invariants.cpp` checks properties
that must hold for every input on thousands of seeded random cases per run —
exec decisions (quarantine always blocks; allowlist, system paths and
non-enforce modes never auto-block; monotone in severity), histogram
percentiles, IOC network matching vs a brute-force reference, IOC list
normalization (bounded, valid, idempotent), governor parsers and admission,
and untrusted policy/status JSON. A failure prints the seed; reproduce with
`STRAWBERRY_PROPERTY_SEED=<seed> builddir/tests/test_invariants`.
Fuzzing (libFuzzer + ASan/UBSan, clang): `make fuzz` (or `FUZZ_SECONDS=300
make fuzz`) builds `fuzz/` in `build/fuzz` and runs each target in turn at
nice 19 with RSS/malloc caps. Targets cover every boundary that parses
untrusted input: `fuzz_ioc_list` (feed bodies, IOC set loading),
`fuzz_policy_apply` (control-socket payload verbs; accepted policy must
reload), `fuzz_governor_parsers` (/proc, PSI, cgroup), `fuzz_status_snapshot`
(client-side status parsing), `fuzz_config`, `fuzz_mcp_handle` (agent
JSON-RPC, read-only). Seeds live in `fuzz/seeds/<target>`, corpora in
`build/fuzz-corpus`, crashes in `build/fuzz-artifacts`. Add a target for any
new parser of untrusted input.
Root-only tests (fanotify exec prevention + quarantine, eBPF behavior events,
persistence watcher, process-memory scan) skip when not root. Run them in a
privileged container:
```bash
make docker-live-tests # scripts/run_live_tests_docker.sh
```
## Platforms
Linux and macOS share one tree. Platform code sits behind `#if defined(__linux__)`
/ `#if defined(__APPLE__)`; a Linux branch is never changed to serve macOS.
| Piece | Linux | macOS |
| --- | --- | --- |
| Process facts | `/proc/<pid>/{exe,stat,cmdline}` | `include/strawberry/platform_process.hpp` (libproc, sysctl `KERN_PROC_PID`, `KERN_PROCARGS2`) |
| Process identity | start ticks + `boot_id` | start time (µs since epoch) + `kern.bootsessionuuid` |
| Exec events | eBPF (`src/bpf/`) or procfs polling | Endpoint Security or libproc polling (`process_monitor.cpp`) |
| Exec prevention | fanotify `FAN_OPEN_EXEC_PERM` | ES `AUTH_EXEC` (`exec_guard.cpp`) |
| File watch | fanotify `FAN_REPORT_DFID_NAME` | ES notify events, inverted target-path muting (`file_watch.cpp`) |
| Resource sampler | `/proc`, PSI, cgroup v2 | Mach `task_info`/`host_statistics64`, `getloadavg` (`resource_governor.cpp`) |
| Durable sync | `fdatasync` | `fcntl(F_FULLFSYNC)` (`sys_io.hpp`) |
| Peer credentials | `SO_PEERCRED` | `LOCAL_PEERCRED` + `LOCAL_PEERPID` |
ES helpers are in `src/platform/es_support.hpp`. ES handlers are clang blocks
(`-fblocks`, added by the `enable_endpoint_security` meson option); every
handler is `noexcept` and records swallowed exceptions with
`STRAWBERRY_NOTE_SWALLOWED()`. Tests that pass a synthetic procfs root
(`STRAWBERRY_PROCFS_ROOT`) still use the procfs code on macOS.
Checks per platform:
- macOS: `make test`; root-only ES checks: `make macos-live-tests` (needs the
ES entitlement; ad hoc signing works only with SIP disabled).
- Linux: `make test`, `make docker-live-tests`, `make fuzz`.
## Remotes
`origin` fetches from GitHub and pushes to GitHub and Forgejo. GitHub runs
the macOS CI job; Forgejo skips it (`github.server_url` gate in
`.github/workflows/build.yml`).
```bash
git remote add origin git@github.com:trvon/strawberry.git
git remote set-url --add --push origin git@github.com:trvon/strawberry.git
git remote set-url --add --push origin ssh://git@git.trevon.dev:2222/trevon/strawberry.git
git remote add forgejo ssh://git@git.trevon.dev:2222/trevon/strawberry.git
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass
5. Submit pull request
### Code Style
- Use C++23 features appropriately
- Follow RAII for resource management
- Prefer `std::unique_ptr` over raw pointers
- Use const correctness
- Classes: PascalCase
- Functions: snake_case
- Members: snake_case_ (trailing underscore)
## Debugging
```bash
# GDB
gdb builddir/src/strawberry
(gdb) break main
(gdb) run config/strawberry.conf
# Valgrind
valgrind --leak-check=full builddir/src/strawberry
```
## Extending
### Adding a New State
1. Define state class in `daemon_states.hpp`
2. Implement `entry()` and event handlers
3. Add transitions in existing states
### Adding a Component
1. Create header in `include/strawberry/`
2. Use PIMPL pattern for implementation hiding
3. Add implementation in `src/`
4. Update `src/meson.build`