The rescan cache
Know when Keryn answers a scan from a stored report instead of scanning, what that store holds and where it lives, and how to bypass or empty it: with --no-cache, KERYN_NO_CACHE=1, keryn cache clear|stats|path, and the keryn-rescan database in the browser.
Before you start
Section titled “Before you start”- The Keryn CLI (install). The cache is on by default; there is nothing to enable.
- The cache holds reports of code on this machine, including the few lines of code each finding quotes. It never holds a token, and nothing in it is sent anywhere.
1. See a hit
Section titled “1. See a hit”Scan twice. The second run finds the same tree, the same rules and the same settings, and returns the stored report without scanning:
keryn scan . --quiet || truekeryn scan . 2>&1 | sed 's/since .* UTC/since <time>/' | sed -n '1,3p'keryn: unchanged since <time>, cached report (--no-cache rescans)Keryn — Policy blocked (Hold); dependency advisories not checked (offline) 1 violation(s)/finding(s) at or above 'error'The first line is on standard error and says it was a hit. The numbers on the second line are those of the scan that produced the report, including its duration; a hit does not take that long. The cached report carries the same exit code the scan had.
2. See what changes the answer
Section titled “2. See what changes the answer”The key is a digest of the engine (Keryn and engine versions, the packaged WebAssembly, the Deep and known-fix identities), the rule texts, the settings that change a report, and the tree (every path with a SHA-256 of its content). Change one file and the key changes:
echo "# edited" >> agent.pykeryn scan . 2>&1 | sed -n '1,1p'Keryn — Policy blocked (Hold); dependency advisories not checked (offline)No unchanged since line: this is a real scan. It is cheaper than the first one in one way only. The pattern pass is file-local, so a file whose content, path, rules and engine are unchanged reuses its matches; Deep, known-fix matching, the inventory and deduplication run again over the whole tree, because they can depend on any file. A one-line edit saves the pattern pass, not Deep.
A report is also not reused in these cases, on purpose:
- a scan with
--base(the comparison is the point; see baselines) or with observations (--observed-browser,--observed-network), - a scan whose Deep or known-fix stage failed or was stopped, and files that hit a rule’s time budget,
- a scan with an
expiressuppression or a policy waiver, across a UTC day boundary: the report could be wrong the next day.
3. Look at it
Section titled “3. Look at it”keryn cache stats | sed -E 's/ in .*//; s/[0-9.]+ MB/<size> MB/'3 entries, <size> MBkeryn cache path prints the directory, one file per stored scan, readable only by you. Defaults: macOS ~/Library/Caches/keryn/rescan, Linux $XDG_CACHE_HOME/keryn/rescan or ~/.cache/keryn/rescan, Windows %LOCALAPPDATA%\keryn\Cache\rescan. Set KERYN_CACHE_DIR to move it, for example onto the volume a CI job caches between runs. The cache is capped (512 MB for the CLI and the language server); the least recently used entries go first.
4. Bypass it, or empty it
Section titled “4. Bypass it, or empty it”KERYN_NO_CACHE=1 keryn scan . 2>&1 | sed -n '1,1p'keryn scan . --no-cache --quietKeryn — Policy blocked (Hold); dependency advisories not checked (offline)--no-cache (on scan and bundle) and KERYN_NO_CACHE=1 neither read nor write the cache for that run. Use them when you want a measured, from-scratch scan, when you are comparing two builds of Keryn, or in a job that must not leave files in a cache directory. If you are working on a checkout of Keryn itself, remember that the engine identity does not hash source you changed without bumping the version.
keryn cache clear | sed -E 's/ from .*//; s/\([0-9.]+ MB\)/(<size> MB)/'cleared 3 entries (<size> MB)keryn cache clear deletes everything the cache holds. Clear it after a scan of code you must not leave traces of, because a stored report quotes lines of that code.
5. In the browser
Section titled “5. In the browser”Keryn Web (and its portfolio view, which uses the same scanner) keeps the same kind of cache in IndexedDB, in a database named keryn-rescan, capped at 256 MB with the same least-recently-used eviction. Entries are keyed by digests of file contents, rules and settings, or by the commit of a public GitHub repository, so scanning the same commit again answers without downloading it. If the browser blocks IndexedDB there is simply no cache.
To empty it, use Settings, Clear cache (or Clear saved data, which clears more). To look at it, open your browser’s developer tools, Application (Storage in Firefox), IndexedDB, keryn-rescan. Two other databases sit next to it and are not part of this cache: keryn-portfolio (saved portfolios) and keryn-gh-cache (GitHub’s answers, with their ETags, for seven days).
What you just proved
Section titled “What you just proved”The cache is a local edge that you can see and cut: a directory (or a browser database) of reports, keyed by content, that never leaves the machine, with one command to inspect it and one to remove it. The property it keeps is the one the rest of Keryn keeps: the same input gives the same answer. A cached report is returned only when every input to the key is identical, and a stale one cannot be returned, because a changed input is a different key.
- What else stays on the machine: local by design and privacy.
- Faster scans in CI: CI, and
KERYN_CACHE_DIRon a cached volume. - Read what a rule says offline: explain and docs.