strawberry/AGENTS.md
trvon 09e6b441ae
Some checks failed
Build and Test / build (debug, clang) (push) Has been cancelled
Build and Test / build (debug, gcc) (push) Has been cancelled
Build and Test / build (release, clang) (push) Has been cancelled
Build and Test / build (release, gcc) (push) Has been cancelled
Build and Test / macos (push) Has been cancelled
Build and Test / docker (push) Has been cancelled
Audit flow: add the clang static analyzer as a strict per-change gate
- scripts/analyze_changed.sh + `make analyze`: clang-check --analyze over the
  changed TUs via builddir/compile_commands.json (host build may be gcc; clang
  tolerates those flags), nice -n 19, 2 at a time. Strict by default (any
  analyzer diagnostic fails), ANALYZE_STRICT=0 reports only; ANALYZE_FILES/--all
  override selection. Results in build/audit/out/analyze.log.
- AGENTS.md "Per-change checks": new analyzer row, positioned as path-sensitive
  intra-TU analysis that complements fold's bounded symbolic cross-call pass and
  the syntactic invariants (run all three); YAMS index-at-checkpoint reminder.
- CLAUDE.md: analyzer added to the checks pointer + a Performance & C++ bullet
  (perf-kpi + Tracy/PerfStats).
- docs/prompts/PROMPT-strawberry-audit.md: "Clang static analyzer" subsection
  under Symbolic SAST.

No C++ changed; unit suite 50/50 green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-10-28 09:55:03 -06:00

316 lines
29 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.

