strawberry/README.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

611 lines
30 KiB
Markdown

# Strawberry Security Scanner
Strawberry is an early-stage Linux host security scanner prototype in C++23, with a macOS port (Endpoint Security). The current codebase has a working build/test baseline, embedded database persistence, an optional libyara-backed file/executable scan path, a synthetic end-to-end procfs→scan→store test, optional procfs startup inventory for already-running processes, and a minimal Linux libbpf exec-event backend with privileged Docker smoke coverage for both live event delivery and live event persistence through the runtime pipeline, plus threat-intel IOC feeds, OpenSnitch network containment, fanotify exec prevention (audit/enforce), behavior and persistence telemetry, process-memory YARA scans and operator response actions. It is still a prototype: correlation is rule-based and narrow, and it is not a replacement for a mature EDR.
## Repository Setup
No submodules: every dependency comes from the system (pkg-config) or Conan.
```bash
git clone <repo-url>
```
## Conan and offline install
Strawberry now includes a root `conanfile.py` for a hybrid offline workflow:
- Conan-managed packages: OpenSSL, nlohmann_json, zstd and optional extras like libbpf
- a seeded local Conan recipe for `yara/4.5.5` under `conan/local_recipes_index/`
- optional local/private YARA recipe support via `user.strawberry:yara_reference`
- Conan cache save/restore for air-gapped transfer
Quick start:
```bash
conan profile detect --force
conan install . -of build/conan --build=missing
. build/conan/generators/conanbuild.sh
meson setup builddir --native-file build/conan/generators/conan_meson_native.ini -Denable_tests=true
meson compile -C builddir
```
The root Conan recipe now forces the generated Meson native file to use a
C++23 dialect for Strawberry itself, so a default `conan profile detect`
result like `gnu17` will not undercut the build.
Enable the seeded local YARA recipe:
```bash
conan remote add strawberry-local-recipes ./conan/local_recipes_index --allowed-packages="yara/*"
conan install . \
-of build/conan \
--build=missing \
-o '&:with_yara=True' \
-c user.strawberry:yara_reference=yara/4.5.5
```
For the full air-gapped flow, see [OFFLINE_INSTALL.md](OFFLINE_INSTALL.md).
## Quick Start
### GNU Make wrapper
```bash
make setup
make build
make test
make run
make app # desktop app + tray indicator (needs Qt6)
make demo # open the app on synthetic demo evidence, no daemon needed
```
### Meson directly
```bash
meson setup builddir -Denable_tests=true
meson compile -C builddir
meson test -C builddir --verbose
./builddir/src/strawberry config/strawberry.conf
```
### Docker
```bash
docker build -t strawberry-linux-dev .
docker run --rm -it -v $(pwd):/workspace strawberry-linux-dev bash -lc \
"meson setup builddir -Denable_tests=true && meson compile -C builddir && meson test -C builddir --verbose"
```
Self-contained Linux validation image:
```bash
docker build --target test -t strawberry-linux-test .
```
Privileged live libbpf smoke:
```bash
docker run --rm --privileged strawberry-linux-test ./builddir/tests/process_monitor_live_smoke
# or
make docker-live-bpf-smoke
```
Privileged live libbpf → pipeline → database smoke:
```bash
docker run --rm --privileged strawberry-linux-test ./builddir/tests/live_bpf_pipeline_smoke
# or
make docker-live-bpf-pipeline-smoke
```
Privileged live libbpf → `StrawberryDaemon` → database smoke:
```bash
docker run --rm --privileged strawberry-linux-test ./builddir/tests/live_bpf_daemon_smoke
# or
make docker-live-bpf-daemon-smoke
```
### Desktop app and tray indicator
`strawberry-tray` is a Qt6 desktop app (built automatically when Qt6 is
available; `-Denable_app=disabled` turns it off). It shows scanner health in
the system tray, raises desktop notifications for new high/critical findings
and automatic containments, and has these tabs:
- **Findings**: severity-sorted list with unseen markers, details, and pivots to
the related processes
- **Processes**: search by PID, path, hash, command line, rule or finding text;
shows identity, deleted/memfd flags, lineage, related evidence and the
incident trace, with actions: **Block network**, **Quarantine**, and for a
live process **Scan memory**, **Suspend**, **Resume**, **Kill** (each
confirmed)
- **Rules** and **Allowlist**: feeds (YARA and threat-intel lists), update
status, allowlist entries and policy history
- **Response**: OpenSnitch status and blocklist sizes, auto-containment and
prevention settings, contained binaries (Undo) and quarantined binaries
(Release)
- **Diagnostics**: eBPF/procfs backend, tracepoints, rule load status and
errors, pipeline counters, plus **Reload rules** and **Rescan running
processes** buttons
Tray colours: gray = scanner not reachable, green = healthy, yellow = degraded
(e.g. procfs fallback, rule reload failed) or unseen low/medium finding,
red = unseen high/critical finding.
Security model:
- the app runs as the desktop user, opens **no network ports**, and reads the
evidence database **read-only**
- access is granted by membership in the `strawberry` group (`install.sh`
creates it and offers to add you; log out/in afterwards)
- controls go through the daemon's Unix control socket
(`/run/strawberry/control.sock`, `root:strawberry 0660`), which accepts a
fixed verb set (plain verbs, plus strictly validated one-line JSON payloads
that take hashes or ids, never paths), rate-limits changes, audit-logs every
request and checks peer credentials; see [API_CONTRACT.md](API_CONTRACT.md)
Running it:
```bash
make app # from the build tree
strawberry-tray # installed: tray icon only
strawberry-tray --show # installed: open the window too
```
On sway, the tray icon needs waybar's `tray` module; start it with your session
by adding `exec strawberry-tray` to your sway config. Install `qt6-wayland` for
a native Wayland window (otherwise it runs under XWayland).
Try it without a running daemon:
```bash
make demo # seeds config/strawberry.demo.conf's DB and opens it in the app
```
### Daemon control from the CLI
The same control socket is available from the command line (any member of the
`strawberry` group):
```bash
strawberry --status --json # health, backend, rules, counters
strawberry --reload-rules # recompile rules; previous rules stay active on failure
strawberry --rescan # re-scan every running process
```
### YARA rules: automatic updates, feeds and allowlist
- **Default feed.** Strawberry ships 5 starter rules and, once installed,
downloads the **YARA Forge core** pack (about 5,100 curated rules, low false
positives).
- **Automatic updates.** The sandboxed `strawberry-update` service runs daily,
and immediately when you press **Update now** in the app. Each release is
verified against its published SHA-256 and compiled before it replaces the
active rules, so a bad update never leaves you without rules.
- **Rules tab** (desktop app): see active rule count, feed versions and update
errors. Add a feed (a GitHub release asset or an HTTPS `.yar`/`.zip` URL with
an optional pinned SHA-256), enable/disable or remove feeds, update now, or
reload rules.
- **Allowlist tab**: suppress known-good matches by binary **hash**
(recommended), **path** (exact or directory prefix, optionally one rule) or
**rule** name. Findings and process details have one-click "Allowlist this
binary" links. Every change is recorded with who made it; see "Recent policy
changes".
- **Who can change policy.** Any member of the `strawberry` group can change
feeds and the allowlist. The MCP server can only *read* them, so an agent
can't be talked into allowlisting malware.
From a terminal:
```bash
strawberry --policy # feeds, allowlist, update status
strawberry --policy-set allowlist-add '{"kind":"sha256","value":"<sha256>","note":"why"}'
strawberry --policy-set feed-add '{"id":"yara-forge-extended","type":"github-release","repo":"YARAHQ/yara-forge","asset":"yara-forge-rules-extended.zip"}'
strawberry --request-rule-update # same as "Update now"
strawberry --check-rules # compile everything, print the rule count
```
### Protection: threat intel, OpenSnitch, exec prevention, behavior, response
Safety rules hold across all of these:
- automatic actions are pinned to the exact binary (hash)
- the allowlist always wins
- system locations (`/usr`, `/bin`, `/sbin`, `/lib*`, `/boot`, `/etc`) are
alerted on but never blocked automatically, so a bad feed can't brick the
machine
- every action is recorded with who or what did it, and can be undone from the
Response tab
**Features:**
- **Threat-intel feeds.** Alongside YARA Forge, the updater fetches
known-malware SHA-256 hashes, CERT Polska malicious domains, Spamhaus DROP
networks and Feodo Tracker C2 IPs. They are validated and protected against
truncated downloads. Executing a listed hash is a critical
`IOC_KnownMalwareHash` detection. Add your own feeds with a kind of
`hashes`, `domains`, `ips` or `nets`.
- **OpenSnitch.** If [OpenSnitch](https://github.com/evilsocket/opensnitch) is
installed, Strawberry exports the domain, IP and net feeds as OpenSnitch
blocklist rules.
- **Automatic containment.** A detection at or above the threshold (default
`high`) gets a per-binary deny rule. Run
`sudo strawberry --opensnitch-enable-checksums` once so these rules are
pinned to the binary's hash rather than only its path.
- **Exec prevention** (fanotify). Before a program starts, its file is checked
against the IOC hashes and YARA rules.
- `audit` (the default) only records "would have been blocked".
- `enforce` denies execution of matches at or above the threshold (default
`critical`).
- It fails open: if no verdict arrives within 1 s, the program runs.
- Start in audit; switch to enforce in the Response tab once audit shows no
false positives.
- **Behavior and persistence.** eBPF watches outbound connects, ptrace attach
and kernel module loads. fanotify watches writes to persistence locations
(systemd units, cron, shell rc files, `authorized_keys`, `ld.so.preload`,
autostart) and drop directories (`/tmp`, `/dev/shm`, `~/Downloads`). Rules
include:
- connection to an IOC address
- a flagged process connecting out
- ptrace attach by a non-debugger
- module load outside modprobe
- persistence write
- download-then-execute
- **Memory scans.** Running from memfd, a deleted executable, or being the
target of ptrace triggers a YARA scan of the process's memory. You can also
start one from the app.
- **Response.**
- **Quarantine** blocks every execution of a binary, in every prevention
mode, and blocks its network. The file is kept for forensics.
- **Suspend**, **Resume** and **Kill** re-verify the process start time
first, so a reused PID is never hit.
- Core system and session processes are refused.
From a terminal:
```bash
strawberry --policy-set protection-set '{"prevention_mode":"enforce"}'
strawberry --policy-set quarantine '{"sha256":"<sha256>"}'
strawberry --policy-set process-kill '{"node_id":"process_<pid>_<boot>_<start>"}'
```
The daemon needs `CAP_SYS_ADMIN` (fanotify permission events), `CAP_KILL` and
`CAP_SYS_PTRACE` (memory scans). The shipped unit grants them and keeps the
rest of the sandbox (`systemd-analyze security strawberry` ≈ 3.2). Agents
(MCP) can read protection state but cannot change it.
### Resource use and scan profiles
Strawberry paces itself so scanning never takes over the machine:
- a resource governor watches its own CPU and memory and the system's
pressure (PSI); background work (startup inventory, rescans, memory scans,
correlation, rule reloads) waits while the system is busy and still runs at
least every 5 minutes
- program launches are never delayed by the governor; under heavy load the
launch check falls back to hash / threat-intel / quarantine checks and the
full YARA scan happens in the background
- background reads are rate-limited and run at low CPU/IO priority; the
systemd unit adds hard limits (`CPUWeight`, `MemoryHigh`/`MemoryMax`)
Pick a profile in `/etc/strawberry/strawberry.conf`: `scan_profile=efficient`
(laptops, busy desktops), `balanced` (default) or `aggressive` (servers).
The Diagnostics tab and `strawberry --status --json` (`resources`, `timings`)
show what the governor is doing. Measure changes with `make perf-kpi`.
### Agent access (MCP)
`strawberry-mcp` is a Model Context Protocol server (stdio) that lets an AI
agent work with the scanner. It's built when `nlohmann_json` is available;
`-Denable_mcp=disabled` turns it off. Register it as your desktop user, who
must be in the `strawberry` group:
```bash
claude mcp add strawberry -- strawberry-mcp # queries, scans, reload/rescan
claude mcp add strawberry -- strawberry-mcp --read-only # queries only
```
Tools:
- `strawberry_status`
- `strawberry_list_findings`, `strawberry_get_finding`
- `strawberry_search_processes`, `strawberry_get_process`
- `strawberry_scan_paths`
- `strawberry_reload_rules`, `strawberry_rescan`
The agent never gets more access than you:
- Evidence is read-only.
- Controls use the group-restricted control socket.
- `strawberry_scan_paths` opens each file **as you** and hands only the open
descriptor to the root daemon, so it can't read files you can't (try
`/etc/shadow`: it reports "Permission denied").
Evidence strings (command lines, paths) come from the monitored host and may be
attacker-controlled, and the server tells agents to treat them as data. See
[API_CONTRACT.md](API_CONTRACT.md) for schemas.
Scan a single file from a terminal the same way:
```bash
strawberry --scan-file ~/Downloads/suspicious.bin
```
### Correlation CLI
The first correlation pass is intentionally small and explainable: it groups
process-executable YARA hits by process/hash and stores a durable finding.
```bash
# generate or refresh findings from the current DB
./builddir/src/strawberry --correlate config/strawberry.demo.conf
# list stored findings
./builddir/src/strawberry --list-findings config/strawberry.demo.conf
# inspect one finding
./builddir/src/strawberry --show-finding finding_process_yara_... config/strawberry.demo.conf
# structured output for GUI/automation clients
./builddir/src/strawberry --list-findings --json config/strawberry.demo.conf
./builddir/src/strawberry --show-finding finding_process_yara_... --json config/strawberry.demo.conf
```
Current rules:
- `process_executable_yara_match`
- `lineage_multiple_yara_matches`
- `same_hash_multiple_process_matches`
- `same_yara_rule_multiple_processes`
This is not yet a full incident engine. It is the first backend contract for
process-first and findings-first analyst UX work.
### Process search CLI
The first process-pivot query surface is also available:
```bash
# search by PID, executable path, hash, YARA rule, or finding text
./builddir/src/strawberry --search-process 654 --json config/strawberry.demo.conf
./builddir/src/strawberry --search-process SyntheticDemoRule --json config/strawberry.demo.conf
./builddir/src/strawberry --search-process demo_hash_abc123 --json config/strawberry.demo.conf
```
The desktop app's Processes tab uses this same query surface.
JSON process-search results include the matched process, matched fields,
first/last seen evidence timestamps, related findings, parent process when
known, and immediate child processes.
Notes:
- the Docker image now installs `libyara-dev` by default so Linux container builds exercise the real libyara-backed path
- the Docker image defaults to `gcc`/`g++`; `clang` is still installed for future Linux eBPF work, but the default build compiler is `gcc`/`g++` for C++23
- the privileged smoke harness mounts `tracefs` inside the container if needed before attaching tracepoints
- the libbpf backend now attempts an additional optional `sched_process_fork` tracepoint attach for parent-PID enrichment, but it degrades cleanly if that tracepoint is blocked by the runtime/kernel policy
- the libbpf backend now also carries a best-effort fixed-width argv preview (`argv0`/`argv1`) for cases where `/proc/<pid>/cmdline` is unavailable
- the live smoke currently matches the observed `/bin/echo` exec event by executable path; PID values may differ from the child process seen inside the container because the callback can surface a host/kernel namespace PID
- the live pipeline smoke currently persists timestamped runtime context, but `parent_pid` may remain unavailable in the privileged container BPF path when `/proc/<host-pid>` cannot be resolved from inside the container
## Current Status
As of **April 26, 2026**:
- Meson configure/compile/test is working again
- `Database` is backed by the compressed event store (`src/store/`; zstd segments, crash-atomic manifest); older `database.db` files are imported on the daemon's first start
- local persistence across reopen is covered by unit tests
- optional libyara-backed rule loading and file scanning are implemented
- YARA hit metadata is now persisted through the database path and linked into the graph model
- best-effort `/proc/<pid>/exe` scanning is implemented for `scan_process` when libyara is available
- a Conan-backed libyara build and test pass succeeded on **April 25, 2026** on the current macOS host, including real rule compilation and file-scan assertions
- Linux-specific `scan_process` behavior is now covered by a Docker-validated Linux test on **April 26, 2026**, using `/proc/<pid>/exe` against the running test process
- a minimal runtime **process event ingestion** path now exists on **April 26, 2026** through procfs polling, with synthetic procfs unit coverage
- a reusable **DetectionPipeline** now owns the scan/store path, and a Docker-validated synthetic runtime test on **April 26, 2026** proves procfs event ingestion can trigger YARA matching and persisted graph/indicator storage end-to-end
- a minimal **libbpf exec-event backend** now also builds on Linux as of **April 26, 2026**, with procfs fallback still in place
- a privileged Linux Docker smoke run on **April 26, 2026** successfully loaded the libbpf backend, attached the exec tracepoints, and observed a live `/bin/echo` exec event
- that privileged `/bin/echo` smoke now also validates best-effort live argv preview capture (`echo strawberry_process_monitor_live_smoke`) on **April 26, 2026**
- a second privileged Linux Docker smoke run on **April 26, 2026** successfully fed a live libbpf exec event into `DetectionPipeline` and verified persisted indicator + graph storage from that real event
- that staged-executable pipeline smoke now also surfaces a useful argv preview (`live_echo strawberry_live_bpf_pipeline_smoke`) on **April 26, 2026**
- a reusable `StrawberryDaemon` wrapper now owns the long-running daemon shell around configuration, `ProcessMonitor`, and `DetectionPipeline`
- a third privileged Linux Docker smoke run on **April 26, 2026** successfully fed a live libbpf exec event through `StrawberryDaemon` itself and verified persisted indicator + graph storage from that daemon-owned path
- a new `IncidentReporter` path now produces concise human-readable trace summaries from persisted graph data, including trace first/last seen timestamps and relative span formatting, and the main binary can print them with `--trace-process` or `--trace-node`
- a Qt6 desktop app with a tray indicator (`strawberry-tray`) replaces the earlier temporary web evaluator; it reads evidence read-only and controls the daemon through a group-restricted Unix socket
- a minimal `CorrelationEngine` now emits durable findings for process-executable YARA matches grouped by process/hash, multiple matched descendants under one parent, the same matched executable hash across processes, and the same YARA rule across processes
- findings can now be listed/shown as JSON for the desktop app and automation clients
- process search can now query PID, path, hash, YARA rule, and related finding evidence with JSON output
- the libbpf path now opportunistically attempts `sched_process_fork` attachment for parent-PID enrichment, but the privileged container smoke still shows that this extra tracepoint can be denied while the main exec-event path continues to work
- procfs-driven runtime events now persist `parent_pid` and `event_timestamp_ns`, and create a minimal `spawned` lineage edge from parent process to matched child process
- matched runtime events now also persist an executable-image `file_*` node plus `executed` and `content_matched` provenance edges on **April 26, 2026**
## Features
- **State Machine Daemon Shell**: TinyFSM-based daemon/state transitions
- **Event Store**: compressed (zstd) append-only evidence and telemetry streams with crash recovery; indicator and graph persistence
- **Graph Analysis Primitives**: process/file node and edge storage/query helpers
- **Persisted YARA Match Context**: multiple indicator hits per hash plus process→indicator graph linkage
- **Hash Verification**: SHA256/MD5 helpers for artifact fingerprinting
- **YARA File/Executable Scanning**: optional libyara-backed rule compilation, match extraction, and best-effort `/proc/<pid>/exe` scans
- **Detection Pipeline**: reusable scan/store runtime pipeline that prefers scanning the resolved executable path from `ProcessInfo` and persists matched process→indicator relationships plus minimal parent→child lineage when available
- **Daemon Runtime Shell**: `StrawberryDaemon` now owns config loading, state-machine transitions, process-monitor startup, and graceful stop handling for the production binary and daemon-level tests
- **Incident Trace Summaries**: `IncidentReporter` can render concise process/node-centered summaries over persisted nodes and edges, including first/last seen timing plus approximate duration units, for quick operator review
- **Desktop App + Tray Indicator**: `strawberry-tray` shows scanner health, notifies on new high-severity findings, and offers findings/process/diagnostics views plus reload/rescan controls, without opening any network port
- **Executable Provenance Edges**: matched runtime events now also connect process → executable image (`executed`) and executable image → indicator (`content_matched`)
- **Process Event Ingestion**: Linux monitor that prefers a minimal libbpf exec-event path when available and otherwise falls back to procfs polling; privileged Docker smoke validation now exists for live exec delivery, a direct pipeline persistence path, and a daemon-owned persistence path
## Architecture
```text
Idle → Initializing → Monitoring ⇄ Updating → Shutdown
```
### Components
- **ProcessMonitor**: process-event monitor abstraction; current Linux builds can compile and live-smoke a minimal libbpf exec-event path, while procfs fallback currently provides the richest parent-PID enrichment
- **DetectionPipeline**: reusable scan/store wiring shared by the daemon and tests; current coverage proves both synthetic procfs event → executable scan → indicator/graph persistence and one privileged live libbpf event → persistence path on libyara-enabled Linux
- **StrawberryDaemon**: reusable long-running wrapper around config loading, TinyFSM transitions, process-monitor startup, and pipeline ownership; current coverage now includes both a synthetic daemon test and a privileged live daemon smoke on Linux
- **IncidentReporter**: summary/reporting helper over persisted graph state; current coverage includes a unit test that renders a process-centered lineage/match trace
- **ControlServer**: Unix-socket control channel in the daemon (fixed plain verbs, fd-passing `scan-fd`, and validated JSON payload verbs for policy, protection and response), group-restricted with peer-credential checks, rate limits and an audit log
- **PolicyStore**: `policy.json` with feeds, allowlist, containment, quarantine, protection settings and change history
- **RuleUpdater**: sandboxed feed updater (YARA archives and IOC lists, digest-verified, compile-checked, atomic switch)
- **OpenSnitch integration**: blocklist and per-binary deny rule files (`strawberry-*.json`)
- **ExecGuard**: fanotify `FAN_OPEN_EXEC_PERM` exec prevention with a fail-open deadline and verdict cache
- **BehaviorEngine + FileWatcher**: eBPF connect/ptrace/module events and fanotify persistence/drop writes, evaluated by behavior rules
- **strawberry-tray** (`app/`): Qt6 desktop app and tray indicator over read-only evidence plus the control socket
- **strawberry-mcp** (`mcp/`): MCP server for agents over the same read-only evidence, control verbs and fd-passing scans
- **YaraScanner**: YARA wrapper with optional libyara-backed rule compilation, file/in-memory scanning, and process-memory scanning (`yr_rules_scan_proc`)
- **Database**: indicator, graph and finding API over the event store (in-memory view, O(degree) graph queries)
- **HashUtils**: cryptographic hashing helpers
- **Config**: file-based configuration with XDG-aware defaults
## Building
### Dependencies
Minimal build dependencies:
```bash
# Ubuntu/Debian
sudo apt-get install -y meson ninja-build clang ccache libssl-dev
```
Recommended runtime/integration dependencies for enabled detection features:
```bash
sudo apt-get install -y libbpf-dev libyara-dev
```
`tinyfsm.hpp` is bundled locally in `include/`, so no separate TinyFSM install is required.
`libyara-dev` enables real rule compilation and file/executable scanning. Without it, Strawberry still builds and tests, but `YaraScanner` stays in graceful fallback mode.
`libbpf-dev` plus `clang` on Linux enables the minimal exec-event eBPF object build path. If that backend cannot be loaded or attached at runtime, `ProcessMonitor` falls back to procfs polling.
### Build Commands
```bash
meson setup builddir -Denable_tests=true
meson compile -C builddir
meson test -C builddir --verbose
```
### macOS
```bash
brew install meson ninja pkgconf ccache yara libarchive zstd nlohmann-json openssl@3 qt
make build test
```
`make setup` adds Homebrew's keg-only libarchive to `pkg_config_path`. With
meson directly, pass `-Dpkg_config_path=$(brew --prefix)/opt/libarchive/lib/pkgconfig`.
`-Denable_app=disabled` skips the Qt app.
Backends on macOS:
| Linux | macOS | Needs |
| --- | --- | --- |
| eBPF exec events | Endpoint Security `NOTIFY_EXEC` | ES client (below) |
| procfs polling | libproc polling | nothing |
| fanotify exec prevention | ES `AUTH_EXEC` | ES client |
| fanotify file watch | ES `NOTIFY_CREATE/RENAME/CLOSE` | ES client |
| eBPF connect events | none | |
| eBPF ptrace / module load | ES `NOTIFY_TRACE` / `NOTIFY_KEXTLOAD` | ES client |
| process memory scan | YARA `yr_rules_scan_proc` (`task_for_pid`) | root; untested |
An ES client needs root, the `com.apple.developer.endpoint-security.client`
entitlement and Full Disk Access for the binary. Apple grants the
entitlement to Developer ID accounts on request; an ad hoc signature carries
it only with SIP disabled. Without an ES client the daemon polls libproc and
`--status` reports prevention and file watching unavailable.
```bash
make macos-sign # ad hoc: IDENTITY=-, or IDENTITY='Developer ID Application: ...'
make macos-install # binaries, /etc/strawberry, /var/db/strawberry, launchd jobs
sudo launchctl kickstart -k system/com.strawberry.daemon
make macos-live-tests # ES exec prevention, exec events, file watch (sudo)
```
Files: `/etc/strawberry/strawberry.conf`, `/var/db/strawberry/` (evidence,
feeds), `/var/run/strawberry/control.sock`, `/var/log/strawberry.log`,
`/Library/LaunchDaemons/com.strawberry.{daemon,update}.plist`.
## Configuration
Example `config/strawberry.conf`:
```ini
# Database path (empty = XDG default: ~/.local/share/strawberry/database.db)
db_path=
# YARA rules directory
yara_rules_path=/etc/strawberry/rules
# Enable process monitoring
# (currently prefers libbpf on supported Linux builds and otherwise falls back to procfs polling)
enable_bpf_monitoring=true
# When using the procfs backend, emit already-running processes at startup
# before continuing to poll for newly observed PIDs.
scan_existing_processes_on_start=true
```
For a fuller Linux process corpus during correlation experiments, force the
procfs backend so startup inventory is active:
```bash
STRAWBERRY_PROCESS_MONITOR_BACKEND=procfs ./builddir/src/strawberry config/strawberry.conf
```
## Usage
```bash
# Run with the repo's sample config
./builddir/src/strawberry config/strawberry.conf
# Run with the default system config path
./builddir/src/strawberry /etc/strawberry/strawberry.conf
# Print a stored trace summary for one process
./builddir/src/strawberry --trace-process 654 config/strawberry.conf
# Print a stored trace summary for one graph node
./builddir/src/strawberry --trace-node process_654 config/strawberry.conf
# Seed a synthetic demo trace for app/report evaluation
./builddir/src/strawberry --seed-demo-trace config/strawberry.demo.conf
```
Example YARA rule:
```yara
rule SuspiciousProcess {
strings:
$exec = "/bin/sh"
condition:
$exec
}
```
## Data Storage
Strawberry follows the XDG Base Directory specification:
- target database path: `$XDG_DATA_HOME/strawberry/database.db` (default: `~/.local/share/strawberry/database.db`)
- config: `/etc/strawberry/strawberry.conf` or a custom path
Current local status:
- Strawberry persists indicators, graph nodes, graph edges, and YARA hit metadata across reopen in this checkout
- multiple indicator entries can now be stored for the same file/process hash
- direct tests cover reopen, commit, rollback, and read-only behavior
- `test_yara_scanner` now covers graceful fallback without libyara and contains real scan assertions for libyara-enabled builds
## Development
See these project docs:
- [AGENTS.md](AGENTS.md)
- [PLAN.md](PLAN.md)
- [RESEARCH.md](RESEARCH.md)
- [DEVELOPER.md](DEVELOPER.md)
Third-party code: none vendored (`include/tinyfsm.hpp` is a single header).
## License
MIT License