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>
555 lines
24 KiB
Markdown
555 lines
24 KiB
Markdown
# 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":"<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`
|
||
|
||
```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": "<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-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": "<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 `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_<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*`, `/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 `<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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```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/<repo>/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/<id>/<version>/` and atomically switches `feeds/<id>/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/<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: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 `<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)
|
||
|
||
```bash
|
||
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
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
- `process`
|
||
- `file` (`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
|
||
|
||
```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_<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_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.
|