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.
846 lines
44 KiB
Markdown
846 lines
44 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,
|
||
"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.
|