BEAM Reachability Model & Soundness Guarantees

Copy Markdown View Source

A vulnerability scanner loses credibility the moment a single real production exposure is falsely hidden as "unreachable." vulncheck follows a soundness-first design tailored to Erlang/OTP, Elixir, and Gleam execution semantics.


Why Go's govulncheck Model Cannot Be Copied Verbatim to the BEAM

In statically linked languages like Go, execution starts at main.main() and package init() functions; if a function cannot be reached through static calls or interface VTA edges from main, it is dead code.

On the BEAM, four runtime mechanisms invoke functions without a direct static Mod.fun(...) call in user modules:

  1. OTP Supervision Trees & Included Applications: Adding {Bandit, plug: MyAppWeb.Endpoint} in MyApp.Application.start/2 starts a supervision subtree inside :bandit and :thousand_island via :supervisor callbacks. User code never calls Bandit.HTTP2.* directly, yet every inbound TCP/TLS packet hits those routines.
  2. Behaviours & Process Mailboxes: Calling GenServer.call(pid, msg) invokes :gen_server.call/3, which sends a message handled asynchronously by TargetServer.handle_call/3.
  3. Compile-Time Macro Expansion: plug Plug.Parsers, parsers: [:urlencoded, :json] expands into generated Plug pipeline clauses inside the compiled .beam module. Reading raw .ex source misses the generated calls; reading .beam :abstract_code sees the exact expanded parser modules!
  4. Configuration-Driven Dynamic Adapters (apply/3): Libraries like Tesla or Swoosh read an adapter module from Application.get_env/3 or module attributes and invoke apply(adapter, :call, [env, opts]).

Three-Tier Verdict Taxonomy

Every advisory matching a package version in the lockfile receives exactly one of three verdicts, each with one of thirteen reason codes. A fourth, RETIRED (reason package_retired), reports a locked release that its maintainers retired on Hex.pm (severity follows the retirement reason: security is high, invalid medium, deprecated and renamed low); it is a package lifecycle status and is excluded from SBOM vulnerabilities and VEX statements.

1. REACHABLE (High-Confidence Proof of Execution Path)

Assigned when both conditions hold:

  • The advisory specifies one or more target MFA symbols (programRoutines) or modules; and
  • There exists a directed path in the post-macro .beam + behaviour-linked call graph from a production root $r \in R$ to at least one vulnerable Module.fun/arity.

Output: vulncheck prefers confirmed traces from the project's entrypoints, then confirmed traces through a daemon or protocol client. It selects the shortest trace among matching routines within each group and breaks ties by MFA. Speculative import edges stay visible in potential traces and cannot displace a confirmed trace.

Two reason codes tell how the chain starts:

  • call_chain_proven — the chain starts at a function the project runs itself (an application start/2, a module named in the configuration, an extra_entrypoints function, or an exported function of a library).
  • daemon_call_chain — the chain starts at a protocol handler of an active network daemon (for example Bandit.HTTP2.Handler.handle_data/3), or passes through the receive function of a protocol client the project uses (for example Mint.HTTP2.stream/2). Nothing in the project calls that handler: the daemon or client calls it for data that arrives from the network, which is part of the model rather than a call written in code. Chains from the project's own entrypoints always take precedence, so this reason only appears when no such chain reaches the routine.

A chain that starts at a root the project does not call itself begins with a step 0 activation hop that says why the root is live:

Hop kindPoints toExample
daemon_activationThe project function that names the daemon module (application start/2 callbacks first), with its file:line. When the project only names a daemon that depends on the package (Bandit for thousand_island), that function is used and the note says so. Without such a reference, the .app file of the project's application whose boot tree starts the daemon.0. MyApp.Application.start/2 starts Bandit (lib/my_app/application.ex:12)
config_activationThe configuration line that names a module of a dependency, or the .vulncheck.exs file for extra_entrypoints.0. the configuration names Swoosh.Adapters.Sendgrid (config/runtime.exs:41)

A chain into a protocol client continues after the call that reaches the client with a hop of kind incoming_data: the client's receive function, with the note processes data received by the mint client.

