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>
283 lines
15 KiB
Markdown
283 lines
15 KiB
Markdown
# 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`
|