strawberry/API_CONTRACT.md
trvon a4179c474d
docs: say what the gate actually enforces, and what a passing verdict needs
The gate's own documentation claimed more than the tool did, in ways that
mattered once the integrity checks landed.

- "passes only if all 9 cells pass" was enforced by scripts, not by the gate; it
  is now enforced (previous commit) and the text says which criterion the tool
  applies: complete evidence, refused false, every pooled cell passing.
- The model digest proves agreement ACROSS reports. It cannot prove that the
  file on disk now is the one that was evaluated. Corrected everywhere.
- The remedy was described inconsistently: cutting the training bundles earlier
  is NOT enough (evaluation still replays the whole store), a bounded evaluation
  range is required. Written consistently, with --eval-after NS|auto.
- scripts/fleet_e2e.sh asserted three gate checks; promotion_gate emits five. It
  now asserts >= 5, requires the provenance fields, and adds the honest-evidence
  invariant: today every cell is in-sample, so at least one cell must report
  in_sample true, none may pass, and each must carry the out-of-sample failure.
  A pass over in-sample cells is itself a failure.
- The Salt/range runbooks advertised the flow as producing promotion evidence;
  it collects gate INPUT, and a passing verdict requires out-of-sample windows.
2026-11-19 17:30:35 -07:00

846 lines
44 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

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

