Skip to content

Static reachability analysis

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
  • Status: Beta

Version history

Static reachability analysis (SRA) helps you prioritize remediation of vulnerabilities in dependencies.

An application is generally deployed with many dependencies. Dependency scanning identifies which of those dependencies have vulnerabilities. However, not all dependencies are used by an application. Static reachability analysis identifies those dependencies that are used, in other words reachable, and so are a higher security risk than others. Use this information to help prioritize remediation of vulnerabilities according to risk.

To identify vulnerable dependencies that are reachable, either:

  • Hover over the Severity value of a vulnerability in the vulnerability report.
  • Check the Reachable value in the vulnerability page.
  • Use a GraphQL query to list those vulnerabilities that are reachable.

Supported languages and package managers

Static reachability analysis is available only for Python projects. SRA uses the new dependency scanning analyzer to generate SBOMs and so supports the same package managers as the analyzer.

Language Supported Package Managers
Python pip, pipenv, poetry, uv

Enable static reachability analysis

Enable static reachability analysis to identify high-risk dependencies.

Prerequisites:

To enable static reachability analysis from GitLab 18.0 and later:

  • Set the CI/CD variable DS_STATIC_REACHABILITY_ENABLED to true

Static reachability is integrated into the dependency-scanning job of the latest Dependency-Scanning template. Alternatively you can enable Static Reachability by including the Dependency Scanning component rather than using the standard Dependency-Scanning template.

include:
  - component: ${CI_SERVER_FQDN}/components/dependency-scanning/main@0
    inputs:
      enable_static_reachability: true
    rules:
      - if: $CI_SERVER_HOST == "gitlab.com"

Please notice that to use GitLab.com components on a GitLab Self-Managed instance, you must mirror the component project.

Static reachability analysis functionality is supported in Dependency Scanning analyzer version 0.23.0 and all subsequent versions.

If you are using GitLab 17.11 follow these instructions to enable Static Reachability Analysis
  • Make sure you extend dependency-scanning-with-reachability needs section to depend on the build job that creates the artifact required by the DS analyzer.
stages:
  - build
  - test

include:
  - template: Jobs/Dependency-Scanning.latest.gitlab-ci.yml

variables:
  DS_STATIC_REACHABILITY_ENABLED: true
  DS_ENFORCE_NEW_ANALYZER: true

# create job required by the DS analyzer to create pipdeptree.json
# https://docs.gitlab.com/user/application_security/dependency_scanning/dependency_scanning_sbom/#pip
create:
  stage: build
  image: "python:latest"
  script:
    - "pip install -r requirements.txt"
    - "pip install pipdeptree"
    - "pipdeptree --json > pipdeptree.json"
  artifacts:
    when: on_success
    access: developer
    paths: ["**/pipdeptree.json"]

dependency-scanning-with-reachability:
  needs:
    - job: gitlab-static-reachability
      optional: true
      artifacts: true
    - job: create
      optional: true
      artifacts: true

Static reachability in 17.11 introduces two key jobs:

  • gitlab-static-reachability: Performs Static Reachability Analysis (SRA) on your Python files.
  • dependency-scanning-with-reachability: Executes dependency scanning and generates an SBOM report enriched with reachability data. This job requires the artifact output from the gitlab-static-reachability job.

When you enable static reachability feature for non-Python projects, the gitlab-static-reachability job will fail but won't break your pipeline, because it's configured to allow failures. In such cases, the dependency-scanning-with-reachability job will perform standard dependency scanning without adding reachability data to the SBOM.

How static reachability analysis works

SRA (Static reachability analysis) identifies dependencies used in a project's code and marks them and their dependencies as reachable.

The following are marked as not found:

  • Dependencies that are found in the project's lock files but are not imported in the code.
  • Tools that are included in the project's lock files for local usage but are not imported in the code. For example, tools such as coverage testing or linting packages are marked as not found even if used locally.

SRA requires two key components:

  • Dependency scanning (DS): Generates an SBOM report that identifies all components and their transitive dependencies.
  • GitLab Advanced SAST (GLAS): Performs static reachability analysis to provide a report showing direct dependencies usage in the codebase.

SRA adds reachability data to the SBOM output by dependency scanning. The enriched SBOM is then ingested by the GitLab instance.

Reachability data in the UI can have one of the following values:

Reachability values Description
Yes The package linked to this vulnerability is confirmed reachable in code
Not Found SRA ran successfully but did not detect usage of the vulnerable package
Not Available SRA was not executed, therefore no reachability data exists

Where to find the reachability data

The reachability data is available in the vulnerability report

Reachability on the vulnerability report

and the vulnerability page

Reachability on the vulnerability page

Finally reachability data can be reached using GraphQL.

When a vulnerability reachability value shows as "Not Found," exercise caution rather than completely dismissing it, because the beta version of SRA may produce false negatives.

Restrictions

Static reachability analysis has the following limitations:

  • When a direct dependency is marked as in use, all its transitive dependencies are also marked as in use.
  • Requires the new dependency scanning analyzer. Gemnasium analyzers are not supported.
  • SRA on beta is not supported in combination with Scan and Pipeline execution policies