Configuration, Suppressions & CI/CD Guide

Copy Markdown View Source

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
]
KeyTypeDefaultMeaning
env:prod | :dev | :test:prodEnvironment whose dependency closure and build directory are analyzed.
formatatom:terminal:terminal, :json, :markdown, :sarif, :github, :gitlab, :cyclonedx or :openvex.
outputstring | nilnilWrite the report to this file instead of standard output.
sbomstring | nilnilAlso write a CycloneDX 1.6 SBOM to this file.
vexstring | nilnilAlso write an OpenVEX v0.2.0 document to this file.
fail_onatom:potentially_reachable:reachable, :potentially_reachable, :any (also unreachable) or :none.
min_severityatom: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_retiredbooleantrueRetired Hex releases fail the run.
check_retiredbooleantrueQuery Hex.pm for retired releases at all.
show_unreachablebooleanfalseDetail unreachable advisories in terminal and Markdown output.
otp_versionstring | integer | nilrunning OTPOTP release the project is deployed on, for OTP-gated advisories.
offlinebooleanfalseNever use the network; use the cache or a bundle.
bundlestring | nilnilAdvisory bundle imported before the scan.
max_feed_age_secondsinteger | nilnilOSV freshness limit. The default is 24 hours online and unlimited in explicit offline mode.
beam_timeoutpositive integer15000Per-file .beam worker timeout in milliseconds.
max_beam_filespositive integer20000Maximum number of .beam files analyzed in a workspace.
max_beam_bytespositive integer67108864Maximum .beam file size in bytes (64 MiB).
max_beam_heap_bytespositive integer134217728Per-worker heap limit in bytes for .beam analysis (128 MiB).
configured_adapterskeyword list[]Adapter modules per family: tesla, swoosh, ecto, phoenix_pubsub, finch, req. A family may list several modules.
extra_entrypointslist of {Module, :function, arity}[]Functions treated as roots in addition to the detected ones.
ignore_filestring".vulncheck.ignore"Suppression file, relative to the project.
require_ignore_reasonbooleantrueSuppressions without a reason are rejected.
require_ignore_expirybooleanfalseSuppressions without an expires date are rejected.
forbid_new_suppressionsbooleanfalseFail when the ignore file gains or extends suppressions compared with diff.
diffstring | nilnilGit ref. Keep findings related to changed packages or files and retain active findings whose prior state is unknown.
baselinestring | nilnilJSON baseline whose findings are hidden.
cache_dirstring | nil$XDG_CACHE_HOME/vulncheck or ~/.cache/vulncheckFeed and .beam summary cache.
cache_ttl_secondsnon-negative integer3600Age 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() passes expires, the suppression becomes inactive and vulncheck reports 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.ignore with its version at the base ref (e.g., origin/main) and fails with exit code 1 when 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-baseline when an older baseline lacks these fields.

CLI Reference

Mix Tasks

CommandDescription
mix vulncheckRun full dependency & .beam reachability audit.
mix vulncheck.initGenerate .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 syncRevalidate the OSV archive and refresh every referenced CVE record through EEF CNA or MITRE. Exit 2 signals incomplete refresh.
mix vulncheck.feeds statusPrint 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 pruneRemove stored bundle snapshots beyond the three most recently used ones and module caches of other schema versions.

Flags (mix vulncheck and the vulncheck escript)

FlagMeaning
--project-dir DIRProject to scan (default: current directory).
--config FILEConfiguration file (default: DIR/.vulncheck.exs).
--env ENVprod (default), dev or test.
-f, --format FMTterminal (default), json, markdown, sarif, github, gitlab, cyclonedx or openvex.
-o, --output FILEWrite the report to a file instead of standard output.
--sarif FILEAlso write a SARIF 2.1.0 report from the same scan.
--sbom FILEAlso write a CycloneDX 1.6 SBOM.
--vex FILEAlso write an OpenVEX v0.2.0 document.
--fail-on TIERreachable, potentially_reachable (default), any or none.
--min-severity SEVlow (default), medium, high or critical.
--[no-]fail-on-retiredFail on retired Hex releases (default: on).
--no-retiredSkip the Hex retirement check.
--show-unreachableDetail unreachable advisories.
--diff REFShow changes since the Git ref while retaining active findings with no baseline evidence.
--baseline FILEHide findings recorded in a JSON baseline.
--write-baseline FILERecord the complete scan as a baseline before display filters.
--forbid-new-suppressionsFail when .vulncheck.ignore gains or extends suppressions since --diff.
--ignore-file FILESuppression file (default: .vulncheck.ignore).
--otp-version VEROTP release the project runs on (default: the running VM's).
--offlineNever use the network; use the cache or --bundle.
--bundle FILERead an advisory bundle for this scan only.
--cache-dir DIRFeed and .beam summary cache directory.
--cache-ttl SECONDSFeed freshness (default: 3600).
--max-feed-age SECONDSMaximum accepted age of the cached OSV archive. Use 0 for live validation on every scan.
--no-colorDisable ANSI colors (also NO_COLOR=1).
-q, --quietHide 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:

SnapshotSelected byRead by
Live cacheOnline scans and feeds syncOnline scans; offline scans when it is at least as recent as the imported snapshot
Imported snapshotfeeds import FILEOffline scans while it is newer than the live cache
--bundle snapshot--bundle FILEThat 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 CodeMeaning
0Clean — zero findings at or above --fail-on and --min-severity thresholds.
1Policy violation — findings, retired packages, expired or forbidden suppressions, or an invalid ignore policy. Reports are available.
2Execution 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: true

Pull 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: false

The 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.json

Container 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: vulncheck

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