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>
24 KiB
Strawberry Interface Contract
Strawberry exposes two local interfaces. Neither opens a network port. The
desktop app, the CLI and the MCP server (strawberry-mcp, for agents) are all
clients of these two.
- Control socket: a Unix socket served by the root daemon, for live status, operator actions (reload, rescan, rule updates), policy changes, and response actions (containment, quarantine, memory scan, suspend/kill).
- Evidence: the embedded database, read read-only by clients
(
Database::open_read_only()), and the CLI--jsonviews over it.
Access control
| What | Path (systemd install) | Owner / mode | Who can use it |
|---|---|---|---|
| Control socket | /run/strawberry/control.sock (macOS /var/run/strawberry/control.sock) |
root:strawberry 0660 (dir 0750) |
uid 0, the daemon's own uid, members of strawberry |
| Evidence DB | /var/lib/strawberry/database.db |
root:strawberry 0640 (dir 0750) |
members of strawberry (read-only) |
| Rules | /etc/strawberry/rules/ |
root 0700 |
root only |
The daemon re-checks peer credentials (SO_PEERCRED; macOS LOCAL_PEERCRED +
LOCAL_PEERPID) on every connection,
independent of the file mode. Configure the socket with control_socket_path
(empty disables it) and control_group in strawberry.conf.
Control socket protocol
- One request per connection.
- Request: a single verb terminated by
\n, at most 64 bytes. Plain verbs take no arguments; payload verbs take exactly one JSON line (see below);scan-fdtakes one passed file descriptor. Anything else (extra words, different case, unknown verbs) is rejected without running anything. - The read timeout is 2 s. A request with no newline is rejected.
- Reply: one JSON line, then the daemon closes the connection.
{"ok":true,"verb":"<verb>","data":<object>}
{"ok":false,"error":"<message>"}
Errors include permission denied, unknown command, request too long,
request timed out, empty request and rescan rate limited; retry in Ns.
status
{
"version": "0.1.0",
"pid": 1234,
"now_ns": 1792887028777076502,
"started_at_ns": 1792887022744355381,
"running": true,
"config_path": "/etc/strawberry/strawberry.conf",
"db_path": "/var/lib/strawberry/database.db",
"monitor": {
"enabled": true,
"backend": "bpf",
"execveat": true,
"fork_tracepoint": false,
"events": 72,
"events_dropped": 0,
"queue_depth": 0
},
"rules": {
"path": "/etc/strawberry/rules",
"required": true,
"loaded": true,
"files": 2,
"count": 5142,
"generation": 2,
"loaded_at_ns": 1792887025771774835,
"last_error": ""
},
"pipeline": {
"events": 72,
"scanned": 44,
"cache_hits": 28,
"detections": 1,
"images_unavailable": 0,
"images_too_large": 0,
"suppressed": 1,
"scan_errors": 0,
"persist_failures": 0,
"last_detection_ns": 1792887024282406813
},
"feeds": {
"dir": "/var/lib/strawberry/feeds",
"configured": [{"id": "yara-forge-core", "enabled": true}],
"state": {"feeds": [{"id": "yara-forge-core", "ok": true, "version": "20261018", "rules": 5137, "error": ""}]},
"allowlist_entries": 1,
"policy_error": ""
},
"prevention": {
"mode": "audit", "min_severity": "critical", "active": true, "error": "",
"marked_filesystems": 4, "checked": 812, "cache_hits": 790, "blocked": 0,
"would_block": 0, "timeouts": 0, "unscanned": 1
},
"behavior": {
"network_tracepoints": true, "file_watch": true, "file_watch_locations": 15, "file_watch_error": "",
"connects": 1204, "file_writes": 37, "detections": 0, "ioc_networks": 1688
},
"opensnitch": {
"integration": true, "installed": true, "checksums_enabled": true,
"rules_dir": "/etc/opensnitchd/rules", "containments": 0,
"blocklists": {"entries": {"domains": 124712, "ips": 1, "nets": 1687}, "error": "",
"rules": ["strawberry-ioc-domains", "strawberry-ioc-ips", "strawberry-ioc-nets"]}
}
}
- All
*_nsvalues are wall-clock nanoseconds since the Unix epoch. monitor.backendisbpf,procfs,endpoint_security,libprocornone.procfs(Linux) andlibproc(macOS) are polling fallbacks: eBPF or Endpoint Security was unavailable, and short-lived processes can be missed.- macOS:
behavior.network_tracepointsis alwaysfalse(Endpoint Security has no connect event);prevention.errorandbehavior.file_watch_errorname the missing ES requirement (root, entitlement, Full Disk Access). rules.generationincrements on every successful load.rules.last_erroris set when the most recent reload failed. The previous rules stay active.pipeline.images_unavailablecounts executions whose image was gone or replaced before it could be read.prevention.activeis false (witherror) when fanotify permission events are unavailable, for example withoutCAP_SYS_ADMIN.timeoutscounts executions allowed because no verdict arrived in time.resources(resource governor):profile,level(normal / warning / critical / emergency),host_busy,host_severe,own_cpu_pct(ofcpu_capacityCPUs),rss_mb/memory_budget_mb,host(PSI or loadavg,mem_available_mb),cgrouplimits,deferring(work classes waiting) andlongest_deferral_s, per-classworkcounters,guard_degraded,read_paced_ms,inventory_pending,memory_scans_skipped,large_scans_pending/large_scan_coalesced(uncached images over 8 MiB are scanned off the live path, once per image),worker_errors(events whose handling threw; skipped),thread_errors(threads stopped by an exception),swallowed_exceptions(exceptions recorded where nothing more could be done, e.g. in destructors or C callbacks; each is logged with file:line), effectivelimits.timings: per step{count, mean/p50/p95/p99/max_ms}forexec_decision,exec_assess,queue_wait,image_scan,yara_scan,db_commit,correlation,rule_compile,memory_scan;image_sizein MiB;bytes_read,yara_timeouts,memory_queue_depth. Percentiles are log2 bucket upper bounds (within 2×).behavior.network_tracepointsreports the connect/ptrace/module tracepoints.file_watchreports the fanotify persistence/drop watcher, which needs file-handle support, so it doesn't work on overlayfs.
reload-rules
{"reloaded": true, "error": ""}
Recompiles every .yar/.yara file under rules.path. On failure,
reloaded is false, error holds the first compiler message, and the
previous rule set keeps running.
rescan
{"queued": true}
Asks the monitor to re-emit every running process. The rescan runs on the
monitor thread, so this returns immediately. It is rate-limited to once per
30 s. A process image already scanned under the current rules generation is
not recorded twice, so rescan after reload-rules to apply new rules to
running processes.
scan-fd
The client opens a file with its own permissions and sends the verb line
plus exactly one open descriptor in the same sendmsg (SCM_RIGHTS). The
daemon never receives or resolves a path, so it can't be used to read files the
caller couldn't open.
{
"scanned": true,
"error": "",
"size": 47445,
"sha256": "<hex>",
"matches": [
{"rule": "Strawberry_Test_Marker", "severity": "low", "namespace": "default", "tags": [], "meta": "description=...; severity=low"}
]
}
- Regular files only, at most
scan_max_bytes(default 64 MiB). - The file is read into a private buffer before scanning. The hash and scan see the same bytes, and a caller truncating the file can't fault the daemon.
- Rate-limited to 300 scans/min. Results are not stored as evidence. Each scan is logged with the caller's uid/pid.
scan-fdwithout a descriptor, with more than one, or a descriptor attached to any other verb is rejected. Every received descriptor is closed.
policy
Read-only. Returns the operator policy and the updater's per-feed state:
{
"policy": {
"path": "/var/lib/strawberry/policy.json",
"feeds": [{"id": "yara-forge-core", "name": "YARA Forge core", "type": "github-release",
"repo": "YARAHQ/yara-forge", "asset": "yara-forge-rules-core.zip", "enabled": true,
"added_by": 0, "added_at": 0}],
"allowlist": [{"id": "allow-a964413a", "kind": "sha256", "value": "<hex>", "rule": "",
"note": "socat is a legit admin tool", "added_by": 1000, "added_at": 1792895972627876720}],
"history": [{"at": 1792895972627876720, "uid": 1000, "action": "allowlist-add", "summary": "sha256 <hex>"}]
},
"feed_state": {"updated_at": 0, "feeds": [{"id": "yara-forge-core", "ok": true, "version": "20261018",
"sha256": "<hex>", "rule_files": 1, "rules": 5137, "checked_at": 0, "updated_at": 0, "error": ""}]},
"feeds_dir": "/var/lib/strawberry/feeds",
"policy_error": ""
}
Payload verbs: allowlist-add, allowlist-remove, feed-add, feed-remove, feed-set-enabled
Format. The verb line is followed by exactly one JSON line of at most 8 KiB. Anything else is rejected:
- a missing payload line
- extra lines
- a payload attached to any other verb
Validation is strict, and unknown fields are rejected:
| Verb | Payload |
|---|---|
allowlist-add |
{"kind":"sha256","value":"<64 hex>","rule"?,"note"?}, {"kind":"path","value":"/abs/path or /dir/","rule"?,"note"?}, {"kind":"rule","value":"RuleName","note"?} |
allowlist-remove |
{"id":"allow-…"} |
feed-add |
{"id":"[a-z0-9-]{1,32}","name"?,"kind"?,"type":"github-release","repo":"owner/name","asset":"file.zip","enabled"?} or {"id":…,"kind"?,"type":"url","url":"https://…" | "urls":[1–10 URLs],"sha256"?,"auth_header_file"?}. kind is yara (default), hashes, domains, ips or nets; sha256 only with a single URL; auth_header_file is an absolute path to a root-only file holding one Header: value line, read by the updater |
feed-remove |
{"id":"…"} |
feed-set-enabled |
{"id":"…","enabled":true} |
Limits:
- 1000 allowlist entries, 20 feeds
- paths must be absolute and normalized
- URLs must be
https:// - rule names match
[A-Za-z0-9_]{1,128} - 30 changes per minute
Behavior.
- Every change is persisted atomically, recorded in
historywith the caller's uid, and logged. - Feed changes reload the rules immediately. Adding or enabling a feed also requests an update.
- Paths and URLs in the policy are stored strings: the root daemon never opens them. URLs are fetched only by the sandboxed updater.
Matching (process detections):
sha256suppresses every rule on that exact binary, optionally limited to onerule.pathmatches the resolved executable path exactly, or by prefix when it ends in/, optionally limited to onerule.rulesuppresses that rule everywhere.- Suppressed detections are counted in
pipeline.suppressedand are not stored. - On-demand
scan-fdmatches reportallowlisted_byinstead of being hidden.
Protection and response verbs
Same payload format and the same 30-changes-per-minute limit. They take hashes or ids, never paths: paths always come from Strawberry's own stored evidence, so the root daemon cannot be pointed at an arbitrary file. None of them are exposed through MCP.
| Verb | Payload | Effect |
|---|---|---|
protection-set |
any of {"contain_auto":bool,"contain_min_severity":"low…critical","prevention_mode":"off"|"audit"|"enforce","prevention_min_severity":"low…critical"} |
Saves protection settings and applies them live. Defaults: auto-contain on at high, prevention audit at critical. |
contain-add |
{"sha256":"<64 hex>"} |
Writes an OpenSnitch deny rule for a binary seen in stored evidence. Reply: {"containment":{"id","rule","hash_pinned","path","new"}}. |
contain-remove |
{"id":"contain-…"} |
Removes the rule (undo). |
quarantine |
{"sha256":"<64 hex>"} |
Blocks every execution of that exact binary in every prevention mode (the exec guard runs hash-only when prevention is off) and contains its network. The file is not moved. Reply: {"quarantined","path","execution_blocked","network_contained","network_error","note"}. |
quarantine-remove |
{"sha256":"<64 hex>"} |
Releases the quarantine and its containment. |
scan-memory |
{"node_id":"process_<pid>_<boot>_<start>"} |
Queues a YARA scan of the live process's memory (yr_rules_scan_proc, 30 s timeout). Matches are stored as source=memory indicators and become findings. Reply: {"queued":true,"pid","path"}. |
process-suspend / process-resume / process-kill |
{"node_id":"process_<pid>_<boot>_<start>"} |
SIGSTOP / SIGCONT / SIGKILL. Reply: {"done","pid","path"}. |
Process safety. Process verbs accept only the stable node id. The legacy
process_<pid> form is refused. The daemon resolves the pid from /proc, and
the boot id plus start time must match, so a reused PID can never be hit.
process-* verbs refuse:
- pid 1 and the daemon itself
- core session and system processes: systemd and its daemons, dbus, opensnitchd, the display server and compositor, display managers, sshd, polkitd, NetworkManager, PipeWire, Strawberry itself
Every action is recorded in policy history with the caller's uid.
Automatic actions (all recorded in history and shown in the app's Response tab):
- Containment. A stored detection at or above
contain_min_severity(not allowlisted, not in/usr,/bin,/sbin,/lib*,/bootor/etc) gets an OpenSnitch deny rule. It is pinned to the binary's MD5 when OpenSnitch hasEnableChecksums, otherwise path-only. - Exec prevention (fanotify
FAN_OPEN_EXEC_PERM, needsCAP_SYS_ADMIN):auditrecords "would have been blocked".enforcedenies withEPERMon an IOC hash match or a YARA match at or aboveprevention_min_severity.- System locations are never denied (alert only), allowlisted binaries are never denied, and quarantined binaries are always denied.
- An unanswered event is allowed after
prevention_timeout_ms(default 1000), and so are files larger thanprocess_scan_max_bytes.
- Memory scans run automatically for memfd executions, deleted non-system executables and ptrace targets (bounded queue, one at a time, each process scanned once).
update-rules
{"requested": true}
Touches <feeds_dir>/update-requested. The strawberry-update.path unit then
starts the updater. Rate-limited to once per 5 minutes.
Audit
Every request except status is logged as
[ControlServer] uid=<uid> pid=<pid> verb=<verb> result=ok|error. Denied peers
are logged too.
CLI equivalents
strawberry --status [--json] [config_path]
strawberry --reload-rules [config_path]
strawberry --rescan [config_path]
strawberry --scan-file <path> [config_path] # opened as you, sent via scan-fd
strawberry --policy [config_path]
strawberry --policy-set <verb> '<json>' [config_path] # any payload verb, e.g. quarantine '{"sha256":"…"}'
strawberry --opensnitch-enable-checksums # root: set Rules.EnableChecksums in OpenSnitch (keeps a .bak)
strawberry --request-rule-update [config_path]
Local, no socket:
strawberry --update-rules [config_path] # run the updater (what strawberry-update.service does)
strawberry --check-rules [config_path] # compile local + installed feed rules, print the count
Rule feeds and the updater
strawberry-update.service runs strawberry --update-rules:
- daily, via
strawberry-update.timer - on request, via
strawberry-update.path
It runs sandboxed: no capabilities, writes only /var/lib/strawberry/feeds,
network limited to IPv4/IPv6/Unix. For each enabled feed it:
- Resolves the release.
github-releaseusesGET /repos/<repo>/releases/latestand requires the asset's publishedsha256:digest.urluses the optional pinnedsha256. - Skips the feed if the version and digest are unchanged.
- Downloads over HTTPS only (TLS verified, ≤ 64 MiB, ≤ 3 redirects) and verifies the digest.
- Extracts only regular
*.yar/*.yaraentries, flattened to sanitized basenames. Symlinks, devices and traversal are dropped; ≤ 256 MiB extracted. - Compiles the staged rules together with the local rules and the other feeds. On failure the previous version stays active.
- Installs
feeds/<id>/<version>/and atomically switchesfeeds/<id>/current, keeping one previous version. - Writes
feeds/state.json, then sendsreload-rules.
The daemon loads yara_rules_path (default namespace) plus every enabled
feeds/<id>/current in namespace <id>. GitHub's anonymous API limit is
60 requests/hour per IP. On a 403/429 rate limit the updater keeps the current
rules and retries; github_token_file raises the limit.
Each prints the reply line. Exit codes:
0:ok:true1:ok:false2: could not reach the daemon
Threat-intel list feeds
List feeds (kind hashes, domains, ips, nets) use the same pipeline,
with these differences:
- They download one or more URLs.
- Lines are parsed after stripping
#/;comments and hosts-file prefixes. Each entry is validated (64-hex SHA-256, domain syntax,inet_pton, CIDR no broader than /8 for IPv4 or /16 for IPv6, checked again when loaded), deduped and capped (5M hashes, 2M domains, 1M IPs/nets). - A normalized
list.txtis installed under the samecurrentswitch. - Shrink guard: a new list under 10% of the previous size is rejected as truncated, and the old one stays.
Default feeds, seeded once (a default you remove stays removed):
| id | kind | Source |
|---|---|---|
yara-forge-core |
yara | YARAHQ/yara-forge core release |
malware-hashes |
hashes | romainmarcoux/malicious-hash full-hash-sha256-aa.txt |
cert-pl-domains |
domains | CERT Polska hole.cert.pl/domains/v2/domains.txt |
spamhaus-drop |
nets | Spamhaus DROP |
feodo-c2 |
ips | abuse.ch Feodo Tracker recommended C2 IPs |
Hash feeds become the IOC_KnownMalwareHash detection (critical,
source=ioc). IP and net feeds drive the IOC_Connection behavior rule.
Domain, IP and net feeds are also exported to OpenSnitch.
YARA severity comes from meta.severity, else meta.score (≥ 90 critical,
≥ 70 high, ≥ 40 medium, else low).
OpenSnitch files
When opensnitch_integration=true and opensnitch_rules_dir (default
/etc/opensnitchd/rules) exists, the daemon writes only strawberry-*.json
files there (mode 0600, written atomically). OpenSnitch reloads them on change.
| File | Rule |
|---|---|
strawberry-ioc-domains.json, -ips.json, -nets.json |
deny, precedence, operator lists.domains / lists.ips / lists.nets over <state_dir>/opensnitch/lists/<kind>/strawberry.txt (domains as 0.0.0.0 host) |
strawberry-contain-<sha256[0:12]>.json |
deny, precedence, process.path and (with checksums) process.hash.md5 |
List rules are refreshed after each feed update and removed when no list feed is enabled.
Evidence (read-only)
strawberry --list-findings --json [config_path]
strawberry --show-finding <finding_id> --json [config_path]
strawberry --search-process <query> --json [config_path]
strawberry --trace-process <pid> [--trace-depth n] [config_path]
strawberry --trace-node <node_id> [--trace-depth n] [config_path]
These open the database read-only and never write back, so they are safe to run while the daemon is active.
GraphNode
{
"id": "process_654_a902af2e_9798407",
"type": "process",
"properties": {
"pid": "654",
"path": "/tmp/payload",
"hash": "<sha256>",
"cmdline": "payload --flag",
"parent_pid": "1",
"parent_node_id": "process_1_a902af2e_12",
"start_time_ticks": "9798407",
"boot_id": "<hex>",
"exe_deleted": "true",
"exe_memfd": "true",
"event_timestamp_ns": "1792887024282406813"
}
}
Node types:
processfile(file_<sha256>)indicator
Process IDs have the form process_<pid>_<boot8>_<start_ticks>, so a reused
PID does not merge different processes. Older evidence and synthetic data may
still use process_<pid>. Properties are string→string and may be absent.
Finding
{
"id": "finding_process_yara_...",
"title": "YARA match on executed process image",
"severity": "high",
"score": 85,
"summary": "Process 429675 executed /memfd:payload ... matched 2 indicators (MemfdExecution, Strawberry_Test_Marker).",
"first_seen": 1792887024282406813,
"last_seen": 1792887024282406813,
"related_node_ids": ["process_429675_a902af2e_9798410", "file_<sha256>", "indicator_process-hit:..."],
"related_indicator_ids": ["process-hit:..."],
"metadata": {
"engine": "strawberry-rule-correlation-v1",
"rule": "process_executable_yara_match",
"process_node_id": "process_429675_a902af2e_9798410"
}
}
- Correlation rules:
process_executable_yara_matchlineage_multiple_yara_matchessame_hash_multiple_process_matchessame_yara_rule_multiple_processes
- Heuristic-only process findings are titled "Suspicious executed process
image". They come from indicators with
source=heuristic:MemfdExecution(high)DeletedExecutable(low)
ProcessSearchResult
{
"process": { "id": "process_654_...", "type": "process", "properties": {} },
"matched_fields": ["pid", "finding"],
"first_seen": 123456780,
"last_seen": 123456789,
"parent_process": null,
"child_processes": [],
"related_nodes": [],
"findings": []
}
MCP server (strawberry-mcp)
MCP over stdio (newline-delimited JSON-RPC 2.0). Supported protocol versions:
2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. stdout carries
protocol messages only; logs go to stderr.
claude mcp add strawberry -- strawberry-mcp # full
claude mcp add strawberry -- strawberry-mcp --read-only # queries only
Flags:
--config(where to readcontrol_socket_path; default/etc/strawberry/strawberry.conf)--socket--db(default: the path the daemon reports)--read-only
| Tool | Arguments | Read-only mode |
|---|---|---|
strawberry_status |
— | yes |
strawberry_list_findings |
min_severity (low/medium/high/critical), since_ns, limit 1–200 (50) |
yes |
strawberry_get_finding |
id |
yes |
strawberry_search_processes |
query, limit 1–50 (20) |
yes |
strawberry_get_process |
node_id, trace_depth 0–4 (2) |
yes |
strawberry_get_policy |
— (feeds, allowlist, update state; agents cannot change policy) | yes |
strawberry_scan_paths |
paths (1–20 absolute), recursive (false), max_files 1–2000 (200) |
hidden |
strawberry_reload_rules |
— | hidden |
strawberry_rescan |
— | hidden |
Results. Each result carries a one-line text summary, the JSON as text,
and the same JSON in structuredContent. Finding and node objects use the
same shapes as the CLI --json output; a test checks they match.
Errors.
- Schema violations and unknown tools: JSON-RPC
-32602. - Execution failures (daemon down, missing finding, evidence unreadable): a
result with
isError: true.
strawberry_scan_paths opens files with O_NOFOLLOW as the calling user.
- It doesn't follow symlinks or descend into
/proc,/sysor/dev. - It reports unreadable files without contacting the daemon.
- It returns only matching files, errors and skipped entries, plus counts.
Untrusted data. Paths, command lines and rule metadata originate on the
monitored host and may be attacker-written. The server's instructions tell
agents to treat them as data. String fields are capped at 4 KiB, and invalid
UTF-8 is replaced.