Reachability

Experimental. Reachability is opt-in (--analyze) and still maturing. The output shape is stable, but ecosystem coverage is growing. The JavaScript, Python, and JVM analyzers work at package precision: they confirm that your code imports the vulnerable package, not that it calls the vulnerable function. Read Unreachable is not safe before you gate CI on it.

Reachability answers one question per vulnerability: can the scanned project reach the vulnerable code at all? Use it to stop chasing high-severity advisories in transitive packages your code never imports. This page explains what the analyzers check, what the results mean, and where they appear.

Quick start

--analyze requires --enrich, because it annotates the vulnerabilities enrichment found:

# Annotate vulnerabilities with reachability
bomly scan --enrich --analyze --json

# Fail only when a finding is both low-or-higher severity and confirmed reachable
bomly scan --enrich --audit --analyze --fail-on low --fail-on reachable

What each analyzer checks

Each analyzer handles one language and reports at one level of precision, called a tier.

On a project with no applicable analyzer, the scan runs normally and every vulnerability keeps an empty reachability result.

The tiers, from strongest to weakest:

Each analyzer reports one of three statuses per vulnerability, or leaves it empty when the vulnerability is outside its scope:

Analyzer failures never stop a scan. A missing toolchain, a broken build, or a cancelled run becomes unknown with a machine-readable reason such as missing-toolchain or build-failed.

Unreachable is not safe

This is the most important thing to know before you gate CI on --fail-on reachable. Static analysis cannot see:

• Dynamic imports: require(userInput), importlib.import_module(name), Class.forName(string), conditional __import__.
• Runtime loaders: plugin systems, Python entry points, Django INSTALLED_APPS strings, Spring component scanning, ServiceLoader, OSGi, JPMS layers, reflection.
• Generated or external code: annotation processors, build-time code generators, shell commands.

A package-tier unreachable says "the application does not import this package". That is useful for deprioritizing dev-only and unused transitive dependencies. It is not evidence that the vulnerability is mitigated. The Go symbol tier is much stronger, because govulncheck builds the real call graph, but even it cannot see reflection.

When an analyzer sees dynamic-import constructs in your source, it sets dynamic_imports_detected to true and lowers the confidence of its results, so you can tell from the output when an unreachable verdict is incomplete.

Package-tier analysis in brief

jsreach, pyreach, and jvmreach all work the same way. They scan application source for import statements to build the set of directly imported packages, then expand that set through the dependency graph the detector resolved. Any package reachable from the imported set is reachable; everything else, such as a dev dependency no source file imports, is unreachable.

Three consequences follow for all three:

• Imports of a subpath count for the whole package. Importing lodash/get marks all of lodash reachable, even if an advisory affects only lodash/template.
• The result is only as good as the lockfile or build manifest. A package installed locally but never recorded, or a dependency the build tool did not report, cannot be reached.
• Python and JVM imports must be mapped to package names. import yaml means the PyYAML distribution, and org.apache.commons covers many Maven artifacts. Both analyzers use curated maps for the well-known cases, so a missing entry can produce a false unreachable for a direct import. If you find one, open an issue naming the import and the package; additions are quick to ship.

The per-analyzer details, including the override maps and workspace handling, are in the reachability internals for contributors.

Gating on reachability

--fail-on is repeatable, and the vulnerability constraints must all match (they combine with AND). An empty reachability result, meaning no analyzer ran on that vulnerability, never matches reachable: the analyzer must have confirmed it.

bomly scan --enrich --audit --fail-on low                                   # severity only
bomly scan --enrich --audit --analyze --fail-on low --fail-on reachable      # severity AND reachable

The full list of --fail-on values, including exploitable, is on the Auditors page.

Where the results appear

confidence is high for a direct import with no dynamic imports seen, medium for one to three hops, and low for four or more hops or when dynamic imports were seen.

Selecting analyzers

--analyzers uses the same selector grammar as the other component flags:

bomly scan --enrich --analyze --analyzers govulncheck            # only govulncheck
bomly scan --enrich --analyze --analyzers -govulncheck           # everything except govulncheck
bomly scan --enrich --analyze --analyzers govulncheck,jsreach    # these two

External analyzer plugins join the same selector once installed and enabled. See Plugins and How to implement an analyzer plugin.

Limitations

govulncheck reason codes when the build fails:

See also

• Auditors — every --fail-on value and how they combine
• JSON schemas — the full reachability object
• How to implement an analyzer plugin — add an analyzer for another language