Reuse the existing resolver/sampler for opt-in aggregate training summaries. Reject incomplete or undecodable snapshots without usable partial reports, retain best-effort readers elsewhere, and document cooperative extent checks rather than atomic snapshot guarantees. Include command-table/help, JSON, fixture and corruption regressions; no model training or promotion.
433 lines
19 KiB
Markdown
433 lines
19 KiB
Markdown
# 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
|
||
`<state dir>/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 <action>)
|
||
strawberry findings list # stored findings; findings show <id> for one
|
||
strawberry process search <query> # PID, path, hash, YARA rule or finding text
|
||
strawberry process trace <pid> # lineage and evidence of one process
|
||
strawberry scan file <path> # 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 <command> for its flags
|
||
```
|
||
|
||
Every command takes `--config <path>` (default
|
||
`/etc/strawberry/strawberry.conf`). The older flag forms (`strawberry
|
||
--status`, `strawberry <config>`) 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":"<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 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":"<sha256>"}'
|
||
strawberry process kill process_<pid>_<boot>_<start>
|
||
```
|
||
|
||
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
|