2945e59bc2
The README listed 11 of fold's 17 detectors, never explained the confidence tiers every finding carries, did not mention the new exit code 2 / coverage reporting, and spent half its length on a performance roadmap. It now says what fold is, defines the five tiers (from include/fold/report/finding.hpp, including concrete-witness and latent), what "bounded" means after the loop-exit fix, a quick start, output formats and exit codes (0 none, 1 any unsuppressed finding, 2 unwritable report or any unanalysed translation unit), and links. The detector list defers to the complete table in docs/USAGE.md. The performance section moves to docs/architecture/performance.md, with one correction: the gold set was derived from fold's own reviewed output and is matched by detector kind and file, so it catches drift rather than measuring precision/recall independently. The lint pre-commit hook note moves to BUILD.md.
58 lines
2.5 KiB
Markdown
58 lines
2.5 KiB
Markdown
# fold
|
|
|
|
Bounded symbolic static analysis for C++: dead-branch and hazard detection
|
|
(null dereference, division by zero, integer overflow, out-of-bounds, and more),
|
|
clone and equivalence detection, and taint tracking, built on Clang LibTooling
|
|
and the Z3 solver. Rust (HIR), Swift and binary scan modes also exist; the Rust
|
|
detectors are heuristic today.
|
|
|
|
Every finding carries a confidence tier that says how it was established:
|
|
|
|
| Tier | Meaning |
|
|
| --- | --- |
|
|
| `concrete-witness` | A fuzzer ran the solver's witness under a sanitizer and produced a correlated crash. |
|
|
| `proved` | An exact bounded model proved it: SAT for a hazard witness, or UNSAT for a negated invariant. |
|
|
| `latent` | Proved inside the function, but only reachable if a caller supplies a value the callee never guards. |
|
|
| `heuristic` | Some part of the model was over-approximated. |
|
|
| `syntactic` | An AST pattern or hash match only. |
|
|
|
|
"Bounded" is literal: loops are unrolled to a fixed depth, and a condition that
|
|
depends on a loop's exit is never reported as proved. The contract behind each
|
|
tier is in [docs/research/soundness.md](docs/research/soundness.md).
|
|
|
|
## Quick start
|
|
|
|
```sh
|
|
./setup.sh release # needs LLVM/Clang 18+ and libz3 headers; Conan handles the rest
|
|
fold scan --compile-db compile_commands.json \
|
|
--detectors null-deref --detectors div-by-zero \
|
|
--format sarif --output findings.sarif
|
|
fold grep "null pointer" findings.sarif --field message --ignore-case
|
|
```
|
|
|
|
Per-platform install lines and a Docker validation harness are in
|
|
[BUILD.md](BUILD.md).
|
|
|
|
Output formats are `sarif`, versioned `findings-json`, and `markdown`. Both
|
|
machine formats record which translation units were analysed. A scan exits `0`
|
|
with no findings, `1` with any unsuppressed finding, and `2` when a report could
|
|
not be written or any translation unit was not analysed (compile errors,
|
|
frontend failure, crash, timeout): no findings from an incomplete scan is not
|
|
evidence of no bugs.
|
|
|
|
## Documentation
|
|
|
|
- [Usage](docs/USAGE.md): the full CLI (scan modes, scopes, confirmation,
|
|
fuzzing), every detector with its CWE and method, MCP/LSP, and project
|
|
evaluation.
|
|
- [MCP tools](docs/mcp-tools.md) and [compatibility](docs/compatibility.md)
|
|
(deprecated names and removal criteria).
|
|
- [Positioning](docs/positioning.md) and [prior art](docs/research/prior-art.md):
|
|
how fold relates to other analyzers.
|
|
- [Performance](docs/architecture/performance.md): the evaluation gates and the
|
|
single-pass graph-building plan.
|
|
- [Architecture](docs/architecture/) and [research](docs/research/) notes.
|
|
|
|
## License
|
|
|
|
GPL-3.0-only
|