Start Free
Latest | Advanced security | Analyzing projects for dependencies (SCA)

Analyzing projects for dependencies (SCA)

On this page

Advanced Security is only available in SonarQube Server, as an add-on 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: 

  1. Make sure your SonarQube Server license includes Advanced Security.
  2. Go to Administration > Configuration > General Settings > Advanced Security and activate the Software Composition analysis (SCA) option.

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:

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, data is sent to a Sonar cloud service for 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 a zip file and sent to a Sonar cloud service for analysis. All data is sent over a secure HTTPS connection. Information on your dependencies and their issues is returned to your SonarQube Server instance. No source code is sent to Sonar. 

Manifests and lockfiles are not stored persistently in Sonar. Sonar may collect aggregate data, and other service telemetry on open source package usage in an anonymized way.

The manifest and lockfiles that are processed contain a list of all dependencies of your project, which could include internally-developed library names. The Sonar service compares dependency names against a set of known open source components; any internally-developed library name would not match, and therefore would not have any license or vulnerability data returned for that library.

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: 

LanguagePackage manager
/Build tool
Package repositoryManifest file namesLock file names
JavaMavenMaven Central
pom.xmlGenerated at the time of analysis
JavaGradleMaven Central
  • build.gradle
  • build.gradle.kts
Generated at the time of analysis
JavaScriptNPMNPMpackage.json
  • package-lock.json
  • npm-shrinkwrap.json
JavaScriptYarnNPMpackage.jsonyarn.lock
JavaScriptPNPMNPMpackage.jsonpnpm-lock.yaml
JavaScriptBunNPMpackage.jsonbun.lock
KotlinMavenMaven Centralpom.xmlGenerated at the time of analysis
KotlinGradleMaven Central
  • build.gradle
  • build.gradle.kts
Generated at the time of analysis
PythonPipPyPIrequirements.txtGenerated at the time of analysis
PythonPipenvPyPIPipfilePipfile.lock
PythonPoetryPyPIpyproject.tomlpoetry.lock
ScalaMavenMaven Centralpom.xmlGenerated at the time of analysis
ScalaGradleMaven Centralbuild.gradleGenerated at the time of analysis
Golanggopkg.go.devgo.modGenerated at the time of analysis
C# / .NET CoreNuGetNuGet Gallery
  • *.csproj
  • Project.json
  • *.nuspec
  • packages.lock.json
  • project.assets.json
  • Project.lock.json
    paket.lock
