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>
15 KiB
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
execveandexecveat(fexecve/memfd) tracepoints; procfs polling is the fallback - Every event is resolved through
/proc/<pid>/exe:executable_pathis what actually ran,image_pathpins the inode for hashing/scanning, andexecutable_deleted/executable_memfdflag fileless or unlinked images - Process identity:
make_process_node_id()buildsprocess_<pid>_<boot8>_<starttime>from/proc/<pid>/statfield 22 and the boot ID, so PID reuse does not merge unrelated processes (legacyprocess_<pid>when no start time is known) - BPF timestamps use
CLOCK_BOOTTIMEand 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>/exescans scan_process_memory(pid)viayr_rules_scan_proc(needsCAP_SYS_PTRACE, or being the parent under yamaptrace_scope≤ 1)YaraMatch::severitycomes frommeta.severity, elsemeta.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) andDeletedExecutable(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_memorystoresource=prevention|behavior|memoryevidence; memory scans use a separate scanner instance under their own mutex so slow scans never block exec decisionsset_detection_callbackreports stored detections to the daemon (auto-containment)
Policy (policy.hpp/cpp)
PolicyStore:policy.jsonv2 (next to the DB) with feeds (kindyara|hashes|domains|ips|nets), allowlist, containment, quarantine, protection settings, history andremoved_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 injectableFetcher(tests use a fake); GitHub release digest verification, safe extraction, compile check viaYaraScanner::check_rules, atomiccurrentswitch,state.json, thenreload-rules- Run by
strawberry --update-rulesfromstrawberry-update.service(daily timer, path trigger)
OpenSnitch (opensnitch.hpp/cpp)
- Detects the rules dir and
EnableChecksums; writes onlystrawberry-*.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_FILESYSTEMper 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_eventsring buffer:connect(AF_INET/6),ptraceattach/seize,init_module/finit_module FileWatcher: fanotifyFAN_REPORT_DFID_NAMEover persistence and drop directories (needs file handles; not overlayfs)BehaviorEnginerules 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-removeby hash (path from stored evidence),scan-memoryandprocess-suspend/resume/killby stable node id re-verified withresolve_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/cgroupcpu.maxcapacity), RSS vs budget (profile, capped by cgroupmemory.max), host PSIsome avg10(loadavg fallback) andMemAvailable - Level
normal/warning/critical/emergencywith 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 perbackground_max_deferral_sguard_should_degrade(bytes): hash/IOC/quarantine only for files over the profile cap or under pressure (profile-dependent); degraded results are not cachedpace_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) → statustimings- Tracy:
meson setup -Denable_profiling=true(needstracyvia pkg-config ormeson wrap install tracy); macros inprofiling.hpp(STRAWBERRY_ZONE,STRAWBERRY_PLOT,STRAWBERRY_THREAD_NAME) are no-ops otherwise - Constrained-lane KPI:
make perf-kpi LABEL=xruns 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 withMANIFEST,evidence/andtelemetry/zstd segments; queries come from an in-memory view rebuilt on open - A legacy unqlite-format
database.dbfile is imported on the first writer open and kept asdatabase.db.migrated-<ts> - Graph structures: GraphNode and GraphEdge
- Indicator storage with metadata
- Single writer enforced with
flockon<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
# 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)
class Component {
private:
class Impl;
std::unique_ptr<Impl> pimpl_;
};
Benefits: Hide implementation, reduce compilation dependencies
State Machine
class MonitoringState : public DaemonState {
void react(ScanEvent const & event) override;
};
Benefits: Type-safe transitions, clear state flow
Observer (Callbacks)
monitor->start([this](const ProcessInfo& info) {
this->handle_process(info);
});
Benefits: Decoupled components, flexible event handling
Testing
Run tests:
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:
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).
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
- Fork the repository
- Create a feature branch
- Write tests for new features
- Ensure all tests pass
- Submit pull request
Code Style
- Use C++23 features appropriately
- Follow RAII for resource management
- Prefer
std::unique_ptrover raw pointers - Use const correctness
- Classes: PascalCase
- Functions: snake_case
- Members: snake_case_ (trailing underscore)
Debugging
# 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
- Define state class in
daemon_states.hpp - Implement
entry()and event handlers - Add transitions in existing states
Adding a Component
- Create header in
include/strawberry/ - Use PIMPL pattern for implementation hiding
- Add implementation in
src/ - Update
src/meson.build