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