# Strawberry 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,
"cache": "hit",
"load_ms": 212,
"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,
"evidence_only": 0,
"repeats_aggregated": 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.cache` is the compiled-rules cache outcome of the last load: `hit`
(loaded `rules.yrc`), `miss` (compiled, then cached), `disabled`
(`rules_cache_dir` empty) or `error` (cache unusable or unwritable; rules
were compiled from source). `rules.load_ms` is that load's wall time.
- `rules.partitions` (rule partitioning, `rule_partitions=true` by default):
`state` (`off` | `building` | `ready` | `disabled`), `reason` (why disabled,
e.g. an `include` directive or a rule-count mismatch: scans then use the
full rule set), `subsets` (compiled subsets, capped by
`rule_partition_budget_pct`), `total_rules`, `kept_rules` and `scans` per
partition (`nonpe_lt1m`, `nonpe_1to4m`, `nonpe_4to16m`, `nonpe_ge16m`,
`pe_*`; a partition without a subset reports `total_rules` kept), and
`full_scans` (scans that used the full set: process memory, partitions
without a subset, or before the subsets are ready). File and buffer scans
use the subset whose rules can match the file's type (MZ or not) and size;
results are identical to the full set.
- `replay --policy-eval --eval-model FILE... --periods N --json` adds
`policy_eval.cells`: one per (eval model, period) with `model` (file name),
`period` (0-based), `start_ns`/`end_ns`, `windows`, `extra_positives`,
`rule_detected` and `policies` (`model`, `rarity_greedy`: inspections,
cpu_seconds, hits, weighted_hits, budget_refusals). Each cell also carries
`model_sha256` (first 16 hex of the model file's sha256),
`training_range_known`, `training_first_ns`/`training_last_ns` (the windows the
model was trained on, recorded by `model train`/`fleet train`; `0`/`false` means
unknown), `eval_first_ns`/`eval_last_ns` (the windows it evaluated) and
`in_sample` (the two ranges overlap) and `eval_error` (why a run produced no
out-of-sample window, empty when one did). `policy_eval.provenance` is the same block
for the single-model evaluation, and `policy_eval.models` lists each distinct
(model, digest, training range) in the report. `strawberry fleet gate DIR`
[--json]` pools the cells of every `*.json` report in DIR and applies the
promotion gate to each: `{passed, complete, expected_cells, reports, refused,
errors, cells: [{model, period, nodes, windows, extra_positives, model_hits,
model_cpu_seconds, rarity_hits, rarity_cpu_seconds, model_sha256,
training_range_known, training_first_ns, training_last_ns, eval_first_ns,
eval_last_ns, in_sample, provenance_incomplete, provenance_unknown_nodes,
passed, checks}]}`. `passed` is true, and the process exits 0, only if nothing
was refused (`refused: false`), the report set covers the pre-registered matrix
(`complete: true`; `expected_cells` is 3 training seeds x 3 replay periods, and
every contributing node must have reported the same set of models and periods),
and every pooled cell passed. An incomplete or mixed set therefore yields no
verdict, instead of a verdict over the cells that happen to be present. A cell
without a digest, or a (model, period) cell whose digests disagree across
reports, is refused (`refused: true` plus an `errors` entry) instead of pooled.
What a digest proves is only agreement across the reports in this set, not that
the file on disk now is the file that was evaluated: a model replaced after its
reports were written leaves reports that still agree with each other and
describe bytes the node no longer has. The gate also fails a cell whose
rarity-greedy baseline has 0 hits or 0 CPU-seconds
(`FAIL: degenerate baseline: ...`), a cell whose evaluation overlaps its model's
training range or whose model has no recorded range
(`FAIL: out-of-sample: ...`), and a pooled cell where any contributing node could
not prove a training or evaluation range (`FAIL: provenance incomplete: ...`,
`provenance_incomplete: true`, with `provenance_unknown_nodes` counting those
reports: an unknown range is never replaced by another node's known one).
- `replay --policy-eval --eval-after NS|auto` is the bounded evaluation range. `NS` is an absolute
unix-ns bound; `auto` is the latest training-range end among the `--eval-model` files (0/unbounded
when none records a range). Windows starting before the bound - and before the warm-up, whichever is
later - are excluded from ranking, from injected-trace placement and from the evaluation, so each
cell's `start_ns`/`end_ns`, `windows`, `extra_positives`, `eval_first_ns`/`eval_last_ns` and policies
describe only the bounded span, and `in_sample` is false unless a model's training range still
extends into it. A run that leaves no window at all publishes `policy_eval.provenance.eval_error`
(the same key on each cell) with the reason, and `promotion_gate` reports it verbatim inside
`FAIL: out-of-sample: ...` instead of judging a 0-window cell. The replay side is in place
(`ReplayOptions::eval_after_ns`, `eval_after_from_models()`); the CLI flag itself is landing in
parallel and is not parsed by this build yet. Without a bound, in-sample evidence cannot pass the
gate: a replay scores every window after the warm-up, so replaying the history a model trained on
fails with `FAIL: out-of-sample: ...`, and cutting the training bundles earlier does not help
because the node still replays its whole store.
- `pipeline.guard_partial_scans` counts exec-guard scans of loaded ELF
segments only (`guard_loaded_segments_only`, off by default).
- `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`, `block_io_util_pct`: maximum block-device utilization
over the interval since the previous sample, diagnostic only (`-1` means
unknown: first sample, unreadable/oversized snapshot, or a new/reset
device). It never weakens a pressure decision: host pressure is fail-safe,
and global I/O PSI also counts waits with no block-device counter
(FUSE/network-backed I/O, display page flips), so idle disks do not prove
pressure is benign), `cgroup` limits
(`memory_max_mb`, `memory_current_mb`,
`memory_high_mb`, `memory_high_events` (kernel throttle events),
`memory_full_pct` (own `memory.pressure` full avg10) and `throttled` (full
>= 20%: the daemon is stalled at MemoryHigh, and exec-guard launches wait with
it)), `scan_buffers` (`budget_mb` = the effective (cgroup-`memory.max`-capped)
memory budget / 4, minimum 32 MiB; `in_flight_mb`,
`peak_mb`, `waits`, `refused`: in-memory image copies are budgeted; the exec
guard streams-hashes an image over `guard_full_scan_max_mb` or when no budget
is free, deciding on hash / IOC / quarantine), `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`.
- `store` (evidence/telemetry store): `floor` (ok / soft: telemetry paused /
hard: evidence can no longer be saved, alerts still fire), `free_mb`,
`total_mb`, `soft_floor_mb`, `generation` (manifest), and per stream
(`evidence`, `telemetry`): `sealed_segments`, `bytes` (on disk), `raw_bytes`
and `records` (sealed), `compression_ratio`, `dropped_records` (refused by
the floor), `gaps_recorded`, `deleted_segments` (retention/eviction),
`failed`, `error`.
- `privacy` (tracker attribution, advisory only;
[docs/tracker-attribution.md](docs/tracker-attribution.md)): `enabled`,
`strength` (`circumstantial`), `tracker_domains` and `lists` (loaded
`trackers` feeds), `error`, `listener` (the daemon's AF_UNIX ingest socket fed
by the host-namespace relay: `source` `opensnitch-relay`, `ingest_socket`
path, `relay_events` the TCP address the relay binds, `listening`, `path`,
`error`, `connections`, `rejected_peers` (not a root peer), `events`,
`parse_errors`, `oversized`), `contacts` (`keys` program x domain, `programs`,
`events`, `dropped` when the 20000-key bound is full).
- Control verb `privacy-trackers` (read, like `status`): `{contacts: [{program,
domain, feed, uid, port, count, first_ns, last_ns}], strength, since_ns,
listening}`, sorted by program then domain, since the daemon started.
Telemetry keeps a root-only `tracker_contact` record (type 25: ts, program,
uid, domain, feed, port, count since the key's previous record, source) on
a key's first contact and then at most hourly. Never a finding, never a
block; command lines and environments from OpenSnitch are never stored.
- Control verb `doctor` (read, like `status`): `{healthy, checks: [{id,
status: ok|info|warn|problem, summary, action, advice}]}`. Checks:
`store.health`, `store.growth` (telemetry MiB/day and days until the disk
floor when retention is unlimited), `store.leftovers`,
`resources.memory` (problem when the daemon is throttled at its cgroup
MemoryHigh; absent when the pressure file is unreadable),
`findings.superseded`, `findings.allowlisted` (warn when a managed finding's
complete supporting evidence is now allowlisted), `retro_hunt`, `daemon.errors`, `logs`, `model`,
`model.rarity_state` (warn, only when the live rarity state could not be
loaded or saved).
- Control payload verb `maintain` (privileged, rate limited and audited like
policy changes): `{"action": "retire-superseded-findings" |
"retire-allowlisted-findings" | "clean-store", "dry_run": bool,
"min_age_days": n}`. `retire-superseded-findings` removes findings replaced by
a stable-id one; `retire-allowlisted-findings` removes this engine's findings only when
every supporting indicator is available and matches the actual allowlist
`(hash, path, rule)` predicate. A hash entry scoped to an IOC rule does not
clear independent YARA evidence; missing/capped support is left for full
recomputation. Allowlist add/remove schedules that rebuild on the existing
correlation loop, including withdrawal of unsupported managed findings and
restoration of evidence after removal. Both leave retirement in stream history. `clean-store`
deletes orphan/ files older than `min_age_days` (default 7) and
interrupted-compaction temp files, never a file the manifest lists.
- `retro_hunt` (re-scan of binaries seen before, after a rules change):
`enabled`, `running`, `total` / `done` for the current pass, `scanned`
(same content still on disk), `changed` (the path holds different
content), `missing`, `hits` (binaries with new matches), `passes`
completed since start, `rules_digest` (current rules, first 16 hex),
`last_completed_ns`, `last_rules_digest`, `last_hits`. Hits are stored as
indicators with `scan_kind: retro_hunt` and show as findings titled
"YARA match on a binary that ran here (found after a rules update)".
- `model` (inspection model, Stage 4): `kernel` (scalar | avx2 | neon),
`shadow_enabled`, and when enabled `shadow_active` (a valid shadow.sbm is
loaded), `generation`, `windows` / `warmup_windows` seen live,
`decisions`, `explored`, `by_action` counts, `would_spend_seconds_this_hour`,
`budget_refusals`, `error` (why the shadow model is not used). Shadow
decisions are logged as `inspection_action` telemetry records and never
executed. Additive acting fields: `acting`, `promoted_generation`,
`act_decisions`, `act_by_action`, `act_estimated_spend_seconds_this_hour`,
`act_budget_refusals`, `action_queue_drops`, `decision_record_drops`,
`promoted_error`. `executor` contains `submitted`, `queue_full`,
`queued_memory_scans`, `deep_rescans`, `matches`, `skipped` (executor-level
counters; queued memory-scan completion is recorded separately in telemetry).
`rarity_state` (the live rarity model, kept in `model_dir/rarity.state`,
saved hourly and at stop, restored at start): `restored`, `warmup_skipped`
(a restored state younger than the 7-day half-life skips the 1 h warm-up),
`restored_saved_ns`, `last_saved_ns` (0 until the first save),
`load_error`, `save_error` (empty when fine; a refused file is replaced by
the next save).
Acting requires an explicitly promoted execution-policy-compatible model;
an old promotion file is refused, not silently activated. See
[the execution gate](docs/evaluation/stage4-execution-gate.md).
`inspection_action.shadow=false` identifies acting decisions. The root-only
`inspection_outcome` record carries timestamp, stable root node, action,
status, detail, matches, duration in microseconds and model generation.
Status is `queued`, `scanned`, `duplicate`, `skipped_exited`,
`skipped_protected`, `deferred`, `queue_full`, `failed`, `unsupported`,
`revoked`, `stopped` or `not_recorded`. `queued` is not proof of a scan;
memory jobs emit a second outcome when finished or refused.
- `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`, `model_inspection`; `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`, `nets` or `trackers` (privacy list, advisory only); `max_severity`? (`critical`\|`high`\|`medium`\|`low`) sets the severity an IOC hash match from the feed reports at — default advisory `high`, only `critical` forces prevention; `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`, `trackers`) use the
same pipeline, with these differences:
- `trackers` lists are privacy labels, never threat intel: they are never
exported to OpenSnitch, never block and never raise a finding
([docs/tracker-attribution.md](docs/tracker-attribution.md)). They also take
adblock whole-domain rules (`||host^`, `||host^$third-party`); other adblock
rules (cosmetic, exceptions, paths, other options) are skipped.
- 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`
- Multi-process findings include string metadata `process_instance_count` and
`unique_pid_count`; the summary counts stable process instances, not just
numeric PIDs. Existing PID lists are unchanged.
- Shared-rule identity includes `rule_source`, `rule_namespace` and the existing
`matched_rule`. Different namespaces/source domains never group solely by bare
name (`demo` uses the YARA domain). Missing legacy namespaces remain unknown,
separate from known `default`/feed namespaces. Legacy YARA/unknown-namespace
ids stay stable; other rule ids use a typed, length-prefixed identity. A full
correlation rebuild retires obsolete managed ids using existing history
records; it does not erase raw indicators or other engines' findings.
- Full reconciliation is shared by the daemon and the existing offline
`--correlate` compatibility entrypoint. The latter reads an immutable allowlist
before opening a writer: a missing policy means no allowlist and is never
seeded; corrupt/inaccessible policy exits 3 (empty stdout in JSON mode), rather
than rebuilding with an accidentally empty policy. Reading an existing legacy
policy does not migrate it or change its bytes. No new command/control verb or
record format is introduced. Unlike replay diagnostics, correlation is an
explicit evidence-store mutation.
- 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": []
}
```
## Offline replay diagnostics (CLI only)
```bash
strawberry replay [store_dir] --training-summary [--warmup H] [--json] [--config FILE]
```
This is a read-only, aggregate extension of the existing replay engine. It uses
its final-label resolver and actual seeded sample, not another readiness engine,
policy executor or trainer. It does not load/train/save an inspection model,
contact the daemon, mutate the store, take its writer lock, recover files, create
a snapshot or change permissions. Supply an already readable cooperative
immutable snapshot, or configure its `db_path` locally. With neither, the mode
fails instead of discovering the live store through status RPC.
Summary mode rejects `--model`, `--policy-eval`, `--inject`, `--inject-copies`
and `--top` before opening inputs, even when the explicitly supplied value is
the default. It uses sampler defaults `max_examples=50000`,
`max_entity_share=0.01`, `sample_seed=1`; there are no new tuning flags.
A summary requires a valid **current** `MANIFEST`, successful complete scans of
all listed evidence/telemetry segments, no malformed labels or corrupt blocks,
no invalid sealed footer/counts, and no torn active tail. Every listed block must
also be *decodable*: a block that needs a zstd dictionary this build does not
have (or memory it could not get) and a complete block header that fails
validation are both unusable input, not an empty stream. The only tail a strict
reader tolerates is a short one an active writer still owns. Such segments are
observed per segment, not just through the last aggregate tail error. Decoded
manifest identity/generation and both stream active extents must match
before/after the replay. This is an **unchanged-observed-extents check**, not atomic snapshot
capture or proof against an adversarial filesystem. A stream with no listed
segments can be empty; a missing listed file/directory cannot.
Ordinary replay retains valid fragment/fallback-manifest and active-tail support,
but now rejects missing/skipped/invalid listed segments and malformed evidence.
`replay_store` returns an explicit internal failure category and no usable
partial report/examples on an error; this intentionally also protects offline
trainer loader callers without changing training/split/model algorithms.
On success JSON is exactly one document with the following additive schema:
| Key | Shape / meaning |
| --- | --------------- |
| `schema_version` | integer `1` |
| `mode` | fixed `"training_summary"` |
| `data_status` | fixed `"available"`: structural source checks passed, not label quality/readiness |
| `assessment` | always `"not_assessed"` |
| `telemetry_empty` / `sample_empty` | separate booleans; warm-up can leave an empty sample in nonempty telemetry |
| `snapshot` | `manifest_generation`, `check: "unchanged_observed_extents"`, `evidence_active_bytes`, `telemetry_active_bytes`, both streams' `*_segments` and scanned `*_bytes` |
| `coverage` | existing aggregate records, undecodable, execs, scans, windows/warmup, detected/late-detected, behavior/file/persistence/unjoined/gap/late counts and `first_ns`/`last_ns`; no window arrays |
| `labels` | raw decodable `records`, `positive`/`negative`/`retracted`; fixed `provenance` and `actions` buckets; `missing_hash`, `idless_allowlist`, `timestamp_known`/`timestamp_unknown`, `first_ns`/`last_ns`; `resolved_positive_hashes`, `resolved_negative_hashes`, `overlap_hashes` |
| `sample` | `collected`, `seed`, configured `max_examples`/`configured_max_entity_share`, `effective_capacity`, `entity_cap`, `positive_quota`; `eligible`/`eligible_positive`/`eligible_zero_label`, `retained`/`retained_positive`/`retained_zero_label`; actual `entities`, `max_entity_examples`, `max_entity_share`, anonymous descending `top_entity_counts` (at most five); `unfilled_capacity`, positive/zero-label entity-refusal counts |
| `limits` | fixed warning identifiers listed below; not an approval rubric |
| `timings` | `unit: "wall_microseconds"`, `replay` and `summary_build` histograms with `count`, `sum`, `p50`, `p95`, `p99`, `max` |
Provenance buckets are `operator`, `allowlist`, `other`. Action buckets are
`quarantine`, `quarantine-remove`, `allowlist-add`, `allowlist-remove`,
`contain-add`, `contain-remove`, `process-kill`, `process-suspend`,
`process-resume`, `suppressed`, `other`. Unknown strings increment `other`;
they never become JSON keys. Nonpositive label timestamps count as unknown;
no known timestamp is represented by zero `first_ns`/`last_ns`. Resolved positive
and negative sets can overlap; suppression takes precedence in the actual sample.
An empty sample has `max_entity_share: null` and `top_entity_counts: []`, not a
claim of zero concentration. The configured combined cap is a fraction of
configured/effective capacity, not of an underfilled retained sample. Zero-label
examples include unlabeled and suppressed windows, not proven benign activity.
No host node, executable, command-line, rule, hash, entry-id, raw source/action or
model-path strings are emitted by summary JSON or its concise human table.
`limits` always includes `retrospective_final_labels`,
`zero_label_includes_unlabeled_and_suppressed`, `nonuniform_constrained_sample`,
`cap_is_fraction_of_configured_capacity_not_actual_sample`,
`teacher_versions_and_maturity_not_assessed`,
`point_in_time_splits_not_assessed`,
`resolver_memory_scales_with_evidence`,
`rss_and_actual_inspection_cpu_budget_not_measured`, and
`not_training_or_promotion_approval`. This does not replace the unchanged separate
three-period × three-seed promotion/execution contracts. CLI wall histograms and
Tracy zones are separate from deterministic semantics; they measure neither
actual inspection CPU nor RSS and are not a three-repeat KPI result.
Ordinary replay JSON adds `examples_collected` without changing existing key
types. It remains `false` unless collection was requested: zero uncollected
sample counters are not evidence of an empty training corpus. Summary mode
collects through the same sampler and reports actual retained classes, not raw
or deduplicated detection counts.
Errors emit stderr, **empty stdout** (no partial/success JSON), and nonzero exit:
usage/conflicting options `2`, unavailable/observably changed source `3`, invalid
segment/block/label data `1`. A block requiring a dictionary the build does not
have is *unavailable* (`3`); a complete block header that fails validation is
*invalid* (`1`). Sealed footer/manifest counts are only compared when every block
decoded, so a missing decoder is not reported as corruption. Successful `store verify --json` config chatter is
now captured so stdout is one document, but verifier `ok: true` can still coexist
with skipped/unreadable-coverage `notes`; it is not a full-coverage/readiness
verdict. The stricter replay source checks are independent of that flag.
No new control verb, MCP tool or persistence record is introduced.
## 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.