VulnCheck.Cache (VulnCheck v1.0.1)

Copy Markdown View Source

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 summaries

Every 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

fetch_status()

@type fetch_status() :: :network | :cached | :revalidated | :stale

Functions

atomic_write(path, data)

@spec atomic_write(Path.t(), iodata()) :: :ok | {:error, term()}

Atomically writes data to path (temporary file + rename).

beam_dir(config)

@spec beam_dir(VulnCheck.Config.t()) :: String.t()

Directory holding cached .beam summaries.

dir(config)

@spec dir(VulnCheck.Config.t() | keyword()) :: String.t()

Root cache directory for a configuration.

export_bundle(config, path)

@spec export_bundle(VulnCheck.Config.t(), Path.t()) :: {:ok, map()} | {:error, term()}

Exports a verified snapshot of cached feeds.

feeds_dir(config)

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

fetch(url, rel_path, config, opts \\ [])

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

fetch_validated(url, rel_path, config, opts, validator)

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

get_beam(config, sha)

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

import_bundle(path, config)

@spec import_bundle(Path.t(), VulnCheck.Config.t()) :: {:ok, map()} | {:error, term()}

Validates a bundle and selects it for later offline scans.

list_feed_files(config)

@spec list_feed_files(VulnCheck.Config.t()) :: [String.t()]

Lists cached feed resources (relative paths), excluding metadata and temporary files.

prune(config)

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

put_beam(config, sha, summary)

@spec put_beam(VulnCheck.Config.t() | keyword(), String.t(), term()) ::
  :ok | {:error, term()}

Stores a module summary under its .beam SHA-256.

read_feed(config, rel_path)

@spec read_feed(VulnCheck.Config.t(), String.t()) ::
  {:ok, binary()} | {:error, term()}

Reads a verified cached feed file without any network access.

read_meta(path)

@spec read_meta(Path.t()) :: map()

Reads verified metadata stored with a cached file.

sha256(data)

@spec sha256(iodata()) :: String.t()

SHA-256 hex digest of a binary.