# 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//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___` from `/proc//stat` field 22 and the boot ID, so PID reuse does not merge unrelated processes (legacy `process_` 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//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/-x/kpi.json`; `scripts/perf_kpi_report.py --compare A B` **Database** (`database.hpp/cpp`) - Backed by the event store (`src/store/`): `` 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-` - Graph structures: GraphNode and GraphEdge - Indicator storage with metadata - Single writer enforced with `flock` on `.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 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= 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/`, 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//{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`