# Analyzing projects for dependencies (SCA)

Advanced Security is an add-on that requires a separate subscription to your [SonarQube Cloud's Enterprise plan](https://www.sonarsource.com/plans-and-pricing/#sonarqube-cloud-features).

## Enabling the SCA service

By default, SCA is enabled for your organization when SonarQube [Advanced Security](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/introduction) is active.

You can choose whether all projects will be scanned using SCA by default. To do this, go to your organization and choose **Administration** > **Organization Settings** > **Advanced Security**, where you can adjust the **Enable SCA** checkbox. 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 an analysis parameter.

## Supported languages and package managers <a href="#supported-languages-and-package-managers" id="supported-languages-and-package-managers"></a>

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:

<table><thead><tr><th>Language</th><th>Text</th><th>Package repository</th><th width="149">Manifest file names</th><th>Lock file names</th></tr></thead><tbody><tr><td>Java</td><td>Maven</td><td><a href="https://central.sonatype.com/">Maven Central</a><br></td><td>pom.xml</td><td>Generated at the time of analysis</td></tr><tr><td>Java</td><td>Gradle</td><td><a href="https://central.sonatype.com/">Maven Central</a><br></td><td><ul><li>build.gradle</li><li>build.gradle.kts</li></ul></td><td>Generated at the time of analysis</td></tr><tr><td>JavaScript</td><td>NPM</td><td><a href="https://npmjs.com/">NPM</a></td><td>package.json</td><td><ul><li>package-lock.json</li><li>npm-shrinkwrap.json</li></ul></td></tr><tr><td>JavaScript</td><td>Yarn</td><td><a href="https://npmjs.com/">NPM</a></td><td>package.json</td><td>yarn.lock</td></tr><tr><td>JavaScript</td><td>PNPM</td><td><a href="https://npmjs.com/">NPM</a></td><td>package.json</td><td>pnpm-lock.yaml</td></tr><tr><td>JavaScript</td><td>Bun</td><td><a href="https://npmjs.com/">NPM</a></td><td>package.json</td><td>bun.lock</td></tr><tr><td>Kotlin</td><td>Maven</td><td><a href="https://central.sonatype.com/">Maven Central</a></td><td>pom.xml</td><td>Generated at the time of analysis</td></tr><tr><td>Kotlin</td><td>Gradle</td><td><a href="https://central.sonatype.com/">Maven Central</a></td><td><ul><li>build.gradle</li><li>build.gradle.kts</li></ul></td><td>Generated at the time of analysis</td></tr><tr><td>PHP</td><td>Composer</td><td><a href="https://packagist.org/">Packagist</a></td><td>composer.json</td><td>composer.lock</td></tr><tr><td>Python</td><td>Pip</td><td><a href="https://pypi.org/">PyPI</a></td><td>requirements.txt</td><td>Generated at the time of analysis</td></tr><tr><td>Python</td><td>Pipenv</td><td><a href="https://pypi.org/">PyPI</a></td><td>Pipfile</td><td>Pipfile.lock</td></tr><tr><td>Python</td><td>Poetry</td><td><a href="https://pypi.org/">PyPI</a></td><td>pyproject.toml</td><td>poetry.lock</td></tr><tr><td>Python</td><td>uv</td><td><a href="https://pypi.org/">PyPI</a></td><td>pyproject.toml</td><td>uv.lock</td></tr><tr><td>Scala</td><td>Maven</td><td><a href="https://central.sonatype.com/">Maven Central</a></td><td>pom.xml</td><td>Generated at the time of analysis</td></tr><tr><td>Scala</td><td>Gradle</td><td><a href="https://central.sonatype.com/">Maven Central</a></td><td>build.gradle</td><td>Generated at the time of analysis</td></tr><tr><td>Golang</td><td>go</td><td><a href="https://pkg.go.dev/">pkg.go.dev</a></td><td>go.mod</td><td>Generated at the time of analysis</td></tr><tr><td>C#</td><td>NuGet</td><td><a href="https://www.nuget.org/">NuGet Gallery</a><br></td><td><ul><li><em>.csproj</em></li><li><em>Project.json</em></li><li>.nuspec</li></ul></td><td><ul><li>packages.lock.json<br></li><li>project.assets.json</li><li>Project.lock.json</li><li>paket.lock</li></ul></td></tr><tr><td>Ruby</td><td>Rubygems</td><td><a href="https://rubygems.org/">Rubygems</a></td><td>Gemfile</td><td>Gemfile.lock</td></tr><tr><td>Rust</td><td>Cargo</td><td><a href="https://crates.io/">Crates.io</a></td><td>Cargo.toml</td><td>Cargo.lock</td></tr><tr><td>C/C++ (beta)​</td><td>Conan</td><td>​<a href="https://conan.io/">conan.io</a></td><td>conanfile.py</td><td>conan.lock</td></tr><tr><td>C/C++ (beta)​</td><td>VCPkg</td><td>​<a href="https://vcpkg.io/">vcpkg.io</a></td><td>vcpkg.json</td><td>Generated at the time of analysis</td></tr><tr><td>Generic SBOM (CycloneDX)</td><td>N/A</td><td>N/A</td><td><ul><li>cyclonedx.json</li><li>cyclonedx.xml</li><li><em>.cdx.json</em></li><li>.cdx.xml</li></ul></td><td>N/A</td></tr><tr><td>Generic SBOM (SPDX)</td><td>N/A</td><td>N/A</td><td><ul><li><em>.spdx</em></li><li>.spdx.json</li></ul></td><td>N/A</td></tr></tbody></table>

## Automatic analysis support

[automatic-analysis](https://docs.sonarsource.com/sonarqube-cloud/analyzing-source-code/automatic-analysis "mention") supports SonarQube Advanced Security's SCA functionality.&#x20;

To ensure accurate results, commit lockfiles (such as `yarn.lock`) to the project repository.

If lockfiles are not present in the repository, or not supported by the platform, only direct dependencies will be analyzed when using automatic analysis.

## Ensure the analysis is run in an appropriate environment <a href="#appropriate-environment" id="appropriate-environment"></a>

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 <a href="#note-on-security" id="note-on-security"></a>

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 <a href="#notes-on-specific-build-tools-and-language-ecosystems" id="notes-on-specific-build-tools-and-language-ecosystems"></a>

**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](https://github.com/SonarSource/sonarqube-documentation/blob/main/content-output/advanced-security/.gitbook/includes/troubleshooting-the-dependency-analysis.md) for some common scenarios.

#### Note on pull request analysis <a href="#appropriate-files" id="appropriate-files"></a>

To get valuable results when performing a pull request analysis, the target branch should be analyzed first.

## Ensure the analysis includes the appropriate files <a href="#appropriate-files" id="appropriate-files"></a>

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 SonarQube's SCM support is enabled (the default), add the paths to a source control ignore file, such as `.gitignore`

## Customizing the dependency analysis <a href="#customizing-the-dependency-analysis" id="customizing-the-dependency-analysis"></a>

The following parameters influence the results of the dependency analysis.

| Parameter                              | Type    | Default         | Description                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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  | <p><br></p>     | <p>A comma-separated list of global patterns of paths to exclude as part of analysis.</p><p>For example, to ignore all manifests under the tests/ and fixtures/ directories, set:</p><p><code>sonar.sca.exclusions = "tests/</code><strong><code>, fixtures/</code></strong><code>"</code></p>                                                  |
| `sonar.sca.allowManifestFailures`      | Boolean | true            | <p>When performing analysis, SonarQube attempts to run your build tools (such as Maven or Gradle) to create a full dependency graph.</p><p>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.</p> |
| `sonar.sca.goNoResolve`                | Boolean | false           | Disables automatic generation of a Go lock file. This results in degraded dependency information.                                                                                                                                                                                                                                               |
| `sonar.sca.mavenNoResolve`             | Boolean | false           | <p>Disables automatic generation of a Maven lock file and dependency graph file.</p><p>This results in degraded dependency information.</p>                                                                                                                                                                                                     |
| `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  | <p><br></p>     | 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  | <p><br></p>     | 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](https://www.sonarsource.com/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.                                                                                                                                                                                     |

## Troubleshooting the dependency analysis <a href="#troubleshooting-the-dependency-analysis" id="troubleshooting-the-dependency-analysis"></a>

See [Advanced security troubleshooting](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/troubleshooting/) for guidance on how to troubleshoot the dependency analysis.

## Using software bills of materials to analyze containers

You can use the Software Bill of Materials (SBOM) import feature of SonarQube Advanced Security to analyze a container image.

1. Generate an SBOM of the container. Several freely available tools can do this. For example, given a potential `test/example` container, version 1.2:

   **Using Syft**

   To generate the SBOM of the container using [Syft](https://github.com/anchore/syft):

   ```bash
   syft -o cyclonedx-json=container.cdx.json test/example:1.2
   ```

   **Using CycloneDX Generator**

   To generate the SBOM of the container using [CycloneDX Generator](https://github.com/cdxgen/cdxgen):

   ```bash
   cdxgen test/example:1.2 -o container.cdx.json -t docker
   ```
2. Use the SBOM import feature to analyze the resulting SBOM by passing the following in `sonar-project.properties` or on the scanner command line:

   ```properties
   sonar.sca.sbomImportPaths=container.cdx.json
   ```

## Continual analysis

Once SCA analysis has been performed on a 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.

You can configure the branch rescan frequency by going to **Administration** > **Advanced Security** > **Configure branch rescanning**.

From there, you can set the following:

* **Branch rescan frequency**: Daily, weekly, or never
* **Target branch types**: Main branch only, kept branches only, or all branches. When set to **Kept branches only**, continual analysis targets [long-lived branches](https://docs.sonarsource.com/sonarqube-cloud/analyzing-source-code/branch-analysis/branch-analysis-setup#longlived-branches).

## 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 an archive 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.

## Related pages <a href="#related-pages" id="related-pages"></a>

* [Viewing dependencies](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/viewing-dependencies)
* [Reviewing and fixing dependency risks](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/reviewing-and-fixing-dependency-risks)
* [Managing license profiles and policies](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/managing-license-profiles-and-policies)
* [Troubleshooting](https://docs.sonarsource.com/sonarqube-cloud/appendices/troubleshooting)
* [Best practices for managing dependency risks](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/best-practices-for-managing-dependency-risks)

## Related online courses

* <i class="fa-desktop">:desktop:</i> [Configuring SonarQube Advanced Security](https://www.sonarsource.com/learn/course/advanced-security/7160987d-7e9b-4223-a434-8dfba3beb34a/configuring-sonarqube-advanced-security)