doc/user/application_security/dependency_scanning/static_reachability.md
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Dependency scanning identifies all vulnerable dependencies in your project. However, not all vulnerabilities pose equal risk. Static reachability analysis helps you prioritize remediation by determining which vulnerable packages are reachable, meaning they are imported by your application. By focusing on reachable vulnerabilities, static reachability analysis enables you to prioritize remediation based on actual threat exposure rather than theoretical risk.
Static reachability analysis works by analyzing your project's source code to determine which dependencies from your SBOM are reachable. Dependency scanning generates an SBOM report that identifies all components and their transitive dependencies. Static reachability analysis then checks each dependency in the SBOM and adds a reachability value, enriching the report with actual usage data. This enriched SBOM is then ingested by GitLab to supplement vulnerability findings.
An SBOM is enriched only when both the SBOM file and source code files belong to the same project directory tree. When multiple nested projects exist, the system selects the closest (deepest) project path to determine enrichment. static reachability analysis relies on metadata that maps package names from SBOMs to their corresponding code import paths for Python and Java packages. This metadata is maintained with weekly updates.
[!warning] Static reachability analysis is production-ready. However, it has limited availability because it depends on dependency scanning by SBOM, which has the same status.
Share feedback in issue 535498.
Prerequisites:
History above).build stage. See the
instructions for pip or
pipenv. For other supported Python package
managers, see the
dependency scanning analyzer documentation.[!warning] Static reachability analysis increases job duration.
To turn on static reachability analysis in your project:
In the top bar, select Search or go to and find your project.
Select Code > Repository.
Select the .gitlab-ci.yml file.
Select Edit > Edit single file.
Add the following configuration:
include:
- template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml
variables:
DS_STATIC_REACHABILITY_ENABLED: true
Select Commit changes.
When dependency scanning runs and outputs an SBOM, the results are supplemented by static reachability analysis.
A dependency can have one of the following reachability values. Prioritize triage and remediation of dependencies marked as Yes, because these are confirmed to be used in your code.
Yes : The package linked to this vulnerability is confirmed reachable in code. When a direct dependency is marked as reachable, its transitive dependencies are also marked as reachable.
Not Found : Static reachability analysis ran successfully but did not detect usage of the vulnerable package.
Not Available : Static reachability analysis was not executed, so no reachability data exists.
To find the reachability value for a vulnerable dependency:
A Not Found reachability value doesn't guarantee the dependency is unused, because static reachability analysis cannot always definitively determine package usage.
Dependencies are marked as not found when:
DS_EXCLUDED_PATHS).Consider the following example of an excluded directory. You have defined the CI/CD variable
DS_EXCLUDED_PATHS="test". The project's repository structure is as follows.
.
├── pipdeptree.json // contains "requests" dependency
└── test/
└── app.py // imports "requests" dependency
In this example, the graph file pipdeptree.json is outside the excluded directory and is analyzed
to identify the dependencies listed in the file. However, the source code that imports the
requests dependency is in an excluded directory, so static reachability analysis doesn't check its
reachability. As a result, the requests dependency is labeled as Not found. In other words,
this occurs when the lockfile is outside the excluded directory but the code that imports the
dependency is inside it.
Support varies by language maturity and includes specific package managers and file types for each language.
| Language | Maturity | Supported package managers | Supported file types |
|---|---|---|---|
| Python<sup>1</sup> | Beta | pip, pipenv<sup>2</sup>, poetry, uv | .py |
| JavaScript/TypeScript<sup>3</sup> | Beta | npm, pnpm, yarn | .js, .ts |
| Java<sup>4</sup> | Beta | maven<sup>5</sup>, gradle<sup>6</sup> | .java |
Footnotes:
pipdeptree,
optional dependencies
are marked as direct dependencies instead of as transitive dependencies. Static reachability
analysis might not identify those packages as in use. For example, requiring passlib[bcrypt]
may result in passlib being marked as in_use and bcrypt is marked as not_found. For more
details, see pip.pipenv, static reachability analysis doesn't support Pipfile.lock files. Support
is available only for pipenv.graph.json because it supports a dependency graph.maven.graph.json files as described in the
Maven instructions.To run static reachability analysis in an offline environment, you must do an initial setup and perform ongoing maintenance.
Initial setup:
Ongoing maintenance:
For Python and Java packages, static reachability analysis uses metadata to map package names from SBOMs to their corresponding code import paths. This metadata is contained in the dependency scanning analyzer's image. Outdated metadata may result in incomplete or inaccurate reachability analysis.