VulnCheck

Hex.pm HexDocs CI License: MIT Zero Runtime Deps

Function-level reachability vulnerability scanner for Elixir, Erlang, and Gleam (govulncheck for the BEAM).

vulncheck bridges the gap between lockfile dependency scanners (mix deps.audit, mix hex.audit) and what your compiled BEAM release actually executes. Instead of failing CI whenever any transitive Hex package receives a CVE, vulncheck pairs OSV.dev and Erlang Ecosystem Foundation (EEF) CNA CVE 5.1 programRoutines metadata with post-macro .beam bytecode call graphs, OTP supervision roots, Plug/Phoenix pipelines, and runtime adapter configurations to prove whether vulnerable functions are reachable in your production code.


Why VulnCheck Exists

Recent Hex ecosystem disclosures include dozens of structured CVEs across core packages such as plug, phoenix, bandit, ash, mint, hackney, cowlib, and tesla.

Traditional lockfile scanners suffer from two structural limitations:

  1. Package-Level Alert Fatigue: Tools that only compare mix.lock versions flag an entire dependency even when the CVE affects a single optional parser, unused HTTP adapter, aggregate helper, or an older OTP runtime.
  2. Unused Official Symbol Data: EEF CNA CVE 5.1 advisories explicitly publish affected MFA symbols under programRoutines (for example, 'Elixir.Plug.Conn.Query':decode/4 or 'Elixir.Ash.Actions.Aggregate':run/4), yet existing BEAM audit tools ignore symbol-level metadata altogether.

At the same time, a naive static call graph is unsafe on the BEAM: HTTP servers (Bandit, :cowboy), Plug pipelines, GenServer / Oban callbacks, and runtime-configured HTTP adapters (Tesla, Swoosh, Finch) are wired via OTP supervision specs, expanded macros, and Application environment terms rather than direct main() calls. vulncheck models BEAM execution semantics soundly so network-exposed daemons and dynamic dispatches are never silently dismissed.


Design Highlights


Comparison with Existing Tools

Capability mix_audit mix hex.audit sobelow vulncheck
Lockfile version matching (mix.lock) Yes Retired only No Yes (mix.lock, rebar.lock, manifest.toml)
EEF CNA CVE 5.1 programRoutines MFA ingestion No No No Yes
Post-macro .beam call-graph reachability No No No Yes (file:line call chains)
OTP supervision & Plug / Tesla adapter awareness No No No Yes (sound 3-tier model)
OTP runtime version gating (--otp-version) No No No Yes (Elixir version in metadata is the scanner VM)
SARIF 2.1.0 codeFlows & OpenVEX / CycloneDX 1.6 No No SARIF (app rules) Yes
Air-gapped offline bundle mode No No N/A (SAST only) Yes (--offline / --bundle)

Quick Start

Elixir / Mix Installation

Add vulncheck to your mix.exs dependencies:

def deps do
  [
    {:vulncheck, "~> 1.0", only: [:dev, :test], runtime: false}
  ]
end

Compile your project (so .beam debug chunks are up to date) and run the audit:

mix deps.get
MIX_ENV=prod mix compile
mix vulncheck

Standalone Escript (Erlang rebar3, Gleam, or CI Containers)

Build the standalone escript from source (or install from Hex once it is published via mix escript.install hex vulncheck):

MIX_ENV=prod mix escript.build
./vulncheck --project-dir /path/to/service

Example Terminal Output

VulnCheck 1.0.1 — BEAM Reachability Vulnerability Audit
Target: my_fintech_api (mix, Elixir 1.18.2 / OTP 27.2, env: prod)
Lockfile: 74 prod packages (19 dev/test excluded) · Scan time: 142 ms (cached)

[REACHABLE] CVE-2026-101028 (HIGH · CVSS 7.5) — ash 3.34.2 (fix: 3.34.6)
  Summary: Ash.count, Ash.exists and Ash.aggregate skip related resources' read policies
  Target:  Ash.Actions.Aggregate.run/4
  Trace:
    1. MyFintechWeb.ReportController.index/2     (lib/my_fintech_web/controllers/report_controller.ex:41)
    2. MyFintech.Ledger.count_filtered_entries/2 (lib/my_fintech/ledger.ex:112)
    3. Ash.count/2                               (deps/ash/lib/ash.ex:1184)
    4. Ash.Actions.Aggregate.run/4               (deps/ash/lib/ash/actions/aggregate.ex:29)

[POTENTIALLY REACHABLE] CVE-2026-54892 (MEDIUM · CVSS 6.5) — plug 1.16.2 (fix: 1.16.4)
  Summary: Quadratic-time nested parameter decoding in Plug.Conn.Query
  Reason:  plug runs inside the HTTP pipeline started by MyFintechWeb.Endpoint (active_network_daemon)

Suppressed as UNREACHABLE (6 advisories — pass --show-unreachable for details):
  • 3 in hackney 1.20.1  (adapter_not_configured: Tesla is configured with Tesla.Adapter.Mint)
  • 1 in hex_core 0.10.0 (otp_version_unaffected: requires OTP <= 25; running OTP 27.2)
  • 1 in meck 0.9.2      (non_prod_dependency: meck is only used in :test)
  • 1 in plug 1.16.2     (function_not_called: Plug.Parsers.MULTIPART.init/1 is never called)

Summary: 1 reachable, 1 potentially reachable, 6 unreachable (75% noise reduction)
Exit code: 1 (threshold: --fail-on potentially_reachable, --min-severity low)

Common CLI & CI Workflows

# Fail CI only on proven reachable vulnerabilities
mix vulncheck --fail-on reachable

# Emit SARIF 2.1.0 with full call-graph codeFlows for GitHub Code Scanning
mix vulncheck --format sarif --output vulncheck.sarif

# Generate CycloneDX 1.6 SBOM + OpenVEX v0.2.0 statements for compliance audits
mix vulncheck --sbom sbom.cdx.json --vex vex.openvex.json

# PR gate: block new reachable CVEs and forbid sneaking in new suppressions
mix vulncheck --diff origin/main --forbid-new-suppressions

# Export an air-gapped advisory bundle for isolated build networks
mix vulncheck.feeds bundle --output vulncheck-feeds.tar.gz
mix vulncheck --offline --bundle vulncheck-feeds.tar.gz
# Or select it for every later offline scan while it is newer than the cache
mix vulncheck.feeds import vulncheck-feeds.tar.gz

GitHub Actions Integration

For trusted branches (where compiling the checkout is safe):

name: Security
on:
  push:
    branches: [main]

jobs:
  vulncheck:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write # SARIF upload to Code Scanning
    steps:
      - uses: actions/checkout@v4
      - uses: erlef/setup-beam@v1
        with:
          otp-version: "27.2"
          elixir-version: "1.18.2"
      - uses: Voskan/vulncheck@v1.0.1
        with:
          fail-on: potentially_reachable
          upload-sarif: true

For untrusted pull requests (including forks), do not grant security-events: write or secrets to a job that compiles project code (compile: true, the default). Either run with compile: false against prebuilt artifacts, or run the scan unprivileged (upload-sarif: false) and publish SARIF from a separate workflow_run workflow. See SECURITY.md and docs/CONFIGURATION_AND_CI.md.


Documentation


License

Released under the MIT License. Copyright (c) 2026 Voskan Voskanyan.