The gate's own documentation claimed more than the tool did, in ways that mattered once the integrity checks landed. - "passes only if all 9 cells pass" was enforced by scripts, not by the gate; it is now enforced (previous commit) and the text says which criterion the tool applies: complete evidence, refused false, every pooled cell passing. - The model digest proves agreement ACROSS reports. It cannot prove that the file on disk now is the one that was evaluated. Corrected everywhere. - The remedy was described inconsistently: cutting the training bundles earlier is NOT enough (evaluation still replays the whole store), a bounded evaluation range is required. Written consistently, with --eval-after NS|auto. - scripts/fleet_e2e.sh asserted three gate checks; promotion_gate emits five. It now asserts >= 5, requires the provenance fields, and adds the honest-evidence invariant: today every cell is in-sample, so at least one cell must report in_sample true, none may pass, and each must carry the out-of-sample failure. A pass over in-sample cells is itself a failure. - The Salt/range runbooks advertised the flow as producing promotion evidence; it collects gate INPUT, and a passing verdict requires out-of-sample windows.
30 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/ctime) so repeated execs of the same binary are cheap. ctime is in the key because mtime is settable (
utimensat): a rewrite that restores size and mtime (cp -p, install -p, package restore, a deliberate attacker) still changes ctime and is re-scanned instead of serving the old verdict. Cached size refusals stay unscanned and never trigger a fallback full-file hash; an already-known SHA remains available for IOC checks. The exec guard does not treat a cached size refusal as a YARA result: its own bounded scan/degradation policy still applies. - 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, best-effort flush on shutdown). Final-flush exceptions are counted and recorded without allocation; resources still close, and startup rebuilds from persisted raw evidence. Ordinary evidence stays incremental; startup and explicit allowlist add/remove/maintenance requests rebuild from raw indicators and an immutable allowlist snapshot. An epoch rejects work invalidated during computation. Rebuilds upsert replacements before retiring unsupported findings of this engine in one view transaction, preserving history and other engines; failures roll back the view and schedule a full retry rather than losing consumed deltas. Large transactions retain the store's existing multi-block disk semantics (not a new crash-atomic snapshot guarantee). - Immediate allowlist cleanup of this engine's findings checks complete actual indicator support with
(hash, path, rule), never a substituted IOC rule; missing or capped support is conservatively left for the rebuild. Cleared members cannot rejoin incremental outputs, while allowlist removal restores the retained raw evidence. - Full persistence is shared by the daemon rebuild and
CorrelationEngine::correlate, including the legacy offline correlate entrypoint, so typed-id migration cannot leave an old unqualified aggregate behind on the offline path. Standalone calls own a view transaction; calls inside an existing transaction do not commit or roll back the caller's work. The legacy CLI reads an immutable allowlist snapshot before opening a writer; missing policy means no allowlist, inaccessible/corrupt policy fails, andPolicyStore::load_read_onlynever seeds or migrates a policy. This is a read-only loader, not a capability restriction on later explicit mutation APIs. - Shared-rule groups use
(source domain, namespace, rule name); demo normalizes to YARA. Legacy missing namespaces stay unknown and keep legacy YARA ids, but do not merge with known namespaces. Other ids encode typed length-prefixed fields. Metadatarule_source/rule_namespacemakes the scope explicit; full rebuilds retire obsolete unqualified ids. Lineage/hash/rule counts distinguish stable process instances from numeric PIDs. - 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 rules fetchfromstrawberry-update.service(daily timer, path trigger); on macOS fromcom.strawberry.updateas_strawberry
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/ctime + 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 processobserve_process(info)captures a stable exec/inventory identity before scan queueing, in bounded in-memory windows only. Ordinary connects add no procfs I/O. Network-to-write joins require that observed lifetime, a nonzero exec timestamp, and matching resolved writer node; connections predating its observation cannot be assigned to a reused PID. Unobserved/unknown/late identities are unjoined (a coverage limitation, not proof of benignity); direct IOC/flagged-network rules remain enabled. At most 8192 windows × 64 connections are retained, with single-window eviction rather than clear-all on churn.
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
Inspection learning (Stage 4) (learn/, inspection_executor.hpp/cpp)
- Offline MLP training, live shadow scoring and replay-gated operator promotion; this is budgeted inspection selection, not AlphaZero tree search or an autonomous detector
- Promotion evidence must be out-of-sample.
model train/fleet trainrecord the inclusive window range they trained on; everyreplay --policy-evalcell and every pooledfleet gatecell publishes the model digest (model_sha256), that training range, the evaluated range andin_sample, andpromotion_gate()fails a cell whose ranges overlap or whose model has no recorded range (unprovable, never assumed out-of-sample).fleet gateadditionally refuses a report set with a missing or disagreeing digest and requires the complete 3 seeds x 3 periods matrix (complete,expected_cells; an incomplete or mixed set yields no verdict). Digest agreement is not file provenance: it only shows that the reports in one set judged the same bytes. Cutting the training bundles earlier is not sufficient on its own, because the node still replays its whole store; the evaluation itself has to be bounded (replay --policy-eval --eval-after NS|auto; the replay-side bound and its refusal text are in the tree, the CLI flag is landing in parallel -API_CONTRACT.md). - Offline replay uses seeded, class-weighted positive/unlabeled sampling.
Positives reserve up to one fifth of the sample (at least one); negatives
borrow vacant slots but yield to later positives.
max_entity_sharebounds each root program's combined positive + negative count. A capped entity refreshes its own class reservoir across time instead of freezing early examples. Capped refreshes do not dilute other entities' global candidate counts. Cross-entity positive replacement can evict one negative too, temporarily leaving the sample one short. Slot back-links use swap-and-pop plus geometric shrinking/release of per-entity allocations, with amortized O(1) mutations and allocated slot storage bounded bymax_examples. Debug invariants check capacity as well as logical size. Entity counters last only while retained; the constrained sample is not a uniform joint sample, and unlabeled is not proven benign. - Replay joins final label judgments retrospectively in stored order, not as point-in-time policy replay. An allowlist entry may cover many hashes; removal retires all its bindings, without erasing other entries or idless negatives. Retired-entry tombstones ignore delayed suppression observations; only an explicit operator add reopens that id. Quarantine removal retracts only operator quarantine provenance, not an independent same-text reason. Retraction restores independent evidence; it never invents a positive. Unreadable/malformed label evidence fails visibly. Resolver memory scales with distinct evidence bindings/tombstones, not the example cap; a full replay/training RSS bound still needs measurement.
replay --training-summaryis an opt-in, CLI-only aggregate view of the same resolver and sampler, not a readiness engine or trainer. Ordinary replay keeps collection disabled and addsexamples_collectedto JSON. The summary uses fixed provenance/action buckets and five anonymous concentration counts; metadata does not feed back into label resolution or admission. Effective entity cap and positive quota come from the sampler's own helpers.scan_store_read_onlyretains best-effort record delivery for Database/app/MCP and import callers, but reports skipped/invalid segments, listing/extent availability, actual header status, torn tails, and per segment whether a block could not be decoded (a zstd dictionary this build lacks, or out of memory) or the scan stopped on a complete but invalid block header. Those two are counted per segment because the aggregate tail error keeps only the last one. A genuine short tail an active writer still owns stays tolerated; sealed footer and manifest counts are only compared when every block decoded, so a missing decoder is never reported as corrupt data.replay_storerejects incomplete/corrupt inputs with an explicit failure category and no usable partial report/examples (missing decoder → unavailable, complete invalid header → invalid). This also tightens corrupt-input rejection for offline trainer loader callers; no trainer algorithm/split/model format changes. Ordinary replay retains valid fragment/fallback and active-tail support. The summary additionally requires a current manifest, no torn tail, and matching decoded manifest identity/generation and active extents before/after replay. This is only a cooperative immutable-snapshot observation, not atomic capture or a hostile-filesystem proof. It takes no writer lock and repairs nothing.- Summary mode never uses daemon status to discover the input store: pass a
snapshot path or configure
db_path. Its JSON is one aggregate document; human output has no host identifiers. CLI-localHistogram/ScopedTimer(thePerfStatsprimitives) and Tracy zones record replay and summary-build wall microseconds, separately from deterministic semantics. They do not measure CPU, RSS, or daemon timings.store verify --jsonnow captures successful config chatter; verifierokcan still coexist with skipped-coverage notes, so it is not a substitute for the stricter replay loader. - The telemetry writer owns
ShadowScorer; separate shadow/promoted estimates, bounded pending decisions/actions, and durable acting records before dispatch InspectionExecutorruns one bounded low-priority worker undermodel_inspectadmission. Memory jobs enter the existing queue behind rule/operator requests, retaining stable process identity; deep rescans read paced bounded image copies- Both paths recheck identity/protected processes. The model never directly invokes exec prevention, containment or process actions. R10 forbids direct learning/response dependency coupling outside the CLI/daemon orchestration translation units
contain-removeemits no retraction label, so hash-carryingcontain-addpositives persist in the replay join.process-kill/process-suspendlabels carry only a path and node id (no sha256), so they do not join by hash at all;process-resumealso emits no retraction label. These are documented gaps, not silent reinterpretations.model_shadow=falsedisables both roles. Only models re-promoted under the execution-policy gate may act; old promotion files or a changed scan-profile budget require re-evaluation- Hourly allocation is estimated cost, not measured CPU-time enforcement. Online training, calibrated costs, subtree watching and Stage 5 detections remain future work
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),/proc/diskstatsutilization andMemAvailable. Host pressure is fail-safe: any one signal (CPU, I/O or memory PSI, or lowMemAvailable) is enough to defer background work.host.block_io_util_pctis diagnostic telemetry only and never suppresses I/O PSI, because global PSI also counts waits with no block-device counter (FUSE/network-backed I/O, display page flips); an unknown/new/reset device or an oversized read reports unknown rather than a false idle value - 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 | 64 / 32 MiB | 10 s | 20 s, queue 8 | 50 ms | 25% | 40/30/10 | 768 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, model inspection) → statustimings- Tracy:
meson setup /var/tmp/profbd -Denable_profiling=truebuilds the client fromthird_party/tracy.wrap, pinned to v0.15.0 = the Archtracytools (tracy-capture,tracy-csvexport,tracy-profiler): client and tools must match exactly, so bump both together. On-demand mode: nothing is recorded or paid for unless a capture is connected. Macros inprofiling.hpp(STRAWBERRY_ZONE,STRAWBERRY_PLOT,STRAWBERRY_THREAD_NAME) are no-ops otherwise. Zones cover the daemon scan path (assess_exec,scan_image,scan_on_demand,image.read,image.sha256,yara_scan,rule_compile), correlation/db/governor/model, the tray (tray.*) and evidence reloads. - Headless capture (no GUI, no root):
scripts/profile_capture.sh run OUT -- CMD...orattach OUT SECONDSfor a running profiled daemon/tray →OUT.tracy,OUT.zones.csvand a top-zones table.strawberry-scan-bench --rules DIR FILE... | @list(dev tool) runs the realscan_on_demandpath over files with the real governor, e.g.scripts/profile_capture.sh run /var/tmp/sb-prof/scan -- /var/tmp/profbd/tests/strawberry-scan-bench --rules packaging/rules-snapshot/yara-forge-core @list.txt. Baseline 2026-11-14 (6 yams ASan binaries, 668 MiB, idle host): YARA 86%, read 9%, sha256 5%; ~61 MiB/s end to end; PT_LOAD segments are 35–48% of those files. libyara internals (perf with a symbol build of the same 4.5.8):_yr_scanner_scan_mem_block(Aho-Corasick walk) 59%,yr_re_fast_exec14% +yr_scan_verify_match10% (atom-hit verification), rule compile ~5%. Engine A/B (strawberry-scan-bench --engine, 3434 ELFs / 2.9 GB): fast mode 1.01x (not used), loaded segments only 1.11x (~2x on debug builds; opt-inguard_loaded_segments_only); a-O3 -march=nativeLTO libyara scans ~2.5% slower than Arch's-O2build (the walk is memory-bound), loads rules ~14% faster. - 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 Bbudgets both the phase-end daemon RSS and the per-phase RSS peak against the baseline run, per phase: max(32 MB, 15%) of the last sample, max(64 MB, 15%) of the peak — a peak-only regression fails, and missing RSS samples fail closed.
Rule partitions (rule_partition.hpp/cpp, YaraScanner)
- Why: libyara verifies every atom hit and only checks a rule's
filesize/ header test at the end. YARA-X avoids that by disabling patterns of rules whosefilesizebound or header constraint already fails (audit of itssearch_for_patterns, 2026-11-14) — that, not the language, is why it scanned ~1.6x faster. In the yara-forge pack 1787 rules require MZ and 2498 boundfilesize, so for a big Linux ELF most verification is wasted. - What: after each rules load a background thread splits the sources (lexer-aware;
includeor a rule-count mismatch vs libyara disables it), takes facts from TOP-LEVELandterms only (uint16(0)==0x5a4d/pe.is_pe-> MZ, ELF/Mach-O magic,filesize </<=), and compiles subsets per (MZ / non-MZ) x size bucket (<1, 1-4, 4-16, >=16 MiB). A rule is left out only when a term is provably false for every file in the partition; global rules and rules referenced by kept rules always stay. Subsets are built in priority order (big non-PE first) while their total rule count stays withinrule_partition_budget_pct(100 = ~one extra full set: +59 MiB, 3 subsets); a subset keeping >= 90% of rules is skipped. File/buffer/fd scans pick the subset; process-memory scans use the full set. Compiled subsets are cached underrules_cache_dir/partitions/<sig>/. - Measured (5132 rules): big ASan ELF 1.64x, 1200 system binaries 1.59x, 0 match differences (incl. 348 positive files across MZ/ELF/raw x small/5 MiB). Tests:
test_rule_partition(splitter traps, facts, exclusion soundness, real pack = 5132 rules),test_yara_scannerdifferential (24 file shapes x memory/ranges/fd scans, every subset built), fail-closed;strawberry-scan-bench --partitionsfor real-pack 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
.clangd points editor diagnostics at Meson's builddir/compile_commands.json;
configure the build before relying on C++ editor diagnostics. Docker validation
caps compilation and test parallelism at two jobs to fit its memory limit.
# 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_rule_partition
(rule splitter, condition facts/identifiers, file partition choice),
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 |
| Service manager | systemd units (scripts/*.service) |
launchd jobs (packaging/macos/*.plist) |
| Service hints in messages | include/strawberry/service_hints.hpp |
same header, launchctl strings |
| System store | /var/lib/strawberry |
/var/db/strawberry (kSystemStorePath) |
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