--- description: Strawberry audit flow — brick (structure), fold (bounded symbolic SAST), pipe (enum-class state flow), with YAMS-recorded triage. argument-hint: "[TASK=strawberry-audit-] [PHASE=]" --- # Strawberry Audit Flow Operating loop, retrieval contract and handoff: `PROMPT-eng-codex.md`. Repository rules and guardrails: `AGENTS.md`. This file covers only how to audit Strawberry with the sibling tools in `../brick`, `../fold` and `../pipe`. ## Rules - Tool output is a candidate, never a verdict. Read the source on both sides of every finding before fixing or reporting it. - Keep each tool's evidence label: brick edges are syntactic/heuristic; fold `proved` means proved inside fold's bounded model; pipe C++ results are experimental. Do not upgrade a label in a report. - Report coverage with results (files analysed, call sites resolved, TUs failed). Incomplete coverage is never a clean result. - A fix lands with a test that fails without it (or a stated reason why it cannot), then `meson test -C builddir` and, for root-only paths, `make docker-live-tests`. - Store the triage in YAMS: one `source=evidence` note per audit run with tool versions, coverage, each finding's verdict (fixed / false positive / accepted risk) and the commit or files touched. Write artifacts (JSON, SARIF, HTML) to the scratchpad or `build/audit/`, not the source tree. ## 1. Structure — brick ```bash brick build . --exclude builddir --exclude third_party --exclude build \ --exclude .ccache --exclude conan \ --json build/audit/strawberry.brick.json --html build/audit/strawberry.brick.html python3 ../brick/skills/brick-sast/scripts/architecture_summary.py build/audit/strawberry.brick.json ``` Look at: dependency cycles, top fan-out (orchestrators such as `process_feed`, `handle_process`, `tool_scan_paths`), top fan-in, and C++ call-site resolution. Expect Qt `signals:`/`slots:` grammar warnings in `app/`. With ~25% of C++ call sites resolved, do not use brick to claim a function is unused; confirm with `yams grep`. Baseline (2026-10-25): 92 files, 868 functions, 0 cycles, structural score 76.5 (experimental), 2550/9798 C++ call sites resolved. ## 2. Symbolic SAST — fold Fold needs LLVM 18–19 and z3. The host's LLVM 23 does not build it (fold uses `ASTContext::getRawCommentForDeclNoCache`, removed in LLVM 23), so run it in fold's validation image, configuring Strawberry inside the container so the compile database matches the container's headers: **Changed files only (per change):** `scripts/fold_changed.sh [base]` scans just the translation units changed since `base` (default: uncommitted), using the cached fold build in `build/audit/cache`. `--all` scans everything. `FOLD_DETECTORS=...` overrides the detector list. **Resource limits.** This is a workstation: never run unbounded builds. Cap the container (`--cpus=2 --memory=6g`), run it under `nice -n 19`, use 2 build jobs and `--processes 2` for fold, and keep the fold build in a persistent cache directory so an interrupted run resumes instead of starting over. An uncapped fold build (LLVM + z3 TUs at full parallelism) has exhausted this machine before. ```bash docker build -t fold-linux-validate -f ../fold/docker/Dockerfile.linux-validate ../fold A=$PWD/build/audit; mkdir -p $A/cache $A/out nice -n 19 docker run --rm -u 0 --cpus=2 --memory=6g --memory-swap=6g --entrypoint bash \ -v ../fold:/fold:ro -v $PWD:/strawberry:ro -v $A/cache:/cache -v $A/out:/out \ -v $A/fold_scan_in_docker.sh:/run.sh:ro fold-linux-validate /run.sh ``` The script (kept in `build/audit/`, recreate from this description if lost) installs Strawberry's `-dev` packages, builds fold once into `/cache` (conan + meson, `-Dghidra=disabled -Dcapstone=disabled`, `-j 2`), runs only `meson setup` for Strawberry (fold needs the compile database, not a build), then: ```bash fold scan --mode source --compile-db /cache/sb/compile_commands.json \ --exclude-glob '*/third_party/*' --exclude-glob '*/tests/*' \ --detectors null-deref,div-by-zero,int-overflow,oob,int-truncation,taint-track,uninit-read,use-after-move,iterator-invalidation,exception-escape \ --processes 2 --budget-seconds 300 --per-query-ms 2000 --format json --output /out/fold.json ``` Fold source fixes needed on Linux (z3 `bv_val` overloads are ambiguous for `long long`/`unsigned long long` literals): cast to `int64_t`/`uint64_t` in `src/symbolic/pcode_encoder.cpp` and `src/cli/scan_runner.cpp`. `setup.sh` also writes `build//llvm_ar.ini` before creating the directory and passes its build-type argument to ninja as a target. `--detectors` takes one comma-separated list; space-separated names are read as source files and silently skipped. Check the log for "running N worker process(es) over M files" with M equal to the TU count, and non-zero query counts, before trusting "0 findings". Triage order: `concrete-witness`, then `proved`, then high-impact `heuristic`. Priority areas: the control socket (`src/control_server.cpp`, payload parsing, `SCM_RIGHTS`), procfs/BPF event parsing (`src/process_monitor.cpp`), bounded reads (`detail::read_fd_bounded`), the exec guard (fanotify event handling), the updater (archive extraction, list parsing) and `PolicyStore` validation. Overlay the report on the structure graph with `brick build ... --fold-report fold.json` when correlating hotspots. Baseline (2026-10-25, fold built from ../fold in fold-linux-validate, LLVM 19): 29/29 TUs, 105 results. 33 `uninit-read` (out-parameters filled by OpenSSL, `inet_pton`, `snprintf`, `readlink`: fold does not model them), 15 `null-deref` on `argv`/kernel-supplied pointers, 14 `use-after-move` where the object is only destroyed after the move, 9 `int-truncation` from `sizeof` → `socklen_t`, and 34 heuristic notes were all false positives on source review. Two hardening fixes came out of reading the flagged code: CIDR prefixes are re-validated when the IOC network set loads and nothing broader than /8 (IPv4) or /16 (IPv6) is accepted anywhere, and the `SCM_RIGHTS` parser checks `cmsg_len` before subtracting. Expect these false-positive classes again; triage new results against them first. **exception-escape** (added to fold 2026-10-25): finds exceptions that can reach a `noexcept` function, a destructor, a C callback (libbpf, YARA, curl, sigaction), a thread entry or a terminate handler. That is the class behind the 2026-10-25 freeze. Its call graph covers one TU, and bodies it cannot see are assumed not to throw. `bad_alloc`, `std::function` calls, `at()`, `substr()` and `optional::value()` are reported as heuristic. The scan script filters `third_party/` and `tests/` out of the compile database itself, because `--exclude-glob` does not match its relative `../strawberry/...` paths. Baseline (2026-10-25): 3 heuristic `bad_alloc` findings. Two were fixed (the `rule_updater` curl write callback is now noexcept with try/catch, and the `~StrawberryDaemon` shutdown is guarded); the third (unqlite's destructor) went with the unqlite-cpp submodule, removed in data-engine Stage 1. Source invariant R4 now covers curl `*FUNCTION` options. **int-overflow coverage gap (fixed 2026-10-25):** until fold's fix that day, the `int-overflow` detector segfaulted on most signed arithmetic and the crashing TUs reported no results, so baselines before that date lack int-overflow coverage for `database.cpp`, `correlation_engine.cpp` and others. Always check fold.stderr for "killed by signal" / "scan incomplete" before trusting a count. The first full rescan (29/29 TUs, 75 findings) led to two fixes: `prevention_timeout_ms` is clamped, and behavior-engine timestamps are now safe when events arrive out of order. The rest are recorded as false-positive classes in YAMS `audit-int-overflow-store-2026-10-25.md`. ### Clang static analyzer (complements fold) The host's clang *does* run the Clang Static Analyzer (unlike fold, which needs LLVM 18–19), so it runs natively — no container. It is path-sensitive within a single TU: null deref, use-after-free, leaks, uninitialized reads, logic bugs the type system and clang-tidy miss. Fold adds bounded symbolic cross-call analysis (incl. `exception-escape`); run both. **Changed files only (per change):** `make analyze` (or `scripts/analyze_changed.sh [base]`) runs `clang-check --analyze` over the TUs changed since `base` (default: uncommitted), reading `builddir/compile_commands.json` (the host build may be gcc; clang tolerates those flags), `nice -n 19`, 2 TUs at a time. Strict by default: any analyzer diagnostic fails the run; `ANALYZE_STRICT=0` reports only. `ANALYZE_FILES="src/foo.cpp"` scans an explicit list, `--all` the whole tree. Results in `build/audit/out/analyze.log`. Verify each finding in source before fixing or reporting it, and store the triage in YAMS (`source=evidence`). ## 3. State flow — pipe (experimental C++) ```bash /usr/bin/python3 -I ../pipe/tool/cpp_front.py . --build-dir builddir -o build/audit/strawberry.pipe.json ../pipe/build/cli/linux_x64/bundle/bin/pipe check --model build/audit/strawberry.pipe.json ``` Covers `enum class` state: `ExecVerdict`, `ProcessMonitor::Impl::Backend`, `BehaviorEvent::Type` (the app's `TrayLevel` is only analysed when the app is in the compile database). Read `emitted-not-rendered` as "produced but never branched on" and `rendered-not-emitted` as "branched on but never produced". TinyFSM daemon states are classes, not enums, so pipe does not see them. Baseline (2026-10-25): 22/22 TUs, 3 state enums, 1 info finding (`Backend::none` reached only through `default:`; fixed by an exhaustive switch). ## 4. Record ```bash yams add - --name "audit--.md" \ --metadata "mode=engineering,task=strawberry-audit,phase=complete,owner=opencode,source=evidence,status=done" ``` Include tool versions, coverage numbers, verdict per finding, tests added, and anything left open.