vulncheck works out of the box with zero configuration files. For team-wide policy enforcement, create a .vulncheck.exs file in the repository root via mix vulncheck.init.
.vulncheck.exs Configuration Schema
.vulncheck.exs is read as literal data: it must be a keyword list of plain values (atoms, strings, numbers, booleans, module aliases, lists and tuples). Nothing in it is evaluated, unknown keys are rejected, and command-line flags override file values.
[
# Mix environment whose dependency closure and _build/<env> artifacts are analyzed
env: :prod,
# Verdict tier that fails the run (exit code 1)
fail_on: :potentially_reachable,
# Minimum advisory severity that fails the run
min_severity: :low,
# Retired Hex releases fail the run
fail_on_retired: true,
# Runtime adapters configured outside of compiled code
configured_adapters: [
tesla: Tesla.Adapter.Mint
],
# Additional roots, e.g. functions called through release eval or RPC
extra_entrypoints: [
{MyApp.Release, :migrate, 0}
],
# Suppression governance
ignore_file: ".vulncheck.ignore",
require_ignore_reason: true,
require_ignore_expiry: false
]| Key | Type | Default | Meaning |
|---|---|---|---|
env | :prod | :dev | :test | :prod | Environment whose dependency closure and build directory are analyzed. |
format | atom | :terminal | :terminal, :json, :markdown, :sarif, :github, :gitlab, :cyclonedx or :openvex. |
output | string | nil | nil | Write the report to this file instead of standard output. |
sbom | string | nil | nil | Also write a CycloneDX 1.6 SBOM to this file. |
vex | string | nil | nil | Also write an OpenVEX v0.2.0 document to this file. |
fail_on | atom | :potentially_reachable | :reachable, :potentially_reachable, :any (also unreachable) or :none. |
min_severity | atom | :low | :low, :medium, :high or :critical; findings below it never fail the run. Severity none (CVSS 0.0) counts as low, and unknown (no CVSS data) as critical. |
fail_on_retired | boolean | true | Retired Hex releases fail the run. |
check_retired | boolean | true | Query Hex.pm for retired releases at all. |
show_unreachable | boolean | false | Detail unreachable advisories in terminal and Markdown output. |
otp_version | string | integer | nil | running OTP | OTP release the project is deployed on, for OTP-gated advisories. |
offline | boolean | false | Never use the network; use the cache or a bundle. |
bundle | string | nil | nil | Advisory bundle imported before the scan. |
max_feed_age_seconds | integer | nil | nil | OSV freshness limit. The default is 24 hours online and unlimited in explicit offline mode. |
beam_timeout | positive integer | 15000 | Per-file .beam worker timeout in milliseconds. |
max_beam_files | positive integer | 20000 | Maximum number of .beam files analyzed in a workspace. |
max_beam_bytes | positive integer | 67108864 | Maximum .beam file size in bytes (64 MiB). |
max_beam_heap_bytes | positive integer | 134217728 | Per-worker heap limit in bytes for .beam analysis (128 MiB). |
configured_adapters | keyword list | [] | Adapter modules per family: tesla, swoosh, ecto, phoenix_pubsub, finch, req. A family may list several modules. |
extra_entrypoints | list of {Module, :function, arity} | [] | Functions treated as roots in addition to the detected ones. |
ignore_file | string | ".vulncheck.ignore" | Suppression file, relative to the project. |
require_ignore_reason | boolean | true | Suppressions without a reason are rejected. |
require_ignore_expiry | boolean | false | Suppressions without an expires date are rejected. |
forbid_new_suppressions | boolean | false | Fail when the ignore file gains or extends suppressions compared with diff. |
diff | string | nil | nil | Git ref. Keep findings related to changed packages or files and retain active findings whose prior state is unknown. |
baseline | string | nil | nil | JSON baseline whose findings are hidden. |
cache_dir | string | nil | $XDG_CACHE_HOME/vulncheck or ~/.cache/vulncheck | Feed and .beam summary cache. |
cache_ttl_seconds | non-negative integer | 3600 | Age after which cached feeds are refreshed. |
mix vulncheck.init writes a commented file with these keys and adds hints for the frameworks and adapters it detects in the lockfile.
Governed Suppressions (.vulncheck.ignore)
Security teams need auditable, time-bounded exceptions rather than permanent silent ignores. .vulncheck.ignore is a literal list of maps. Each entry needs an advisory id (the advisory ID or any alias such as a CVE ID), a reason (required unless require_ignore_reason: false), and optionally a package to narrow the match and an ISO-8601 expires date (required when require_ignore_expiry: true):
[
%{
id: "CVE-2026-54892",
package: "plug",
reason: "WAF blocks nested query depth > 4 at Cloudflare edge; upgrade scheduled in Sprint 48",
expires: "2027-01-31"
}
]- Expired Suppressions Fail Loudly: Once
Date.utc_today()passesexpires, the suppression becomes inactive andvulncheckreports an expired-exception warning alongside the finding. - Stale Entries Are Reported: A suppression that no longer matches any finding produces a warning, so the file does not accumulate dead exceptions.
- Anti-Cheat PR Guardrail (
--forbid-new-suppressions): Together with--diff <ref>, compares.vulncheck.ignorewith its version at the base ref (e.g.,origin/main) and fails with exit code1when a change adds a suppression or moves an existing expiry date later. - A package-specific rule takes precedence over a global rule for the same finding. Conflicting rules at the same scope leave the finding active and report a policy violation.
- A baseline can hide a finding when the earlier observation matches its locked package identity, version, scope and suppression state and had at least its current severity. Prefer refreshing baselines via
--write-baselinewhen an older baseline lacks these fields.
CLI Reference
Mix Tasks
| Command | Description |
|---|---|
mix vulncheck | Run full dependency & .beam reachability audit. |
mix vulncheck.init | Generate .vulncheck.exs tailored to the detected project structure. |
mix vulncheck.explain <ID> | Show full CVE details, affected programRoutines, fixed versions, and local reachability status. |
mix vulncheck.feeds sync | Revalidate the OSV archive and refresh every referenced CVE record through EEF CNA or MITRE. Exit 2 signals incomplete refresh. |
mix vulncheck.feeds status | Print local cache location, ETag timestamps, advisory counts, the imported snapshot and the snapshot offline scans read. |
mix vulncheck.feeds bundle -o <path> | Export self-contained .tar.gz advisory bundle for air-gapped CI runners. |
mix vulncheck.feeds import <path> | Validate a bundle and select it for later offline scans. |
mix vulncheck.feeds prune | Remove stored bundle snapshots beyond the three most recently used ones and module caches of other schema versions. |
Flags (mix vulncheck and the vulncheck escript)
| Flag | Meaning |
|---|---|
--project-dir DIR | Project to scan (default: current directory). |
--config FILE | Configuration file (default: DIR/.vulncheck.exs). |
--env ENV | prod (default), dev or test. |
-f, --format FMT | terminal (default), json, markdown, sarif, github, gitlab, cyclonedx or openvex. |
-o, --output FILE | Write the report to a file instead of standard output. |
--sarif FILE | Also write a SARIF 2.1.0 report from the same scan. |
--sbom FILE | Also write a CycloneDX 1.6 SBOM. |
--vex FILE | Also write an OpenVEX v0.2.0 document. |
--fail-on TIER | reachable, potentially_reachable (default), any or none. |
--min-severity SEV | low (default), medium, high or critical. |
--[no-]fail-on-retired | Fail on retired Hex releases (default: on). |
--no-retired | Skip the Hex retirement check. |
--show-unreachable | Detail unreachable advisories. |
--diff REF | Show changes since the Git ref while retaining active findings with no baseline evidence. |
--baseline FILE | Hide findings recorded in a JSON baseline. |
--write-baseline FILE | Record the complete scan as a baseline before display filters. |
--forbid-new-suppressions | Fail when .vulncheck.ignore gains or extends suppressions since --diff. |
--ignore-file FILE | Suppression file (default: .vulncheck.ignore). |
--otp-version VER | OTP release the project runs on (default: the running VM's). |
--offline | Never use the network; use the cache or --bundle. |
--bundle FILE | Read an advisory bundle for this scan only. |
--cache-dir DIR | Feed and .beam summary cache directory. |
--cache-ttl SECONDS | Feed freshness (default: 3600). |
--max-feed-age SECONDS | Maximum accepted age of the cached OSV archive. Use 0 for live validation on every scan. |
--no-color | Disable ANSI colors (also NO_COLOR=1). |
-q, --quiet | Hide warnings. |
mix vulncheck.init accepts --project-dir and --force (overwrite an existing file). mix vulncheck.explain accepts --project-dir, --offline and --bundle.
Offline Feed Snapshots
An offline scan reads one of these snapshots:
| Snapshot | Selected by | Read by |
|---|---|---|
| Live cache | Online scans and feeds sync | Online scans; offline scans when it is at least as recent as the imported snapshot |
| Imported snapshot | feeds import FILE | Offline scans while it is newer than the live cache |
--bundle snapshot | --bundle FILE | That scan only |
Bundle import validates the complete manifest, file digests and feed contents before the snapshot is used. Absent records remain absent in that snapshot. The manifest preserves source fetch times, including unknown age in older bundles, and an imported snapshot of unknown age is older than any dated live cache.
The JSON feed object and the SARIF run property feed record the snapshot (live, imported or bundle), the reason for the choice, the source, the age and the advisory count. The terminal report prints the same on its Feed: line. A scan warns when its snapshot is older than the other one or holds less than 90% of its OSV records.
Bundle snapshots are stored under feed-bundles/ in the cache directory and named after their manifest digest, so importing the same bundle again reuses its directory. Each import keeps the imported snapshot and the three most recently used ones and removes the rest. feeds prune applies the same limit on demand, and also removes module caches written by other cache schema versions (beam-vN) and the snapshot pointer of 1.0.0, which selected every --bundle for later offline scans. Up to three concurrent scans with different bundles may share one cache directory.
An online scan can use a verified previous OSV archive after a failed refresh if it is within its configured age limit. A cold scan or one past the limit returns exit 2. The native JSON feed object contains the source, status, age, refresh error and discarded record count. feeds status reports a missing archive, a validated archive or an invalid archive with exit 2.
explain shows whether the installed version matches the advisory, the local reachability verdict when available, and the effect of suppressions or display filters. A missing or incomplete local scan is reported separately from an unaffected installed version. Unsupported lockfile entries, partially parsed mix.exs files, and profile mismatches between _build/<env> and --env are recorded as warnings and mark analysis.status incomplete (partial) so unparsed dependencies are never silently dismissed.
Exit Codes
| Exit Code | Meaning |
|---|---|
0 | Clean — zero findings at or above --fail-on and --min-severity thresholds. |
1 | Policy violation — findings, retired packages, expired or forbidden suppressions, or an invalid ignore policy. Reports are available. |
2 | Execution error — invalid flags or configuration, overlapping destinations, missing or unparseable lockfile, or unavailable feeds. |
CI/CD Recipes
GitHub Actions (composite action)
Trusted branches (with compilation and SARIF upload):
on:
push:
branches: [main]
jobs:
vulncheck:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # needed for diff
- uses: erlef/setup-beam@v1
with:
otp-version: "27.2"
elixir-version: "1.18"
- uses: Voskan/vulncheck@v1.0.1
with:
fail-on: potentially_reachable
upload-sarif: truePull requests (untrusted checkouts):
By default compile is "true", which executes the project's build tools and macros. For untrusted pull requests (such as forks), never grant security-events: write or secrets to a job that compiles untrusted code: run without security-events: write (or scan prebuilt artifacts with compile: "false"), and upload SARIF from a separate workflow_run job if needed:
on:
pull_request:
jobs:
vulncheck:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: erlef/setup-beam@v1
with:
otp-version: "27.2"
elixir-version: "1.18"
- uses: Voskan/vulncheck@v1.0.1
with:
fail-on: potentially_reachable
diff: origin/${{ github.base_ref }}
forbid-new-suppressions: true
upload-sarif: falseThe action builds the escript, compiles the project (compile: false skips this for prepared artifacts), and caches advisory feeds (~/.cache/vulncheck/feeds). Annotations, the job summary and optional SARIF come from one scan. A policy failure records exit 1 and uploads available SARIF before enforcing the policy. Execution errors record exit 2 and skip the upload. The action provides exit-code and sarif-file outputs.
GitLab CI (Code Quality widget)
vulncheck:
image: hexpm/elixir:1.18.4-erlang-27.3.4.16-alpine-3.22.5
script:
- mix local.hex --force --if-missing
- mix local.rebar --force --if-missing
- mix deps.get
- MIX_ENV=prod mix compile
- mix escript.install hex vulncheck --force
- ~/.mix/escripts/vulncheck --format gitlab --output gl-code-quality-report.json
artifacts:
when: always
reports:
codequality: gl-code-quality-report.jsonContainer image
docker build -t vulncheck https://github.com/Voskan/vulncheck.git
docker run --rm -v "$PWD:/workspace" vulncheck --format sarif --output vulncheck.sarif
The image runs the escript as an unprivileged user on an Erlang runtime with git (for --diff) and CA certificates. Compile the project first so _build is present in the mounted workspace; without it, findings fall back to package-level verdicts.
pre-commit
repos:
- repo: https://github.com/Voskan/vulncheck
rev: v1.0.1
hooks:
- id: vulncheckInstall the vulncheck executable and make it available on PATH. The hook runs from the repository root for Mix, rebar3 and Gleam workspaces when mix.lock, rebar.lock, manifest.toml or .vulncheck.ignore changes. Use vulncheck-offline when the machine has no network access.