Analyzing projects for dependencies (SCA)
SonarQube Server 2026.5 can analyze your projects for dependencies and identify dependency risks. You can also import SBOM files to analyze containers.
Advanced Security is available in SonarQube Server as a paid product starting in Enterprise edition.
With Software Composition Analysis (SCA), SonarQube analyzes your built project and returns information on:
vulnerabilities in your third-party open source dependencies
where your open source dependencies may conflict with your organization’s license policies
Here are things to check out for to ensure that you get fast and accurate dependency analysis.
Enabling the SCA service
By default, SCA is not enabled on your instance. To turn on the Sonar SCA service as an admin:
Make sure your SonarQube Server license includes Advanced Security.
Go to Administration > Configuration > General Settings > Advanced Security and select Enable Software Composition analysis (SCA).
You can choose whether all projects will be scanned using SCA by default, by adjusting the Analyze all projects toggle. If you disable dependency analysis by default, you will need to enable analysis on a project-by-project basis at the scanner level by passing sonar.sca.enabled=true as a scanner parameter.
A connectivity test is available after SCA is enabled to test your Internet access.
Internet connection
Detecting and remediating third-party vulnerabilities requires a constantly updated source of data. New vulnerabilities are discovered every day, and new releases of software that fix them soon follow. Sonar’s researchers are constantly checking to ensure that our license data is accurate, and for details on how reported vulnerabilities may actually affect your code.
As a result, an internet connection is required to always provide the most up-to-date information on your third-party dependencies, including:
what licenses you have
what issues you are affected by
what workarounds maintainers have published as being available
Your SonarQube Server instance must be able to reach the following servers:
See List of properties common to all editions for more information about configuring system properties and environment variables.
You can use the connectivity check under Administration > Configuration > General Settings > Advanced Security to test your network access.
What data is collected
Whenever you run an analysis, the Sonar scanner collects the manifests of your projects. Manifests are language-specific files that define your projects’ dependencies, such as pom.xml for Java, or requirements.txt for Python. The scanner also collects any relevant lockfiles that describe the fully-resolved set of dependencies, such as package-lock.json for a JavaScript project. These manifests and lockfiles are assembled into an archive file and sent to the SonarQube server.
Controlling data processing via analysis mode
How this data is processed is based on your analysis mode, configured in your Advanced Security settings. Analysis mode has one of two settings:
Local parsing (default)
SonarQube Server processes the manifests and lockfiles to generate a list of dependencies. SonarQube Server then queries a cloud service operated by Sonar for license and vulnerability information for these dependencies. All queries are sent over a secure HTTPS connection.
Your manifests, lockfiles, and source code never leave your SonarQube environment. Query information is not stored by Sonar.
Cloud (optional)
The full archive, including any manifests and lockfiles, is sent to a cloud service operated by Sonar for analysis. All data is sent over a secure HTTPS connection. Manifests and lockfiles are not stored persistently in Sonar. Information on your dependencies and their issues is returned to your SonarQube Server instance. No source code is sent to Sonar.
Choose 'cloud' mode if you need to opt into parsing bugfixes not yet available in your SonarQube Server release.
Supported languages and package managers
SonarQube evaluates your third-party open source code usage by matching dependencies defined in your project’s dependency files to known open source code on upstream package managers. It currently supports the following languages, package managers, and package manager files:
Language
Package manager /Build tool
Package repository
Manifest file names
Lock file names
Reachability supported
JavaScript
NPM
Yarn
PNPM
Bun
package.json
package-lock.json
npm-shrinkwrap.json
yarn.lock
pnpm-lock.yaml
bun.lock
C#
NuGet
.csproj
Project.json
.nuspec
packages.lock.json
project.assets.json
Project.lock.json
paket.lock
✓
VB.NET
NuGet
.vbproj
Project.json
.nuspec
packages.lock.json
project.assets.json
Project.lock.json
paket.lock
✓
Generic SBOM (CycloneDX)
N/A
N/A
cyclonedx.json
cyclonedx.xml
.cdx.json
.cdx.xml
N/A
Generic SBOM (SPDX)
N/A
N/A
.spdx
.spdx.json
N/A
Ensure the analysis is run in an appropriate environment
To correctly analyze both your direct and transitive dependencies on projects where there is not a lockfile that contains all dependencies, SonarQube executes commands using your build tools to get a full dependency list.
Note on security
To run a dependency analysis, the SonarQube scanner might install the dependencies required to build your application. This could pull in untrusted artifacts, similar to while you’re building the application. Ensure the analysis will run in a secure environment before proceeding.
Notes on specific build tools and language ecosystems
Maven
The Maven binary (mvn) or maven wrapper (mvnw) must be located in the project directory, the manifest file’s directory, or in the execution path.
Gradle
The Gradle binary (gradle) or Gradle wrapper (gradlew) must be in the project directory, the manifest file’s directory, or in the execution path.
pip
The analysis must be run with the same Python runtime that your application is built on. The SonarQube analysis will create a virtual environment to resolve dependencies, and a C compiler and development libraries may be required, based on your python dependencies.
Go
The go runtime that matches the version in go.mod must be present.
Internal artifact repositories
If your application build configuration includes internal or private artifacts, the analysis process must have network access to your artifact server.
If the analysis is not run in the proper environment, it will cause degraded analysis results and potential analysis failures. You can see more information in analysis warnings in the UI and in the scanner log. See the Troubleshooting section for some common scenarios.
Note on pull request analysis
To get valuable results when performing a pull request analysis, the target branch should have been analyzed first.
Ensure the analysis includes the appropriate files
The SCA analysis recursively searches for appropriate package files for your project. In some cases, this may analyze more files than what your project actually uses. Common cases to look out for include:
Package manager files in test code and data directories
If you have package manager files present in test directories, ensure these locations are properly excluded from analysis. This can be done in multiple ways:
Add paths to the common
sonar.exclusionsconfiguration option. Example:sonar.exclusions="tests/**"Use the specific
sonar.sca.exclusionsconfiguration option. Examplesonar.sca.exclusions="tests/**"As long as SonarQube's SCM support is enabled (the default), add the paths to a source control ignore file, such as
.gitignore
Customizing the dependency analysis
The following parameters influence the results of the dependency analysis.
sonar.sca.enabled
Boolean
true
Indicates whether to perform Software Composition Analysis (SCA) on this project. Set it to false to disable SCA for this project.
sonar.sca.exclusions
String
A comma-separated list of global patterns of paths to exclude as part of analysis.
For example, to ignore all manifests under the tests/ and fixtures/ directories, set:
sonar.sca.exclusions = "tests/, fixtures/"
sonar.sca.allowManifestFailures
Boolean
true
When performing analysis, SonarQube attempts to run your build tools (such as Maven or Gradle) to create a full dependency graph.
By default, SonarQube does not fail the analysis if these tools fail, and returns information on a limited set of dependencies. Set this parameter to false to force a failure in this scenario.
sonar.sca.goNoResolve
Boolean
false
Disables automatic generation of a Go lock file. This results in degraded dependency information.
sonar.sca.mavenNoResolve
Boolean
false
Disables automatic generation of a Maven lock file and dependency graph file.
This results in degraded dependency information.
sonar.sca.mavenForceDepPlugin
Boolean
true
Ensures Maven Dependency Plugin is installed even when it’s not available in the environment.
sonar.sca.mavenIgnoreWrapper
Boolean
false
Disables a search for a Maven wrapper script mvnw. Set this to true if the default Maven wrapper in your PATH is not functioning.
sonar.sca.mavenOptions
String
Sends additional options to any Maven commands used to generate the lock file and dependency graph file.
sonar.sca.gradleNoResolve
Boolean
false
Disables automatic generation of a Gradle dependencies lock file. This results in degraded dependency information.
sonar.sca.gradleConfigurationPattern
String
Java regex of configurations to include. This is passed to gradle via -PconfigurationPattern. When unset, all configurations will be resolved.
sonar.sca.pythonBinary
String
/usr/bin/python
Path to a specific Python binary that should be used if lock files need to be generated.
sonar.sca.pythonNoResolve
Boolean
false
Disables automatic generation of a Python lock file. This results in degraded dependency information.
sonar.sca.pythonResolveLocal
Boolean
false
When generating a python lockfile, dependency resolution is done in a temporary virtual environment. Set this to true to skip creation of the virtual environment and resolve against the local python environment.
sonar.sca.npmNoResolve
Boolean
false
Disables automatic generation of a lock file for an NPM project when a supported lockfile (yarn.lock, package-lock.json, pnpm-lock.yaml, bun.lock) is not present.
sonar.sca.npmEnableScripts
Boolean
false
By default, when generating a lockfile, the --ignore-scripts NPM/Yarn option is passed to ignore any lifecycle scripts. If lifecycle scripts are needed to properly generate dependencies, enable this option.
sonar.sca.nugetNoResolve
Boolean
false
Disables automatic generation of a lock file for a Nuget project.
sonar.scanner.keepReport
Boolean
false
Not specific to SCA. Keeps the scanner work directory after analysis, including the dependency-files.tar.xz that contains dependency files to analyze. Useful if you have access to commercial support, as the Sonar support team may ask for this file to assist with resolving issues.
sonar.sca.cfamily
Boolean
false
When set to true, enables support for C/C++ dependency analysis (beta)
sonar.sca.sbomImportPaths
String
Comma-separated list of SBOM files to import and analyze. See “Supported languages and package managers” for supported file types and required file naming.
Import SBOM files to analyze containers
You can use the Software Bill of Materials (SBOM) import feature of SonarQube Advanced Security to analyze a container image.
Generate an SBOM of the container. Several freely available tools can do this. For example, given a potential
test/examplecontainer, version 1.2:Using Syft
To generate the SBOM of the container using Syft:
Using CycloneDX Generator
To generate the SBOM of the container using CycloneDX Generator:
Use the SBOM import feature to analyze the resulting SBOM by passing the following in
sonar-project.propertiesor on the scanner command line:
SBOM import requirements
SonarQube Advanced Security has specific requirements for imported Software Bills of Materials.
SBOMs imported into SonarQube must:
Be in the CycloneDX (JSON or XML) or SPDX (JSON or plaintext) formats
Be appropriately named (cyclonedx.xml, cyclonedx.json, *.cdx.json, *.spdx, *.spdx.json)
Contain dependency entries ('components' in CycloneDX, 'packages' in SPDX) that reference items in the Package URL format
Identification of items by CPE is not currently supported.
For operating system (Linux) vulnerabilities, they will be returned for the following Linux distributions:
Red Hat Enterprise Linux
Debian (11 and higher)
Rocky Linux
AlmaLinux
Ubuntu
Alpine
Downstream or vendor packages may return inconsistent results for vulnerabilities.
Continual analysis
Once SCA analysis has been performed on a permanent branch, Sonar automatically re-analyzes your branch for new dependency risks. This analysis runs once per day. Any newly discovered vulnerability or license risks will be added to the list of dependency risks for your project, any changes to risk factors and scoring will cause any needed severity updates, and any quality gate will be recomputed. For more information on project branches, see Maintaining project branches.
You can change how often your branches are re-analyzed and disable re-analysis from the SonarQube Server UI. To do this, go to Administration > Configuration > Advanced Security > Configure Branch Rescanning.
From there, you can set the following:
Branch rescan frequency: Daily, weekly, or never
Branch rescan target branch types: Main branch only, kept branches only, or all branches
You can see the last analysis or reanalysis time on the Dependency Risks screen. If you have the Administer projects permission, you can also trigger a manual reanalysis from that screen.
Troubleshooting the dependency analysis
See Troubleshooting the dependency analysis for guidance on how to troubleshoot the dependency analysis.
Related pages
Related online learning
Last updated
Was this helpful?