strawberry/API_CONTRACT.md
trvon db4c49155f
yara: rule partitions — scan each file only with the rules that can match it
Why YARA-X scanned ~1.6x faster than libyara (perf + source audit, 2026-11-14):
not the language — both spend ~5 s in the atom search loop — but verification
(libyara 2.0 s vs 0.3 s). YARA-X derives filesize bounds and header constraints
per rule at compile time and disables those patterns before the search, so their
atom hits are dropped with one bit test. In the yara-forge core pack 1787 rules
require an MZ header and 2498 bound filesize, so for big Linux ELFs most of
libyara's verification is wasted.

Rule partitioning gets the same win with libyara, and drops the rules' atoms from
the automaton entirely:
- src/rule_partition.cpp (pure): lexer-aware splitter (comments, text, regex
  after = or matches, hex), facts from TOP-LEVEL `and` terms only (MZ /
  pe.is_pe, ELF, Mach-O magic; filesize < / <=), exclusion per (MZ / non-MZ) x
  size bucket (<1, 1-4, 4-16, >=16 MiB). Global rules and rules referenced by
  kept rules always stay.
- YaraScanner builds subsets in a background thread after each load, in
  priority order (big non-PE first) under rule_partition_budget_pct (default
  100 ~ one extra full set: 3 subsets, +59 MiB; all 16 class x size subsets
  would cost +428 MiB). Cached under rules_cache_dir/partitions/. File, buffer
  and fd scans pick their subset; process-memory scans use the full set.
- Fails closed to the full rules: include directives, a split count that
  differs from libyara's, or a subset compile / count error.
- Status rules.partitions (state, reason, subsets, kept_rules/scans per
  partition, full_scans); config rule_partitions (default true) and
  rule_partition_budget_pct.

Measured on the 5132-rule pack: big ASan ELFs 1.64x, 1200 system binaries
1.59x, 0 match-set differences, including 348 positive files across
MZ/ELF/raw x small/5 MiB. Tests: splitter traps, facts, exclusion soundness
property, real pack = 5132 rules; differential test (24 file shapes x memory /
ranges / fd scans, every subset built) and fail-closed; bench --partitions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 06:58:39 -07:00

40 KiB
Raw Permalink Blame History

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.
{"ok":true,"verb":"<verb>","data":<object>}
{"ok":false,"error":"<message>"}

Errors include permission denied, unknown command, request too long, request timed out, empty request and rescan rate limited; retry in Ns.

status

{
  "version": "0.1.0",
  "pid": 1234,
  "now_ns": 1792887028777076502,
  "started_at_ns": 1792887022744355381,
  "running": true,
  "config_path": "/etc/strawberry/strawberry.conf",
  "db_path": "/var/lib/strawberry/database.db",
  "monitor": {
    "enabled": true,
    "backend": "bpf",
    "execveat": true,
    "fork_tracepoint": false,
    "events": 72,
    "events_dropped": 0,
    "queue_depth": 0
  },
  "rules": {
    "path": "/etc/strawberry/rules",
    "required": true,
    "loaded": true,
    "files": 2,
    "count": 5142,
    "generation": 2,
    "loaded_at_ns": 1792887025771774835,
    "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.
  • 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), 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 = memory budget / 4, 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): 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. 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

{"reloaded": true, "error": ""}

Recompiles every .yar/.yara file under rules.path. On failure, reloaded is false, error holds the first compiler message, and the previous rule set keeps running.

rescan

{"queued": true}

Asks the monitor to re-emit every running process. The rescan runs on the monitor thread, so this returns immediately. It is rate-limited to once per 30 s. A process image already scanned under the current rules generation is not recorded twice, so rescan after reload-rules to apply new rules to running processes.

scan-fd

The client opens a file with its own permissions and sends the verb line plus exactly one open descriptor in the same sendmsg (SCM_RIGHTS). The daemon never receives or resolves a path, so it can't be used to read files the caller couldn't open.

{
  "scanned": true,
  "error": "",
  "size": 47445,
  "sha256": "<hex>",
  "matches": [
    {"rule": "Strawberry_Test_Marker", "severity": "low", "namespace": "default", "tags": [], "meta": "description=...; severity=low"}
  ]
}
  • Regular files only, at most scan_max_bytes (default 64 MiB).
  • The file is read into a private buffer before scanning. The hash and scan see the same bytes, and a caller truncating the file can't fault the daemon.
  • Rate-limited to 300 scans/min. Results are not stored as evidence. Each scan is logged with the caller's uid/pid.
  • scan-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:

{
  "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

{"requested": true}

Touches <feeds_dir>/update-requested. The strawberry-update.path unit then starts the updater. Rate-limited to once per 5 minutes.

Audit

Every request except status is logged as [ControlServer] uid=<uid> pid=<pid> verb=<verb> result=ok|error. Denied peers are logged too.

CLI equivalents

strawberry --status [--json] [config_path]
strawberry --reload-rules [config_path]
strawberry --rescan [config_path]
strawberry --scan-file <path> [config_path]   # opened as you, sent via scan-fd
strawberry --policy [config_path]
strawberry --policy-set <verb> '<json>' [config_path]   # any payload verb, e.g. quarantine '{"sha256":"…"}'
strawberry --opensnitch-enable-checksums                 # root: set Rules.EnableChecksums in OpenSnitch (keeps a .bak)
strawberry --request-rule-update [config_path]

Local, no socket:

strawberry --update-rules [config_path]   # run the updater (what strawberry-update.service does)
strawberry --check-rules [config_path]    # compile local + installed feed rules, print the count

Rule feeds and the updater

strawberry-update.service runs strawberry --update-rules:

  • daily, via strawberry-update.timer
  • on request, via strawberry-update.path

It runs sandboxed: no capabilities, writes only /var/lib/strawberry/feeds, network limited to IPv4/IPv6/Unix. For each enabled feed it:

  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). 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)

strawberry --list-findings --json [config_path]
strawberry --show-finding <finding_id> --json [config_path]
strawberry --search-process <query> --json [config_path]
strawberry --trace-process <pid> [--trace-depth n] [config_path]
strawberry --trace-node <node_id> [--trace-depth n] [config_path]

These open the database read-only and never write back, so they are safe to run while the daemon is active.

GraphNode

{
  "id": "process_654_a902af2e_9798407",
  "type": "process",
  "properties": {
    "pid": "654",
    "path": "/tmp/payload",
    "hash": "<sha256>",
    "cmdline": "payload --flag",
    "parent_pid": "1",
    "parent_node_id": "process_1_a902af2e_12",
    "start_time_ticks": "9798407",
    "boot_id": "<hex>",
    "exe_deleted": "true",
    "exe_memfd": "true",
    "event_timestamp_ns": "1792887024282406813"
  }
}

Node types:

  • 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

{
  "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

{
  "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)

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_and_overlap_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.

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.