strawberry/README.md
trvon 31e44caab0
cli: honor <group> --help, and add fleet run for a standalone central node
`strawberry fleet --help` reported "unknown subcommand 'fleet --help'" and
then dumped the group's usage, even though docs/cli-ux.md promises that
`strawberry <cmd> --help` prints the same text as `strawberry help <cmd>`.
A group word followed by -h/--help now prints the group listing.

Centralized training had no single entry point: `fleet train` and
`fleet overlay` had to be run by hand (or through Salt), so a standalone
central node had no "run" command at all. `strawberry fleet run <bundle_dir>
[--out DIR]` trains and builds the overlay by calling the same two code paths,
so the behaviour cannot diverge, and prints the model/overlay paths.

It deliberately does not distribute to nodes, apply the overlay, or promote a
model: distribution stays behind the Salt canary cycle and promotion stays
behind `model promote` plus the fleet promotion gate. The JSON output carries
distributed=false and promoted=false so a script cannot mistake it.

Tests: fleet --help and fleet -h print the group without error; fleet run maps
to --fleet-run with optional dir, --out/--seed/--epochs passthrough, rejects
unknown options; a bare `fleet` still explains itself. Verified end to end on
two seeded bundles: model + overlay written to the requested directory.
2026-11-18 12:11:34 -07:00

482 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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. Two
experimental, shadow-only layers sit on top: a model that learns where to
spend extra inspection, and a distributed mode that lets a fleet learn
centrally from redacted exports — neither blocks or detects on its own. 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.
- Compiled-rules cache: the daemon saves the compiled rules to
`rules_cache_dir` (default `/var/lib/strawberry/rules-cache`, root-only,
0700 dir / 0600 files) and reloads them on the next start instead of
recompiling. It has the same trust as the rule sources, is keyed on the
libyara version plus every source file's content, namespace and order, so a
feed update or libyara upgrade recompiles automatically, and any mismatch or
load error falls back to compiling. `strawberry status` shows
`rules.cache` (`hit|miss|disabled|error`) and `rules.load_ms`.
- 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).
### Fleet learning (experimental)
Across many hosts, Strawberry can learn centrally from what each node already
computes, without raw telemetry leaving a host. Each node *exports* a sealed,
redacted bundle — process windows, feature vectors, teacher labels and rarity
sketches, never argv, paths or secrets. A central node merges the bundles,
trains the shadow model, and builds a fleet-wide rarity overlay that nodes fold
back in as a model feature ("rare across the fleet", not only on one box). It is
hub-and-spoke (not peer-to-peer); promotion stays an operator action.
```bash
# on each sensor (reads a local fleet-overlay.sbo if present)
strawberry export /var/lib/strawberry/evidence --out node.sbx
# on the central node (a directory of collected *.sbx bundles)
strawberry fleet train /path/to/bundles --out shadow.sbm
strawberry fleet overlay /path/to/bundles --out fleet-overlay.sbo
# or both at once, for a standalone central node (still no distribution/promotion)
strawberry fleet run /path/to/bundles --out /var/lib/strawberry/model
```
Still single-process/component tested, not yet validated across a live fleet.
The distributed design (nodes, egress, overlay, Salt deployment) is in `PLAN.md`.
### 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)
- ResourceGovernor: admits/defers background work by host pressure and scan profile
- `learn/`: inspection-steering model (experimental, shadow-only) — offline training,
live shadow scoring, replay-gated operator promotion; it spends inspection budget,
it does not block or detect on its own
- `fleet_export` / `fleet_merge`: distributed mode — redacted export bundles, central
merge/train, and the fleet-wide rarity overlay (see "Fleet learning")
- `app/`: Qt6 tray app; `mcp/`: read-only MCP server
## Documentation
- **[DEVELOPER.md](DEVELOPER.md)** — architecture, code structure, build, testing, contributing
- **[API_CONTRACT.md](API_CONTRACT.md)** — control-socket protocol, access model, CLI + evidence JSON schemas
- **[PLAN.md](PLAN.md)** — current status, roadmap and milestones
- **[RESEARCH.md](RESEARCH.md)** — literature-backed rationale for the design and scope
- **[UX.md](UX.md)** — analyst workflow and the desktop-app direction
- **[OFFLINE_INSTALL.md](OFFLINE_INSTALL.md)** — air-gapped / pinned-dependency install
- **[docs/cli-ux.md](docs/cli-ux.md)** — CLI conventions (the `noun verb` command table, `--json` contract)
- **[docs/store-reduction.md](docs/store-reduction.md)** — opt-in scheduled telemetry reduction (stop, reduce, start)
- **[docs/](docs/)** — topic notes (false positives, tracker attribution) and the inspection-model `evaluation/` gates
- **[AGENTS.md](AGENTS.md)** / **[CLAUDE.md](CLAUDE.md)** — repo rules, per-change checks and guardrails (contributors + coding agents)
No vendored third-party code (`include/tinyfsm.hpp` is a single header).
Contributing: see [DEVELOPER.md#contributing](DEVELOPER.md#contributing).
## License
GPLv3 — GNU General Public License v3, see [LICENSE](LICENSE).