Atomic on-disk cache for advisory feeds and analyzed .beam modules, plus
air-gapped bundle export/import.
Layout (default root: $XDG_CACHE_HOME/vulncheck or ~/.cache/vulncheck):
feeds/osv_hex_all.zip.entry OSV Hex archive and metadata
feeds/cves/<CVE-ID>.json.entry EEF CNA / MITRE records and metadata
feeds/hex/packages/<name>.json.entry Hex.pm package metadata
beam-v4/<sha256>.etf cached module summariesEvery write goes to a unique temporary file that is then renamed into place, so concurrent CI jobs sharing a cache never observe partial files.
Summary
Functions
Atomically writes data to path (temporary file + rename).
Directory holding cached .beam summaries.
Root cache directory for a configuration.
Exports a verified snapshot of cached feeds.
Directory holding feed data. Offline runs read the most recent valid
snapshot: the live cache or the snapshot selected by feeds import.
Returns the body of a cached resource. For resources that affect scan
results, use fetch_validated/5 to validate and decode before publication.
Fetches and decodes a resource, publishing its body and metadata together
only after validation succeeds. Returns the decoded value, refresh
status (:network | :cached | :revalidated | :stale) and metadata. Options
include :http_client, :http_opts, :offline, :ttl, :immutable,
:force, :allow_stale and :max_age.
Reads a cached module summary by .beam SHA-256. Corrupt entries, oversized
entries, schema mismatches or entries that would require creating atoms are
treated as misses.
Validates a bundle and selects it for later offline scans.
Lists cached feed resources (relative paths), excluding metadata and temporary files.
Removes imported feed snapshots beyond the most recently used ones (the
snapshot selected by feeds import is kept) and module caches written by
other cache schema versions.
Stores a module summary under its .beam SHA-256.
Reads a verified cached feed file without any network access.
Reads verified metadata stored with a cached file.
SHA-256 hex digest of a binary.
Types
Functions
Atomically writes data to path (temporary file + rename).
@spec beam_dir(VulnCheck.Config.t()) :: String.t()
Directory holding cached .beam summaries.
@spec dir(VulnCheck.Config.t() | keyword()) :: String.t()
Root cache directory for a configuration.
@spec export_bundle(VulnCheck.Config.t(), Path.t()) :: {:ok, map()} | {:error, term()}
Exports a verified snapshot of cached feeds.
@spec feeds_dir(VulnCheck.Config.t()) :: String.t()
Directory holding feed data. Offline runs read the most recent valid
snapshot: the live cache or the snapshot selected by feeds import.
@spec fetch(String.t(), String.t(), VulnCheck.Config.t(), keyword()) :: {:ok, binary(), fetch_status()} | {:error, term()}
Returns the body of a cached resource. For resources that affect scan
results, use fetch_validated/5 to validate and decode before publication.
@spec fetch_validated( String.t(), String.t(), VulnCheck.Config.t(), keyword(), function() ) :: {:ok, term(), fetch_status(), map()} | {:error, term()}
Fetches and decodes a resource, publishing its body and metadata together
only after validation succeeds. Returns the decoded value, refresh
status (:network | :cached | :revalidated | :stale) and metadata. Options
include :http_client, :http_opts, :offline, :ttl, :immutable,
:force, :allow_stale and :max_age.
When :force is true and the refresh fails with a transient or 5xx error,
allow_stale: true (the default) falls back to the last verified copy with
status :stale and records "refresh_error" in metadata; pass
allow_stale: false to fail instead.
@spec get_beam(VulnCheck.Config.t() | keyword(), String.t()) :: {:ok, term()} | :miss
Reads a cached module summary by .beam SHA-256. Corrupt entries, oversized
entries, schema mismatches or entries that would require creating atoms are
treated as misses.
@spec import_bundle(Path.t(), VulnCheck.Config.t()) :: {:ok, map()} | {:error, term()}
Validates a bundle and selects it for later offline scans.
@spec list_feed_files(VulnCheck.Config.t()) :: [String.t()]
Lists cached feed resources (relative paths), excluding metadata and temporary files.
@spec prune(VulnCheck.Config.t()) :: %{ snapshots: non_neg_integer(), snapshot_bytes: non_neg_integer(), module_caches: non_neg_integer(), module_cache_bytes: non_neg_integer() }
Removes imported feed snapshots beyond the most recently used ones (the
snapshot selected by feeds import is kept) and module caches written by
other cache schema versions.
@spec put_beam(VulnCheck.Config.t() | keyword(), String.t(), term()) :: :ok | {:error, term()}
Stores a module summary under its .beam SHA-256.
@spec read_feed(VulnCheck.Config.t(), String.t()) :: {:ok, binary()} | {:error, term()}
Reads a verified cached feed file without any network access.
Reads verified metadata stored with a cached file.
SHA-256 hex digest of a binary.