# 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. 1. **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). 2. **Evidence**: the embedded database, read **read-only** by clients (`Database::open_read_only()`), and the CLI `--json` views 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-fd` takes 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. ```text {"ok":true,"verb":"","data":} {"ok":false,"error":""} ``` Errors include `permission denied`, `unknown command`, `request too long`, `request timed out`, `empty request` and `rescan rate limited; retry in Ns`. ### `status` ```json { "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 `*_ns` values are wall-clock nanoseconds since the Unix epoch. - `monitor.backend` is `bpf`, `procfs`, `endpoint_security`, `libproc` or `none`. `procfs` (Linux) and `libproc` (macOS) are polling fallbacks: eBPF or Endpoint Security was unavailable, and short-lived processes can be missed. - macOS: `behavior.network_tracepoints` is always `false` (Endpoint Security has no connect event); `prevention.error` and `behavior.file_watch_error` name the missing ES requirement (root, entitlement, Full Disk Access). - `rules.generation` increments on every successful load. - `rules.last_error` is set when the most recent reload failed. The previous rules stay active. - `pipeline.images_unavailable` counts executions whose image was gone or replaced before it could be read. - `prevention.active` is false (with `error`) when fanotify permission events are unavailable, for example without `CAP_SYS_ADMIN`. `timeouts` counts executions allowed because no verdict arrived in time. - `resources` (resource governor): `profile`, `level` (normal / warning / critical / emergency), `host_busy`, `host_severe`, `own_cpu_pct` (of `cpu_capacity` CPUs), `rss_mb` / `memory_budget_mb`, `host` (PSI or loadavg, `mem_available_mb`), `cgroup` limits, `deferring` (work classes waiting) and `longest_deferral_s`, per-class `work` counters, `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), effective `limits`. - `timings`: per step `{count, mean/p50/p95/p99/max_ms}` for `exec_decision`, `exec_assess`, `queue_wait`, `image_scan`, `yara_scan`, `db_commit`, `correlation`, `rule_compile`, `memory_scan`; `image_size` in MiB; `bytes_read`, `yara_timeouts`, `memory_queue_depth`. Percentiles are log2 bucket upper bounds (within 2×). - `behavior.network_tracepoints` reports the connect/ptrace/module tracepoints. `file_watch` reports the fanotify persistence/drop watcher, which needs file-handle support, so it doesn't work on overlayfs. ### `reload-rules` ```json {"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` ```json {"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. ```json { "scanned": true, "error": "", "size": 47445, "sha256": "", "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-fd` without 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: ```json { "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": "", "rule": "", "note": "socat is a legit admin tool", "added_by": 1000, "added_at": 1792895972627876720}], "history": [{"at": 1792895972627876720, "uid": 1000, "action": "allowlist-add", "summary": "sha256 "}] }, "feed_state": {"updated_at": 0, "feeds": [{"id": "yara-forge-core", "ok": true, "version": "20261018", "sha256": "", "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 `history` with 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): - `sha256` suppresses every rule on that exact binary, optionally limited to one `rule`. - `path` matches the resolved executable path exactly, or by prefix when it ends in `/`, optionally limited to one `rule`. - `rule` suppresses that rule everywhere. - Suppressed detections are counted in `pipeline.suppressed` and are not stored. - On-demand `scan-fd` matches report `allowlisted_by` instead 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___"}` | 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___"}` | SIGSTOP / SIGCONT / SIGKILL. Reply: `{"done","pid","path"}`. | **Process safety.** Process verbs accept only the stable node id. The legacy `process_` 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*`, `/boot` or `/etc`) gets an OpenSnitch deny rule. It is pinned to the binary's MD5 when OpenSnitch has `EnableChecksums`, otherwise path-only. - **Exec prevention** (fanotify `FAN_OPEN_EXEC_PERM`, needs `CAP_SYS_ADMIN`): - `audit` records "would have been blocked". - `enforce` denies with `EPERM` on an IOC hash match or a YARA match at or above `prevention_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 than `process_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` ```json {"requested": true} ``` Touches `/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= pid= verb= result=ok|error`. Denied peers are logged too. ### CLI equivalents ```bash strawberry --status [--json] [config_path] strawberry --reload-rules [config_path] strawberry --rescan [config_path] strawberry --scan-file [config_path] # opened as you, sent via scan-fd strawberry --policy [config_path] strawberry --policy-set '' [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: ```bash 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: 1. Resolves the release. `github-release` uses `GET /repos//releases/latest` and requires the asset's published `sha256:` digest. `url` uses the optional pinned `sha256`. 2. Skips the feed if the version and digest are unchanged. 3. Downloads over HTTPS only (TLS verified, ≤ 64 MiB, ≤ 3 redirects) and verifies the digest. 4. Extracts only regular `*.yar`/`*.yara` entries, flattened to sanitized basenames. Symlinks, devices and traversal are dropped; ≤ 256 MiB extracted. 5. Compiles the staged rules together with the local rules and the other feeds. On failure the previous version stays active. 6. Installs `feeds///` and atomically switches `feeds//current`, keeping one previous version. 7. Writes `feeds/state.json`, then sends `reload-rules`. The daemon loads `yara_rules_path` (default namespace) plus every enabled `feeds//current` in namespace ``. 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:true` - `1`: `ok:false` - `2`: 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.txt` is installed under the same `current` switch. - **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 `/opensnitch/lists//strawberry.txt` (domains as `0.0.0.0 host`) | | `strawberry-contain-.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) ```bash strawberry --list-findings --json [config_path] strawberry --show-finding --json [config_path] strawberry --search-process --json [config_path] strawberry --trace-process [--trace-depth n] [config_path] strawberry --trace-node [--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 ```json { "id": "process_654_a902af2e_9798407", "type": "process", "properties": { "pid": "654", "path": "/tmp/payload", "hash": "", "cmdline": "payload --flag", "parent_pid": "1", "parent_node_id": "process_1_a902af2e_12", "start_time_ticks": "9798407", "boot_id": "", "exe_deleted": "true", "exe_memfd": "true", "event_timestamp_ns": "1792887024282406813" } } ``` Node types: - `process` - `file` (`file_`) - `indicator` Process IDs have the form `process___`, so a reused PID does not merge different processes. Older evidence and synthetic data may still use `process_`. Properties are string→string and may be absent. ### Finding ```json { "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_", "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_match` - `lineage_multiple_yara_matches` - `same_hash_multiple_process_matches` - `same_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 ```json { "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. ```bash claude mcp add strawberry -- strawberry-mcp # full claude mcp add strawberry -- strawberry-mcp --read-only # queries only ``` Flags: - `--config` (where to read `control_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`, `/sys` or `/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.