C# / .NET Framework.
Only direct dependencies
are analyzed.
NuGetNuGet Gallery
*.csprojNot supported 
RubyRubygemsRubygemsGemfileGemfile.lock
RustCargoCrates.ioCargo.tomlCargo.lock

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, SonarQube Server might install on its host system all 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 Troubleshooting for some common scenarios.

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.exclusions configuration option. Example: sonar.exclusions=“tests/**”
  • Use the specific sonar.sca.exclusions configuration option. Example sonar.sca.exclusions=“tests/**”
  • As long as SonarQubes 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.

ParameterTypeDefaultDescription
sonar.sca.enabledBooleantrueIndicates whether to perform Software Composition Analysis (SCA) on this project. Set it to false to disable SCA for this project.
sonar.sca.exclusionsString

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.allowManifestFailuresBooleantrue

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.goNoResolveBooleanfalseDisables automatic generation of a Go lock file. This results in degraded dependency information.
sonar.sca.mavenNoResolveBooleanfalse

Disables automatic generation of a Maven lock file and dependency graph file.

This results in degraded dependency information.

sonar.sca.mavenForceDepPluginBooleantrueEnsures Maven Dependency Plugin is installed even when it’s not available in the environment.
sonar.sca.mavenIgnoreWrapperBooleanfalseDisables 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.mavenOptionsString
Sends additional options to any Maven commands used to generate the lock file and dependency graph file.
sonar.sca.gradleNoResolveBooleanfalseDisables automatic generation of a Gradle dependencies lock file. This results in degraded dependency information.
sonar.sca.gradleConfigurationPatternString
Java regex of configurations to include. This is passed to gradle via -PconfigurationPattern. When unset, all configurations will be resolved.
sonar.sca.pythonBinaryString/usr/bin/pythonPath to a specific Python binary that should be used if lock files need to be generated.
sonar.sca.pythonNoResolveBooleanfalseDisables automatic generation of a Python lock file. This results in degraded dependency information.
sonar.sca.pythonResolveLocalBooleanfalseWhen 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.npmNoResolveBooleanfalseDisables automatic generation of a lock file for an NPM project when a supported lockfile (yarn.lockpackage-lock.json, pnpm-lock.yaml, bun.lock) is not present.
sonar.sca.npmEnableScriptsBooleanfalseBy 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.nugetNoResolveBooleanfalseDisables automatic generation of a lock file for a Nuget project.
sonar.scanner.keepReportBooleanfalseNot specific to SCA. Keeps the scanner work directory after analysis, including the dependency-files.zip 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.

Setting up scheduled analyses for SCA

In the initial release of SonarQube Advanced Security, all vulnerabilities and detected licenses are evaluated at analysis time. 

While a future SonarQube release will automatically scan periodically for new vulnerabilities and updated licenses, at the moment a new analysis must be performed to discover newly discovered or newly public vulnerabilities on existing code. 

The easiest way to do this is via the use of scheduled analysis from your DevOps platform. Here is how to set it up for a number of common DevOps platforms.

GitHub

If you are using GitHub actions using the SonarSource/sonarqube-scan-action to perform SonarQube analysis, here is how to to enable an analysis on a periodic basis.

A normal GitHub action workflow may look like this:

name: Run SonarQube analysis

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened]

To add scheduled analysis, just add a schedule section:

name: Run SonarQube analysis

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened]
  schedule:
cron: ‘23 4 * * *‘ 

This schedules a daily analysis at 4:23AM UTC. If daily is too often, you can configure weekly or monthly as well.

For more information, see the GitHub documentation.

GitLab

If you are using GitLab pipelines to perform SonarQube analyis, you can use them to schedule analysis to run on a periodic basis. To configure scheduled runs for your GitLab pipeline: 

  1.  Go to Build > Schedule pipelines for your project and click Create a new pipeline schedule.
  2. Enter:
    • A name for the schedule
    • The desired timezone to interpret the schedule in
    • A crontab-style interval. For example ‘11 7 * * *‘ runs the pipeline at 7:11AM in the configured timezone

You can create multiple schedules to run on multiple branches.

For more information, see the GitLab documentation.

Jenkins

If you are using Jenkins pipelines to perform SonarQube analysis, you can use them to configure periodic analysis:

Go to your job configuration, and click the Build triggers tab. Enable the checkbox for Build periodically.  You can then configure how often to run the analysis by entering a schedule specification in the Schedule box.

For example, to do a daily scan (which will run at an arbitrary, but consistent, time during the day), enter @daily, or ‘H H * * *’.

This can also be configured in the pipeline definition itself. An example daily configuration would be:

triggers { cron('H H * * *') }

For more information see the Jenkins documentation on triggers.

BitBucket

If you are using BitBucket pipelines to perform SonarQube analysis, you can use them to configure periodic analysis:

  1. Go to the repository in BitBucket, and choose the Pipelines > Schedules option. 
  2. Choose New schedule and enter:
    • The branch to run the pipeline on
    • The pipeline to run
    • Set the Schedule, choosing whether to run daily or weekly (hourly is not recommended)
    • Select the hour during the day to run the schedule

For more information see the BitBucket documentation.

Troubleshooting the dependency analysis

See Advanced security troubleshooting for guidance on how to troubleshoot the dependency analysis.


Was this page helpful?

© 2008-2025 SonarSource SA. All rights reserved. SONAR, SONARSOURCE, SONARQUBE, and CLEAN AS YOU CODE are trademarks of SonarSource SA.

Creative Commons License