Daemons and Protocol Clients

CategoryPackagesActive whenRoots
Serversbandit, cowboy, cowboy_telemetry, cowlib, grpc, plug_cowboy, ranch, thousand_islandThe boot tree of a project application starts the package, or project code names one of its modules (Bandit, Plug.Cowboy, GRPC.Server.Supervisor, ...).Every exported function of modules implementing the server's handler behaviours.
Cluster messagingphoenix_pubsubProject code starts Phoenix.PubSub (for example {Phoenix.PubSub, name: MyApp.PubSub} in the supervision tree). Being in the boot tree is not enough.handle_info/2 of its GenServers, which receive messages from other nodes.
Protocol clientsfinch, gun, mintA function of the client package is reachable from the project.The functions that process server responses: stream and recv of Mint.HTTP, Mint.HTTP1 and Mint.HTTP2; handle of gun_http, gun_http2 and gun_ws; connected, connected_read_only and disconnected of Finch.HTTP2.Pool.

A client the project does not reach is evaluated like any other dependency: otp_app_not_started when nothing starts or references it, adapter_not_configured when it is an unconfigured adapter of Tesla, Swoosh or Req.

2. POTENTIALLY_REACHABLE (Conservative Soundness Boundary)

Assigned when static non-reachability cannot be proven safely:

  • Network / Runtime Daemon Exposure: The vulnerable package is an active server in the production application tree (see the table above) and the vulnerable module belongs to its active protocol stack.
  • Unresolved Dynamic Dispatch: A reachable module invokes apply(mod_var, fun_var, args) where target module/function candidates cannot be narrowed away from the vulnerable module, and the vulnerable dependency's OTP application is loaded in :prod. A dynamic call can only name a module whose atom reaches it: one written in reachable code or configuration, one built with Module.concat/1,2 or Module.safe_concat/1,2 anywhere in reachable code (outside modules whose dynamic calls a framework rule resolves, such as Plug.Parsers), or one converted from a string (String.to_atom/1, :erlang.binary_to_atom/2, ...) in the module that makes the call. Each such call site that keeps advisories open is listed in the report warnings. Calls whose arguments are an open list (apply(m, f, [env | rest])) only match functions with at least the known number of arguments. Framework dispatch through a module held in a variable is resolved when the framework only ever calls implementations of its own behaviour (ThousandIsland transports, Mint connections and transports) or entries of literal configuration (the Plug.Parsers body reader and decoder, the Tesla middleware stack).

  • Function Values: Direct calls through a function value and apply(fun, args) use an exact edge when the capture and arity are known. A function value whose origin is not known at the call (callback.(), fun.(conn, data)) does not keep advisories open. Every function value is created by analyzed code. A capture (&Mod.fun/2, fun mod:f/1) is already an edge of the function that takes it, and the body of an anonymous function is part of the function that defines it. Captures built from atoms at runtime (:erlang.make_fun(mod, fun, arity), Function.capture/3) are dynamic calls in their own right and follow the rules above. Modules without debug info are covered by incomplete compiled evidence. Unknown selections among exports of a known module are emitted as dynamic_candidate trace hops. Confirmed alternatives override these candidates.
  • Missing Symbol Granularity: An upstream advisory lacks programRoutines and module-level hints, and at least one function in the vulnerable package is reachable in :prod.
  • Incomplete Compiled Evidence: Absent or unreadable BEAM files, stripped debug info, missing boot application metadata and dependency versions inconsistent with the lock can prevent a negative verdict. An issue in a dependency applies to that package and its recorded dependency closure. An issue in a project application can affect the whole scan. A fallback build profile also prevents negative code verdicts. The compiler's default rebar3 profile is treated as native to rebar3 projects.

The native JSON report records the build profile, issues and analysis status under analysis. The status can be complete, partial, unsuitable for a fallback profile, unavailable when no BEAM could be analyzed, or not_needed when no advisory required code analysis. The default CI policy, --fail-on potentially_reachable, fails for active matches carried by incomplete evidence, subject to the configured minimum severity and suppressions. An explicit non-production scope or an excluded OTP version can still establish a negative verdict independently of BEAM evidence.

