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>
611 lines
30 KiB
Markdown
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
|