# Strawberry Security Scanner Host security scanner for Linux and macOS, in C++23. It YARA-scans every program that runs, checks threat-intel feeds, can block execution, records behavior and persistence writes as evidence, and correlates them into findings. A Qt tray app and an MCP server read the same evidence. It is a prototype, not a replacement for a mature EDR. ## Install Build from source, then run the installer as root. `make install` builds and runs `scripts/install.sh`, which runs `scripts/macos_install.sh` on macOS. ### Linux ```bash # Arch sudo pacman -S meson ninja clang llvm pkgconf openssl zstd nlohmann-json \ yara libbpf curl libarchive qt6-base # Debian/Ubuntu sudo apt-get install -y meson ninja-build clang llvm pkg-config libssl-dev \ libzstd-dev nlohmann-json3-dev libyara-dev libbpf-dev \ libcurl4-openssl-dev libarchive-dev qt6-base-dev make build test make install # sudo: binaries, /etc/strawberry, systemd units sudo systemctl enable --now strawberry strawberry status ``` The installer creates the `strawberry` group and offers to add you (log out and back in afterwards). It enables the daily rule updater, which fetches the default feeds right away. ### macOS ```bash brew install meson ninja pkgconf ccache openssl zstd nlohmann-json yara \ libarchive qt make build test make install # sudo: binaries, /etc/strawberry, launchd jobs strawberry status ``` `make install` starts the daemon and the rule updater under launchd. Endpoint Security (ES) is the macOS backend for exec events, exec prevention and the file watch. An ES client needs three things: - root: the launchd job runs as root - the `com.apple.developer.endpoint-security.client` entitlement - Full Disk Access for `/usr/local/bin/strawberry` The default ad hoc signature carries the entitlement only with SIP disabled. With SIP enabled, the installer signs without the entitlement and the daemon polls libproc instead: detection works, prevention and the file watch do not. With an identity Apple granted the entitlement: ```bash make install IDENTITY='Developer ID Application: ...' # then grant Full Disk Access to /usr/local/bin/strawberry and restart: sudo launchctl kickstart -k system/com.strawberry.daemon ``` The Developer ID path is untested. Apple may also require a provisioning profile, which only an app bundle can carry. ### Installed files | | Linux | macOS | | --- | --- | --- | | Binaries | `/usr/local/bin/strawberry{,-tray,-mcp}` | same | | Config | `/etc/strawberry/strawberry.conf` | same | | Local rules | `/etc/strawberry/rules/` (root, 0700) | same | | Evidence, policy, feeds | `/var/lib/strawberry/` | `/var/db/strawberry/` | | Control socket | `/run/strawberry/control.sock` | `/var/run/strawberry/control.sock` | | Services | `strawberry.service`, `strawberry-update.{service,timer,path}` | `/Library/LaunchDaemons/com.strawberry.{daemon,update}.plist` | | Logs | `journalctl -u strawberry` | `/var/log/strawberry.log`, `/var/log/strawberry-update.log` | | Attack traces (replay, training) | `/usr/local/share/strawberry/traces/` | same | | Rule updater runs as | root without capabilities, systemd sandbox | `_strawberry` (owns only `feeds/`) | The installers record hashes of the service files they write in `/installed-files.sha256`. A write to a persistence location that matches this manifest is stored as evidence, not raised as a finding. ## Usage Members of the `strawberry` group can use the CLI and the app. ```bash strawberry status --json # health, backend, rules, counters strawberry doctor # checks with suggested fixes (strawberry doctor fix ) strawberry findings list # stored findings; findings show for one strawberry process search # PID, path, hash, YARA rule or finding text strawberry process trace # lineage and evidence of one process strawberry scan file # YARA-scan a file with your own permissions strawberry rules reload # recompile rules; previous rules stay active on failure strawberry scan processes # re-scan every running process strawberry help # every command; strawberry help for its flags ``` Every command takes `--config ` (default `/etc/strawberry/strawberry.conf`). The older flag forms (`strawberry --status`, `strawberry `) still work. Run the daemon in the foreground from a build tree: ```bash ./builddir/src/strawberry daemon run --config config/strawberry.conf ``` Correlation rules: `process_executable_yara_match`, `lineage_multiple_yara_matches`, `same_hash_multiple_process_matches`, `same_yara_rule_multiple_processes`, plus the behavior rules below. ### Desktop app and tray indicator `strawberry-tray` (Qt6; `-Denable_app=disabled` turns it off) shows scanner health in the tray and notifies on new high/critical findings and automatic containments. Tabs: - Findings: severity-sorted list with unseen markers and pivots to processes - Processes: search, identity, lineage, related evidence, incident trace; actions Block network, Quarantine, and for a live process Scan memory, Suspend, Resume, Kill (each confirmed) - Rules and Allowlist: feeds, update status, allowlist, policy history - Response: OpenSnitch status, containment and prevention settings, contained and quarantined binaries (Undo / Release) - Diagnostics: backend, rule load status, pipeline counters, Reload rules, Rescan running processes Tray colours: gray = daemon not reachable, green = healthy, yellow = degraded (fallback backend, failed rule reload) or an unseen low/medium finding, red = an unseen high/critical finding. ```bash make app # from the build tree strawberry-tray --show # installed; without --show: tray icon only make demo # synthetic evidence, no daemon needed ``` The app opens no network ports, reads evidence read-only, and sends controls over the control socket (`root:strawberry 0660`). The socket accepts a fixed verb set, checks peer credentials, rate-limits changes and audit-logs every request; see [API_CONTRACT.md](API_CONTRACT.md). Linux: on sway the tray icon needs waybar's `tray` module; add `exec strawberry-tray` to the sway config. Install `qt6-wayland` for a native Wayland window. The "Start at login" toggle writes an XDG autostart entry; it has no effect on macOS. ### YARA rules, feeds and allowlist - Strawberry ships 5 starter rules and downloads the YARA Forge core pack (about 5,100 rules). - The rule updater runs daily, and at once on Update now. Each release is checked against its published SHA-256 and compiled before it replaces the active rules; a bad update leaves the previous rules active. - Feeds: a GitHub release asset or an HTTPS `.yar`/`.zip` URL, with an optional pinned SHA-256. - Allowlist: by binary hash (recommended), path (exact or directory prefix, optionally one rule) or rule name. Every change is recorded with who made it. - Any member of the `strawberry` group can change feeds and the allowlist. The MCP server can only read them. ```bash strawberry policy show strawberry policy set allowlist-add '{"kind":"sha256","value":"","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 rules update # same as Update now strawberry rules check # compile everything, print the rule count ``` ### Protection and response Safety rules: - automatic actions are pinned to the binary's hash - the allowlist always wins - system locations are alerted on but never blocked automatically: `/usr`, `/bin`, `/sbin`, `/lib*`, `/boot`, `/etc`, and on macOS also `/System`, `/Library/Apple`, `/private/etc` and Apple platform binaries - every action is recorded and can be undone from the Response tab Features: - Threat-intel feeds: known-malware SHA-256 hashes, CERT Polska domains, Spamhaus DROP, Feodo Tracker C2 IPs. Executing a listed hash is a critical `IOC_KnownMalwareHash` detection. Custom feeds take a kind of `hashes`, `domains`, `ips` or `nets`, or `trackers` for a privacy list (advisory only, never blocks; see [docs/tracker-attribution.md](docs/tracker-attribution.md)). - OpenSnitch (Linux): domain, IP and net feeds are exported as OpenSnitch blocklists, and a detection at or above `high` gets a per-binary deny rule. Run `sudo strawberry opensnitch enable-checksums` once so these rules pin the hash, not only the path. - Exec prevention (fanotify on Linux, ES `AUTH_EXEC` on macOS): a program's file is checked against IOC hashes and YARA rules before it starts. `audit` (default) records "would have blocked"; `enforce` denies matches at or above `critical`. It fails open: without a verdict within 1 s (macOS: also before the ES deadline) the program runs. Switch to enforce once audit shows no false positives. - Persistence and drop writes (fanotify on Linux, ES on macOS): systemd units, cron, shell rc files, `authorized_keys`, `ld.so.preload`, autostart; on macOS LaunchDaemons/LaunchAgents, periodic jobs, crontabs, sudoers, shell rc files. Drop directories: `/tmp`, `/dev/shm`, `/private/tmp`, `~/Downloads`. - Behavior: outbound connects (eBPF, Linux only), ptrace attach and kernel module loads (eBPF; ES on macOS). Rules: connection to an IOC address, a flagged process connecting out, ptrace by a non-debugger, module load outside the system loader, persistence write, download-then-execute. - Memory scans: a process running from memfd, a deleted executable, or a ptrace target gets a YARA scan of its memory. Untested on macOS. - Response: Quarantine blocks every execution of a binary and its network (the file is kept). Suspend, Resume and Kill re-check the process start time, so a reused PID is never hit. Core system and session processes are refused. ```bash strawberry policy set protection-set '{"prevention_mode":"enforce"}' strawberry policy set quarantine '{"sha256":""}' strawberry process kill process___ ``` On Linux the daemon needs `CAP_SYS_ADMIN` (fanotify permission events), `CAP_KILL` and `CAP_SYS_PTRACE`. The shipped unit grants them inside a systemd sandbox (`systemd-analyze security strawberry` ≈ 3.2). MCP agents can read protection state but not change it. ### Backends | Function | Linux | macOS | | --- | --- | --- | | Exec events | eBPF tracepoints, else procfs polling | ES `NOTIFY_EXEC`, else libproc polling | | Exec prevention | fanotify `FAN_OPEN_EXEC_PERM` | ES `AUTH_EXEC` | | File watch | fanotify | ES `NOTIFY_CREATE/RENAME/CLOSE` | | Connect events | eBPF | none | | ptrace / module load | eBPF | ES `NOTIFY_TRACE` / `NOTIFY_KEXTLOAD` | | System pressure | PSI, cgroup v2 | load average, Mach VM statistics | `strawberry status` reports the active backend and why a fallback was taken (for example `Endpoint Security client failed: needs root`). ### Resource use and scan profiles A resource governor watches the daemon's CPU and memory and the system's load. 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; under load the launch check uses hashes, threat intel and quarantine only, and the YARA scan runs in the background. Background reads are rate-limited at low CPU and I/O priority. The systemd unit adds hard limits (`CPUWeight`, `MemoryHigh`, `MemoryMax`). Set `scan_profile=` in the config: `efficient` (laptops), `balanced` (default) or `aggressive` (servers). `strawberry status --json` (`resources`, `timings`) shows what the governor is doing. Measure changes with `make perf-kpi`. ### Inspection model (experimental, shadow only) The daemon can score each process window with a small model and log which extra inspection (memory scan, deeper rescan) it would request. It never blocks anything, and nothing runs until you promote a model that passed the replay gate (`docs/evaluation/stage4-promotion-gate.md`). ```bash # Train a shadow model. Without detections on this host, train on scripted # attack traces; the gate evaluates on a different set (standard.trace). sudo strawberry model train --inject-train /usr/local/share/strawberry/traces/training.trace strawberry status --json # model: shadow decisions, warm-up, rarity state sudo strawberry model promote # only after a week or more of shadow decisions ``` Before considering training, inspect an **already readable, cooperative immutable snapshot** without invoking the trainer or contacting the daemon: ```bash strawberry replay /path/to/snapshot --training-summary --json # Optional: --warmup 0 includes the initial windows, which are usually first-time events. ``` This reuses replay's label resolver and seeded sampler. It reports aggregate coverage, label provenance, eligible versus actually retained classes and entity concentration; it never prints host identities or writes a model. Ordinary replay still leaves sample collection off (`examples_collected: false`). The summary requires a valid current `MANIFEST`, complete and decodable listed segments (a block needing a dictionary the build lacks, or a complete invalid block header, is unusable input rather than an empty stream), no torn active tail, and unchanged observed manifest identity/extents. It does not stop or lock the daemon, repair a store, change permissions or create a snapshot. Without a path, summary mode needs an explicit `db_path` in the local config; it does not discover a store through daemon status. `--model`, `--policy-eval`, `--inject`, `--inject-copies` and `--top` cannot be combined with this mode. `assessment: "not_assessed"` is deliberate: retrospective labels and a constrained sample do **not** establish training readiness, label maturity, leakage-free splits, measured RSS/inspection CPU budgets, or promotion efficacy. The separate three-period × three-seed gates are unchanged. See [the CLI JSON contract](API_CONTRACT.md#offline-replay-diagnostics-cli-only). ### Privacy: which programs reach trackers Strawberry can show which programs on this machine contact advertising and tracking domains, not only the browser (an idea from the CarolinaCon 2026 talk "How Ad Networks Map You"). It is advisory: never a block, never a finding. Hostnames come from OpenSnitch: the installer sets OpenSnitch to send its connection events to Strawberry on a loopback port only root can bind, and Strawberry keeps the program, the listed domain, the port and the time, never the command lines or environments in those events. The list is EasyPrivacy (a default `trackers` feed). A listed domain is a candidate, not proof of tracking. ```bash strawberry privacy trackers # per program: tracker domains, counts, last contact sudo strawberry opensnitch enable-events # if OpenSnitch was installed after Strawberry ``` Turn it off with `privacy_trackers=false` in the config. Details: [docs/tracker-attribution.md](docs/tracker-attribution.md). ### Agent access (MCP) `strawberry-mcp` is a stdio MCP server (built with `nlohmann_json`; `-Denable_mcp=disabled` turns it off). Register it as a user in the `strawberry` group, not as root: ```bash claude mcp add strawberry -- strawberry-mcp # Claude Code codex mcp add strawberry -- strawberry-mcp # Codex pi mcp add strawberry -- strawberry-mcp # pi ``` Append `--read-only` after `strawberry-mcp` to allow queries only (no scans, reload or rescan). 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 gets no more access than you. Evidence is read-only, controls go through the group-restricted socket, and `strawberry_scan_paths` opens each file as you and passes only the descriptor to the daemon, so a file you cannot read reports "Permission denied". Evidence strings come from the monitored host and may be attacker-controlled; the server tells agents to treat them as data. Schemas: [API_CONTRACT.md](API_CONTRACT.md). ## Configuration `/etc/strawberry/strawberry.conf` (template: `config/strawberry.conf`): ```ini db_path= # empty = $XDG_DATA_HOME/strawberry/database.db yara_rules_path=/etc/strawberry/rules enable_bpf_monitoring=true # process monitoring, every backend scan_existing_processes_on_start=true scan_profile=balanced ``` `STRAWBERRY_PROCESS_MONITOR_BACKEND=procfs` forces procfs polling on Linux. ## Building ```bash meson setup builddir -Denable_tests=true meson compile -C builddir meson test -C builddir ``` Required: OpenSSL, zstd >= 1.5, nlohmann_json. Optional, each turns on a feature: libyara (scanning; without it `YaraScanner` is a stub), libbpf and clang (eBPF), libcurl and libarchive (rule updater), Qt6 (app). On macOS `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`. Conan (OpenSSL, nlohmann_json, zstd, libbpf, a local `yara/4.5.5` recipe, cache save/restore for air-gapped hosts): ```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 ``` See [OFFLINE_INSTALL.md](OFFLINE_INSTALL.md) for the local YARA recipe and the air-gapped flow. Linux in Docker: ```bash docker build --target test -t strawberry-linux-test . # builds and runs the tests make docker-live-tests # privileged: exec prevention, behavior, file watch, memory scans ``` macOS ES live test (root, an ES-capable signature, so SIP disabled for ad hoc): `make macos-live-tests`. ## Architecture ```text Idle → Initializing → Monitoring ⇄ Updating → Shutdown ``` - ProcessMonitor: exec events from eBPF, ES, procfs or libproc - DetectionPipeline: scan and store; persists process→indicator matches, lineage and executable provenance - StrawberryDaemon: config, state machine, monitor and pipeline lifetime - ExecGuard: exec prevention with a fail-open deadline and a verdict cache - BehaviorEngine and FileWatcher: behavior events and persistence writes, evaluated by behavior rules - CorrelationEngine: durable findings from matches and behavior - ControlServer: Unix control socket with peer-credential checks, rate limits and an audit log - PolicyStore: `policy.json` (feeds, allowlist, containment, quarantine, protection, history) - RuleUpdater: feed updater (digest-verified, compile-checked, atomic switch) - Database: indicator, graph and finding API over the event store (zstd segments, crash-atomic manifest; older `database.db` files are imported on first start) - `app/`: Qt6 tray app; `mcp/`: MCP server ## Development [AGENTS.md](AGENTS.md) (rules and per-change checks), [DEVELOPER.md](DEVELOPER.md), [API_CONTRACT.md](API_CONTRACT.md), [PLAN.md](PLAN.md), [RESEARCH.md](RESEARCH.md). No vendored third-party code (`include/tinyfsm.hpp` is a single header). ## License MIT