Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    The rescan cache

    View as Markdown

    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.

    • 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.

    Scan twice. The second run finds the same tree, the same rules and the same settings, and returns the stored report without scanning:

    Terminal window
    keryn scan . --quiet || true
    keryn 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.

    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:

    Terminal window
    echo "# edited" >> agent.py
    keryn 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 expires suppression or a policy waiver, across a UTC day boundary: the report could be wrong the next day.
    Terminal window
    keryn cache stats | sed -E 's/ in .*//; s/[0-9.]+ MB/<size> MB/'
    3 entries, <size> MB

    keryn 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.

    Terminal window
    KERYN_NO_CACHE=1 keryn scan . 2>&1 | sed -n '1,1p'
    keryn scan . --no-cache --quiet
    Keryn — 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.

    Terminal window
    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.

    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).

    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.