strawberry/docs/prompts/PROMPT-strawberry-audit.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

183 lines
9.7 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.

---
description: Strawberry audit flow — brick (structure), fold (bounded symbolic SAST), pipe (enum-class state flow), with YAMS-recorded triage.
argument-hint: "[TASK=strawberry-audit-<topic>] [PHASE=<start|checkpoint|complete>]"
---
# 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/<type>/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-<topic>-<date>.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.