3. UNREACHABLE (Proven Safe to Suppress in Production)

Assigned only when vulncheck establishes a concrete, auditable proof of non-execution, tagged with one of six deterministic reasons:

Reason CodeProof ConditionReal-World Example
non_prod_dependencyPackage is outside the :prod runtime closure (only: [:dev, :test]) or build-time only (runtime: false, see below).CVE in meck or ex_doc.
otp_version_unaffectedAdvisory explicitly restricts the vulnerability to an OTP release range that excludes the target runtime (--otp-version or the running VM).EEF-CVE-2026-103502 (hex_core on OTP $\le$ 25 when running on OTP 27).
otp_app_not_startedTransitive dependency is neither in the :prod release boot tree nor referenced by any reachable module/config.Unused transitive HTTP client pulled as optional dep.
adapter_not_configuredPackage is an optional adapter (Tesla.Adapter.Hackney, Swoosh.Adapters.*) and neither project config nor .beam constants reference that adapter module.hackney advisories when Tesla is configured with Tesla.Adapter.Mint or Tesla.Adapter.Finch.
module_not_loadedAdvisory specifies affected modules (modules / programRoutines), no dynamic apply/3 escapes toward the package, and zero functions in the affected module are reachable.Plug.Parsers.MULTIPART CVE when Plug.Parsers is compiled with parsers: [:json] only.
function_not_calledAdvisory specifies exact programRoutines MFAs, .beam debug chunks are intact across the call boundary, no unresolved apply/3 targets the module, and none of the vulnerable MFAs appear in the reachable closure.Ash.count/2 (Ash.Actions.Aggregate.run/4) CVE when app only uses Ash.read/2 and Ash.create/2.

Build-Time Dependencies (runtime: false)

A Mix dependency declared with runtime: false ({:credo, "~> 1.7", runtime: false}, from Hex, Git or a path) runs while the project compiles, and is neither started as an OTP application nor shipped in the release. The package and every package that only it depends on get scope build_only; a package that some runtime dependency also needs stays prod. If reachable code directly calls a module of a build_only package, that direct call chain still reports REACHABLE; otherwise advisories of build-time packages are UNREACHABLE with reason non_prod_dependency and the detail build-time only (runtime: false). OpenVEX reports them as not_affected with vulnerable_code_not_in_execute_path (the code is not executed in production), CycloneDX as code_not_reachable, and JSON as package_scope: "build_only". Git dependencies whose advisory applicability cannot be proven from a commit hash or upstream SemVer tag additionally carry git_match_status: "uncertain".

Severity Is Independent of Reachability

The verdict says whether vulnerable code can run. The severity is the advisory's CVSS score: the score of the CNA record when there is one, else one computed from the CVSS v4.0 or v3.x vector of the OSV record (see docs/OUTPUT_FORMATS.md). Offline scans and mix vulncheck.explain therefore report a severity for every advisory that carries a vector.

Routines Outside the Vulnerable Package

CVE records sometimes list functions on the vulnerable path that are not part of the vulnerable package: standard library calls such as List.delete/2 or Enum.map_join/3, or functions of another dependency. Those are reachable in almost any project, so a path to them proves nothing about the package. vulncheck keeps only the routines and modules of the vulnerable package as targets (a module counts as part of the package when its compiled .beam belongs to the package, or when no compiled module of that name exists and it does not ship with Erlang/OTP or Elixir). The rest are reported as context_routines. When an advisory names only routines outside the package, it is evaluated at package level and function_not_called is never concluded from it.


Handling NIFs and Erlang Modules

  • Erlang Dependencies (:cowlib, :hackney, :gun, :jose): Because Erlang and Elixir compile to the same .beam abstract_code format, vulncheck traverses mixed Elixir -> Erlang -> Elixir call chains seamlessly without language bridges.
  • Native Implemented Functions (NIFs): When an advisory targets a Rustler or C NIF stub (:erlang.load_nif/2), the Elixir/Erlang wrapper MFA in the host module serves as the reachability sink in the .beam call graph.