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

15 KiB
Raw Permalink Blame History

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

# 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

  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

# 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