# AGENTS.md
## Documentation Map
- [RESEARCH.md](RESEARCH.md) — literature-backed rationale for Strawberry's architecture and scope
- [PLAN.md](PLAN.md) — execution order, status, and next milestones
- [README.md](README.md) — public project overview and build/run instructions
- [DEVELOPER.md](DEVELOPER.md) — implementation notes and code structure
- [OFFLINE_INSTALL.md](OFFLINE_INSTALL.md) — hybrid Conan/submodule air-gapped install workflow
- [UX.md](UX.md) — analyst workflow notes and the desktop app (Qt6 + tray) direction
- [API_CONTRACT.md](API_CONTRACT.md) — control-socket protocol, access model, and CLI/evidence JSON shapes
- [docs/prompts/PROMPT-eng-codex.md](docs/prompts/PROMPT-eng-codex.md) — generic YAMS-first operating loop: retrieval contract, metadata, handoff, ask-first list
- [docs/prompts/PROMPT-strawberry-audit.md](docs/prompts/PROMPT-strawberry-audit.md) — audit flow with brick (structure), fold (symbolic SAST) and pipe (state flow)
## Operating Model
Follow `docs/prompts/PROMPT-eng-codex.md` (shared with `../yams`, `../brick`):
YAMS-first retrieval (`yams grep` / `search` / `graph --explore`, then hydrate
with `yams cat --hash`), a start claim, checkpoints and a completion handoff.
Use task slugs like `strawberry-<topic>` and agent id `opencode-<task>`.
Development memory: store audits, triage notes, decisions and handoffs in YAMS
(`source=note|decision|evidence`, plus `task`, `phase`, `owner=opencode`), not
as new local Markdown. Product docs (README, API_CONTRACT, PLAN, DEVELOPER)
stay in the repo and must keep matching the code. Re-index changed files at
checkpoints:
```bash
yams add . --recursive --include "*.cpp,*.hpp,*.h,*.c,*.md,*.build,*.yar,*.service,*.timer,*.path,*.sh,*.conf" \
--exclude "builddir/*,third_party/*,build/*,.ccache/*" \
--metadata "mode=engineering,task=<task>,phase=checkpoint,owner=opencode,source=code"
```
Audits use the flow in `docs/prompts/PROMPT-strawberry-audit.md`: brick for
structure, fold for bounded symbolic findings, pipe for `enum class` state
flow. Every finding is verified in source before it is fixed or reported, a
fix lands with a test, and the triage is stored in YAMS (`source=evidence`).
## Background Work & Resource Governor
Strawberry runs on desktops: a scanner that freezes the machine gets
uninstalled. `ResourceGovernor` (`include/strawberry/resource_governor.hpp`,
ported from `../yams`) samples the daemon's CPU/RSS, host PSI (loadavg
fallback), `MemAvailable` and cgroup v2 limits, and the scan profile
(`scan_profile = efficient | balanced | aggressive`) bounds every heavy path.
- Code that starts a thread, loop or job asks the governor first:
`admit(WorkClass::…)` / `wait_admitted(…)`. Background classes (inventory,
memory scans, correlation, rule reloads, blocklist sync) wait while the host
is busy; the starvation guard (`background_max_deferral_s`) still runs them.
- The launch path is never deferred: the exec guard may only *degrade* to
hash/IOC/quarantine (`guard_should_degrade`) and must answer before
`prevention_timeout_ms`; its YARA timeout is capped at that deadline.
- Background reads draw from `pace_read` and drop page cache afterwards;
background threads run at the profile's nice/ioprio
(`src/thread_priority.hpp`). Scans happen outside `DetectionPipeline::mutex_`.
- No free-running loops, no unbounded queues, no clear-all caches on hot
paths, no full-file hashing on the eBPF event thread.
- A new or changed background path needs a constrained-lane KPI before and
after (`make perf-kpi`, `scripts/perf_kpi_report.py --compare`), 3 repeats
for any claim. Code reading is not evidence.
- Timings: record into `PerfStats` (`include/strawberry/perf_stats.hpp`) and
add Tracy zones (`STRAWBERRY_ZONE`, `-Denable_profiling=true`) for any new
heavy step; surface them in status `timings`.
## Invariants and Fuzzing
**Per-change checks.** Every change that touches I/O, callbacks, threads,
parsers or persistence runs, before it is called done:
| Check | Command | Catches |
|---|---|---|
| Unit + property + source invariants | `nice -n 19 meson test -C builddir --num-processes 2` | logic, `tests/test_invariants.cpp`, `tests/source_invariants.py` (iostream/`std::sto*`/unguarded threads/non-`noexcept` C callbacks/empty `catch`) |
| Fault injection | `test_fault_injection` (part of meson test; sweep seeds with `STRAWBERRY_PROPERTY_SEED`) | exceptions, hangs or wrong results when reads/opens fail (ESRCH, EIO, EINTR storms, short reads) |
| Fuzzing | `make fuzz` (clang, capped, niced; `fuzz_io_faults` + parser targets) | crashes, escapes and timeouts on hostile input and I/O |
| fold | `scripts/fold_changed.sh [base]` (fold's LLVM-19 image, `--cpus=2 --memory=6g`, cached) | bounded symbolic findings in changed TUs, including `exception-escape` (exceptions reaching noexcept functions, destructors, C callbacks, thread entries) |
| clang-tidy | `nice -n 19 clang-tidy -p builddir <changed files>` (`.clang-tidy`; enforced checks are errors) | `bugprone-empty-catch` today; more checks are added as the tree is cleaned |
| clang static analyzer (strict) | `make analyze` (`scripts/analyze_changed.sh [base]`; clang-check `--analyze` on changed TUs via `builddir/compile_commands.json`, `nice -n 19`, 2 at a time; any diagnostic fails the run, `ANALYZE_STRICT=0` reports only) | null deref, use-after-free, leaks, uninitialized reads and path-sensitive logic bugs the type system and clang-tidy miss |
| brick / pipe | see `docs/prompts/PROMPT-strawberry-audit.md` | structure, `enum class` state flow |
| Live + KPI | `make docker-live-tests`, `make perf-kpi` (3× `--compare`) | root-only paths, resource regressions |
Verify every tool finding in source before fixing or reporting it, and store
the triage in YAMS (`source=evidence`). Fold's `exception-escape` detector,
`source_invariants.py` R4/R5 and the fault-injection properties together cover
exceptions escaping into C frames, destructors and threads. Fold sees one TU at
a time and the invariants are syntactic, so keep all three. The clang static
analyzer is path-sensitive within a TU (null deref, use-after-free, leaks,
uninitialized reads); it complements fold's bounded symbolic cross-call analysis
and the syntactic invariants rather than replacing either — run all of them, and
index the change in YAMS at each checkpoint before and after.
- Decision logic and parsers carry property tests in `tests/test_invariants.cpp`
(seeded; failures print the seed). A new rule that must always hold gets a
property, not just an example.
- Every parser of untrusted or attacker-influenced input has a libFuzzer
target in `fuzz/` (`make fuzz`, clang, capped and niced). New parsers get a
target and seeds in `fuzz/seeds/<target>`.
- Every file or syscall I/O on a runtime path goes through `include/strawberry/sys_io.hpp`
(`io::read`, `io::pread`, …) so the fault-injection property tests and
`fuzz_io_faults` can fail it. Read loops bound EINTR retries (`io::kMaxEintrRetries`);
a short file at EOF is an error, never a silent prefix.
- **No empty `catch` blocks** (R7, clang-tidy `bugprone-empty-catch`). A
comment is not handling. Handle the exception (log, count, return an error),
or, where nothing more is possible (destructors, `noexcept` C callbacks,
error-reporting fallbacks), record it with `STRAWBERRY_NOTE_SWALLOWED()`
from `include/strawberry/swallowed.hpp`: it counts the exception (status
`resources.swallowed_exceptions`) and logs file:line without allocating or
throwing.
- New static rules go in `tests/source_invariants.py` with a `bad_*.cpp`
fixture in `tests/fixtures/invariants/` (the self-test proves the rule fires).
## Purpose
Strawberry is an early-stage Linux host security scanner prototype in C++23. The intended design remains:
- eBPF/libbpf for process/runtime telemetry
- YARA for file/process scanning
- an embedded local store for indicators + relationship graphs
- a minimal rule-based correlation layer over persisted runtime evidence
- a small daemon/state-machine shell around those components
## Current Project Reality
Treat this repository as a **prototype with a working build/test spine**, not a finished scanner.
As of **April 27, 2026**, the most important facts are:
1. **Build and test baseline is green**
- `meson_options.txt` replaced the broken `meson.options` flow.
- `meson setup builddir -Denable_tests=true`, `meson compile -C builddir`, and `meson test -C builddir --verbose` are expected to work.
- A thin `Makefile` wrapper is available for `make setup`, `make build`, `make test`, and `make run`.
2. **The embedded database path is real in this checkout**
- `Database` is backed by the event store (`src/store/`: zstd segments, sealed footers, crash-atomic MANIFEST, LogStore recovery).
- Strawberry persists `IndicatorEntry`, `GraphNode`, `GraphEdge` and findings across reopen; a differential test checks every query against the old store's semantics.
- A legacy unqlite-format `database.db` is imported on the first writer open (verified, old file kept as `.migrated-<ts>`).
- The unqlite-cpp submodule is gone; `src/store/legacy_kv.*` reads the old format for the importer.
3. **The detection pipeline is still incomplete**
- `ProcessMonitor` now has a minimal procfs-polling runtime path plus a Linux libbpf exec-event path, and a privileged Docker smoke run on **April 26, 2026** validated live tracepoint attach plus one observed `/bin/echo` exec event.
- A reusable `DetectionPipeline` now owns the scan/store path, and a Docker-validated synthetic runtime test on **April 26, 2026** proved procfs event ingestion can trigger YARA matching and persisted process→indicator graph storage.
- A second privileged Docker smoke run on **April 26, 2026** proved one real libbpf-delivered exec event can also flow through `DetectionPipeline` into persisted indicator + graph storage.
- A reusable `StrawberryDaemon` wrapper now owns config loading, TinyFSM transitions, process-monitor startup, and pipeline ownership for the production binary.
- A daemon-level synthetic test on **April 26, 2026** now proves procfs event ingestion can also flow through `StrawberryDaemon` into persisted indicator + graph storage.
- A third privileged Docker smoke run on **April 26, 2026** now proves one real libbpf-delivered exec event can also flow through `StrawberryDaemon` itself into persisted indicator + graph storage.
- A new `IncidentReporter` now renders concise human-readable summaries over persisted graph state, including first/last seen timing and relative span formatting, and the main binary can print them with `--trace-process` or `--trace-node`.
- A synthetic demo-trace seed path exists (`--seed-demo-trace`, `config/strawberry.demo.conf`, `make demo`) for evaluating the app/reporting flow without a running daemon.
- The prototype direction is **system improvements first**: collect a fuller Linux process corpus and refine correlation before expanding UI.
- The operator UI is the Qt6 desktop app + tray indicator `strawberry-tray` (`app/`, meson option `enable_app`). The temporary Python web evaluator (`scripts/strawberry_ui_server.py`, `ui/`, `WEB_DEPLOYMENT.md`) was removed on October 24, 2026; do not reintroduce an HTTP server for local use.
- `strawberry-mcp` (`mcp/`, meson option `enable_mcp`, needs nlohmann_json) is the agent interface: MCP over stdio with evidence tools, `strawberry_scan_paths`, reload and rescan (`--read-only` hides the last three). On-demand scans use the `scan-fd` verb: the client opens the file as the user and passes only the descriptor (`SCM_RIGHTS`); the daemon reads it into memory (≤ `scan_max_bytes`), never stores results, and audit-logs uid/pid.
- YARA rules auto-update: `PolicyStore` (`policy.json` next to the DB) holds rule feeds (default: YARA Forge core GitHub release) and the allowlist (sha256 / path / rule); `strawberry-update.timer` + `.path` run the sandboxed updater daily or on `update-rules`; the daemon loads local rules plus each enabled `feeds/<id>/current` in its own YARA namespace. Allowlisted detections are suppressed before storage and counted. The app has Rules and Allowlist tabs; changes go through payload verbs on the control socket (group `strawberry`, rate-limited, audited).
- Process images are scanned from a bounded in-memory copy (`process_scan_max_bytes`), never mmap, and exec events go through a bounded worker queue (`events_dropped` counts overflow and eBPF ring-buffer drops).
- The app runs as the desktop user, reads the DB via `Database::open_read_only()`, and controls the daemon only through `ControlServer` (`/run/strawberry/control.sock`, group `strawberry`, peer-credential checked, rate-limited, audit-logged). Verbs: plain `status` / `policy` / `reload-rules` / `rescan` / `update-rules`, fd-passing `scan-fd`, and one-line JSON payload verbs for allowlist/feeds/protection/containment/quarantine/memory scan/process actions (see API_CONTRACT.md). `strawberry status`, `strawberry policy set ...`, `strawberry doctor` and the rest of the CLI (command form, yams-style: `src/cli_commands.cpp`; the older `--flag` form still works) use the same socket. CLI changes follow [docs/cli-ux.md](docs/cli-ux.md): `noun verb` commands as rows in the one command table (help and shell completions are generated from it; a test in `tests/test_cli.cpp`), never a new top-level `--flag`; results on stdout, everything else on stderr; `--json` on every data command, one document, additive-only keys (shape changes in API_CONTRACT.md); human output never prints raw JSON, and evidence strings pass through the terminal-safe filter (`src/term_safe.hpp`); process actions take node ids only; state-changing maintenance takes `--dry-run`.
- October 25, 2026 protection pass (M1–M5): IOC list feeds, OpenSnitch blocklists + automatic containment, fanotify exec prevention (`audit` default), eBPF/fanotify behavior telemetry, process-memory YARA scans (`yr_rules_scan_proc`) and response actions. The service now also needs `CAP_SYS_ADMIN` and `CAP_KILL` (`systemd-analyze security` ≈ 3.2). Root-only tests run via `make docker-live-tests`.
- October 25, 2026 macOS port: builds and passes `meson test` on macOS (Homebrew deps, CI job `macos` on GitHub). Endpoint Security backends for exec events, `AUTH_EXEC` prevention and file watching, libproc polling fallback, Mach resource sampler, launchd packaging (`packaging/macos/`, `scripts/macos_install.sh`). The ES backends compile and fall back correctly but have not run live: that needs root + the ES entitlement (SIP-disabled VM for ad hoc signing); use `make macos-live-tests`. Platform map: DEVELOPER.md "Platforms". Linux code paths are unchanged; Linux changes must still pass `make docker-live-tests`.
- October 27, 2026 macOS install: `scripts/install.sh` hands off to `scripts/macos_install.sh`. An ad hoc signature carrying the ES entitlement is SIGKILLed at launch while SIP is on, so the installer signs with `packaging/macos/strawberry-base.entitlements` there (libproc fallback). Both entitlements files disable library validation: the hardened runtime otherwise rejects Homebrew dylibs (different Team ID). The rule updater runs as `_strawberry`, which owns only `feeds/`. Platform strings for hints (systemctl vs launchctl) live in `include/strawberry/service_hints.hpp`; the system store path is `kSystemStorePath` in `config.hpp`.
- A first minimal `CorrelationEngine` now stores explainable findings for process-executable YARA matches grouped by process/hash.
- A second rule now stores lineage findings when one parent has multiple matched descendants.
- A third rule now stores findings when the same matched executable hash appears across multiple processes.
- A fourth rule now stores findings when the same YARA rule appears across multiple processes.
- Finding list/show commands support `--json` for UI and automation clients.
- A `ProcessQuery` surface supports process search by PID, path, hash, YARA rule, and finding evidence, with JSON output; the desktop app's Processes tab uses it directly.
- Process search results include first/last seen evidence timestamps and immediate parent/child lineage summaries.
- The correlation engine is intentionally narrow: it is not yet a general subgraph matcher, anomaly scorer, or full incident engine.
- The current model is still **process-centric**. There is no first-class thread/TID telemetry, so “find threads” should be treated as a planned future UX capability, not a current feature.
- The procfs backend can now emit an initial startup inventory of already-running processes when `scan_existing_processes_on_start=true` is passed through daemon config / monitor options. This is the current preferred path for building a host-wide process corpus for correlation refinement.
- Procfs-driven events now also persist `parent_pid` and `event_timestamp_ns`, and create a minimal `spawned` lineage edge when parent information is available.
- Matched runtime events now also persist an executable-image file node and provenance edges: process → file (`executed`) and file → indicator (`content_matched`).
- `YaraScanner` now has optional libyara-backed rule compilation and file scanning.
- `scan_process` currently performs a best-effort `/proc/<pid>/exe` scan, not full process-memory scanning.
- YARA hit metadata now persists through `Database`, and the daemon path links process nodes to indicator nodes with `matched` edges.
- A Conan-backed libyara build and unit-test pass succeeded on **April 25, 2026** on the current macOS host, so real rule compilation and file-scan assertions are now locally validated.
- Linux-specific `/proc/<pid>/exe` behavior is now covered by a Docker-validated Linux unit test on **April 26, 2026**.
- Procfs-based process-event ingestion is covered by a synthetic procfs unit test on **April 26, 2026**.
- The Linux Docker build now also validates that the minimal libbpf exec-event object compiles on **April 26, 2026**.
- The live libbpf smoke harnesses currently match the observed exec by executable path; callback PIDs may differ from the child PID seen inside a privileged container because of namespace/kernel PID differences.
- The libbpf path now includes a best-effort fixed-width argv preview (`argv0`/`argv1`) for cases where `/proc/<pid>/cmdline` cannot be read.
- A privileged `/bin/echo` smoke on **April 26, 2026** validated that live argv preview can surface `echo strawberry_process_monitor_live_smoke`, and the staged live-pipeline smoke also surfaced `live_echo strawberry_live_bpf_pipeline_smoke`.
- The libbpf path now opportunistically attempts `sched_process_fork` for parent-PID enrichment, but that extra tracepoint is not guaranteed to attach in every privileged container/runtime.
- In the privileged container smoke path, `parent_pid` may still be unavailable for live libbpf events because `/proc/<host-pid>` enrichment can fail across PID namespaces.
- The daemon is still best understood as a shell around partially implemented subsystems.
- October 24, 2026 host-readiness pass: the BPF object builds on Arch (UAPI types), `execveat` is hooked, events resolve and scan through `/proc/<pid>/exe` (deleted/memfd flagged as heuristic indicators), process node IDs are `process_<pid>_<boot8>_<starttime>` (legacy `process_<pid>` when start time is unknown; use `make_process_node_id()` / indicator `process_node_id` metadata rather than building IDs by hand), the daemon fails closed without rules or a writable DB, the DB has a single-writer `flock` plus read-only query opens and transactions, correlation is batched, rule severity comes from `meta.severity`.
4. **Runtime target is Linux**
- Static review and most unit tests can run anywhere.
- Real validation for eBPF, `/proc`, systemd, and process-memory scanning should be treated as Linux-only work.
## Storage Guidance
- keep the `Database` public interface narrow and stable; storage specifics live in `src/store/`
- every decoder takes untrusted bytes and never throws; new record fields are tagged (old readers skip them), record type ids are append-only
- all store I/O goes through `strawberry::io` (fault injection); store changes need the S/M/L properties, the differential test and the store fuzzers green
- evidence is group-readable (0640), telemetry root-only (0600)
## Build System Guidance
Meson/Ninja remains the source of truth.
- Prefer fixing Meson rather than replacing it.
- The repository now also exposes a **thin GNU Make wrapper** for convenience.
- A root `conanfile.py` supports a hybrid offline dependency flow for OpenSSL, zstd and optional extras; nothing is vendored.
- The root Conan recipe forces a C++23 Meson native-file setting so `conan profile detect` defaults do not break the build.
- The repo now also seeds a local `yara/4.5.5` Conan recipe under `conan/local_recipes_index/` for air-gapped or pinned builds.
- The root `Dockerfile` is now the Linux build/test container definition and should stay aligned with the real dependency set.
- The Docker image defaults to `gcc`/`g++` for C++23 inside the Ubuntu 24.04 container.
- `make app` runs the desktop app from the build tree; `make demo` seeds demo evidence and opens it in the app. Qt6 (Core, Gui, Widgets, DBus, Network) is optional; `-Denable_app=disabled` skips the app.
- If someone asks for `make` support, keep it as a wrapper around Meson/Ninja unless explicitly told otherwise.
- If “Make” refers to **Make.com**, treat that as a separate integration effort and do not assume it means GNU Make.
## Recommended Work Order
The next meaningful work should happen in roughly this order:
1. Keep build/test green while landing follow-on changes.
2. Keep the daemon-level synthetic and privileged Linux smoke paths aligned with the real binary startup path.
3. Validate and harden startup process inventory plus ongoing process-event collection on Linux.
4. Improve runtime enrichment that feeds correlation: executable identity, command line, timestamps, parent/child lineage, and short-lived process handling.
5. Extend the minimal rule/heuristic **correlation engine** only when the evidence model supports the rule cleanly.
6. Add process-first and findings-first query surfaces on top of that correlation layer.
7. Keep the desktop app focused (findings, processes, diagnostics, reload/rescan); grow it only as evidence quality justifies.
8. Keep control-socket and JSON contract changes limited and documented in API_CONTRACT.md.
9. Agent-facing access (CLI/MCP) should reuse the same read-only evidence and fixed control verbs.
10. Defer thread-level UX until Strawberry actually captures thread/TID telemetry.
11. Expand packaging, service hardening, and external automation surfaces only after the above are stable.
## Testing Priorities
Prioritize tests in this order:
1. **Build configuration tests**
- clean configure
- clean compile
- test toggle works
2. **Pure unit tests**
- hash utilities
- config parsing/serialization
- database persistence semantics
- graph traversal behavior
3. **Integration tests**
- YARA rule load from a temp directory
- file-scan match persistence
- multi-hit indicator persistence for the same hash
- synthetic process-event ingestion pipeline
- synthetic procfs event → `DetectionPipeline` → persisted indicator/graph flow
4. **Linux runtime smoke tests**
- daemon starts with test config
- telemetry path initializes cleanly
- privileged libbpf smoke harness observes a live exec event
- test YARA hit is stored and queryable
- live daemon-owned telemetry path stores a test hit through the real daemon wrapper
5. **Correlation and operator tests**
- multiple related raw events collapse into one explainable finding when intended
- process-first query surfaces return lineage plus related indicators/files
- findings-first query surfaces can pivot back to underlying evidence
## Repo Conventions
- Public headers live in `include/strawberry/`
- Implementations live in `src/`
- Keep public interfaces small and dependency-light
- Prefer RAII and `std::unique_ptr`
- Keep platform-specific code isolated behind implementation details
- Preserve XDG-style default data placement for local storage
## Agent Guardrails
When working in this repo:
- do not describe the current YARA path as fully complete: file/executable and process-memory scans exist, but memory scans run only on triggers (memfd/deleted/ptrace target/operator request), not continuously, and need real-host tuning
- do not describe the current runtime pipeline as fully complete: synthetic procfs-driven scan/store coverage and one live libbpf-to-store smoke pass now exist, but richer live-event enrichment and daemon-grade runtime handling are still the next major steps
- do not describe the daemon runtime as fully complete: the reusable wrapper, daemon-owned smokes, and basic text reporting now exist, but richer live parent-PID enrichment and more advanced reporting/export are still the next major steps
- do not describe the desktop app as a full operations console: it is a findings/process/diagnostics viewer with rules/allowlist/response management and a small set of confirmed actions
- never add a control verb that makes the root daemon open a caller-supplied path or run a command: on-demand file access must stay fd-passing (`scan-fd`). Policy payload verbs (`allowlist-*`, `feed-*`) may *store* path/URL strings after `PolicyStore` validation, but the daemon never opens them, and feed URLs are fetched only by the sandboxed `strawberry-update.service` (`strawberry rules fetch`); the daemon itself keeps `PrivateNetwork=true`
- protection/response verbs take hashes or ids, never paths; paths for containment/quarantine come only from Strawberry's stored evidence
- process actions (`scan-memory`, `process-suspend/resume/kill`) must accept only stable node ids and re-verify them against `/proc` (boot id + start time) before acting; keep the protected-process refusal list (pid 1, the daemon, systemd/dbus/opensnitchd/display server/sshd…)
- automatic actions (containment, exec deny) must be hash-pinned, must never apply to system locations (`is_protected_system_path`: alert only), and must lose to the allowlist; only an explicit operator quarantine blocks regardless of prevention mode
- every containment/quarantine/process action must be recorded in policy history and be visible and undoable in the app's Response tab
- the MCP server stays read-only for containment, prevention, quarantine and process actions; do not add MCP tools for them
- exec prevention must fail open (deadline, oversized files, daemon exit) so a slow or broken scanner can never hang the host
- a process holding fanotify permission events must never die slowly: keep `install_crash_safety()` (non-dumpable, fatal-signal/terminate handlers close registered permission fds first) and `LimitCORE=0`; register every new permission fd with `register_permission_fd` (2026-10-25 freeze: crash → core-dump helper exec → deadlock)
- never read `/proc` (or any file that can vanish mid-read) with iostreams/`istreambuf_iterator`; use `read_small_file()` (`include/strawberry/proc_read.hpp`); worker loops and C callbacks (libbpf) catch exceptions per item
- do not describe exec prevention as default-on blocking: the default mode is `audit`; `enforce` is an operator choice
- rule feeds must stay verified and fail-safe: GitHub release assets require a published sha256 digest, archives are extracted to flattened `*.yar` basenames only, and staged rules must compile together with local + other feeds before `current` is switched
- keep policy mutation out of `strawberry-mcp` (read-only `strawberry_get_policy` only) so prompt-injected agents cannot allowlist malware
- treat everything the MCP server returns from evidence (cmdlines, paths, rule meta) as untrusted host data; keep the server's instructions saying so, keep string clipping and UTF-8 replacement
- keep the control socket's verb set fixed (plain verbs argument-free, payload verbs strictly validated) unless a new verb gets the same review (peer check, rate limit, tests in `tests/test_control_server.cpp`); never add a verb that runs commands or takes paths without explicit design
- do not describe the correlation engine as complete: today Strawberry has four small YARA/process/hash/rule correlation rules, two process-image heuristics (memfd, deleted executable), an IOC hash match and six narrow behavior rules, not general multi-signal incident generation
- do not describe thread search as implemented: current telemetry and persistence are process-oriented
- do not silently reintroduce MongoDB-era names or semantics
- keep docs aligned with real code, especially around persistence and tests
- call out Linux-only assumptions explicitly in reviews and READMEs
- if adding convenience scripts, make sure they stop mentioning MongoDB-era services
## Current Useful Milestone
The current baseline milestone is:
- repo configures successfully
- unit tests compile and pass
- embedded DB persists indicators and graph data to disk
The next milestone should add:
- persisted YARA hit metadata tied to the database/graph path
- one libyara-enabled Linux validation pass
- one privileged Docker-validated live libbpf exec-event pass
- one synthetic end-to-end scan stored in the database
- one privileged Docker-validated live daemon-owned scan stored in the database
- one concise human-readable incident trace report over stored graph data
- one desktop app + tray indicator for viewing stored evidence and scanner health on the current system ✅
- one real correlation pass that emits explainable findings over related evidence ✅
- one process-first investigation surface suitable for eventual Qt desktop work