For the complete documentation index, see llms.txt. This page is also available as Markdown.
BetaDeveloper

Software Composition Analysis (SCA)

Scan your project's open-source dependencies for known vulnerabilities, malware, and prohibited licenses from the terminal, using SonarQube's Software Composition Analysis (SCA) engine.

Note: SCA in the SonarQube CLI is in Beta and subject to change.

sonar analyze dependency-risks runs SonarQube's Software Composition Analysis (SCA) against your local project's open-source dependencies and reports the risks found: vulnerabilities, malware, and prohibited licenses. This command is in beta and subject to change. Use it after adding or updating a dependency to check it for risks before you commit.

Prerequisites

  • A SonarQube connection where Advanced Security with SCA is enabled:

    • SonarQube Cloud: the organization is on a plan that includes SonarQube Advanced Security, and SCA is enabled on the project. See Advanced Security.

    • SonarQube Server: version 2026.4 or later, with Advanced Security licensed and SCA enabled on the project.

  • The project exists on the server. sonar analyze dependency-risks analyzes against an existing project key. It does not create one.

Note: On first use, SonarQube CLI fetches the sca-scanner-cli binary from binaries.sonarsource.com and caches it under ~/.sonar/sonarqube-cli/bin/. Subsequent runs reuse the cached binary. To force a re-download, delete the cached file.

Run an analysis

From the root of your project, with --project set to the project key on the server:

sonar analyze dependency-risks --project <YourProjectKey>

SonarQube CLI:

  1. Verifies that your connection is authenticated and that SCA is enabled.

  2. Downloads the sca-scanner-cli binary on first use, or reuses the cached copy.

  3. Fetches the project's analysis settings (sonar.exclusions, sonar.sca.*) from the server.

  4. Collects your dependency graph from local manifests and lock files.

  5. Sends the snapshot to SonarQube for analysis.

  6. Prints the unresolved dependency risks for the project.

If SCA isn't enabled for the connection, the command exits immediately rather than producing empty results.

What gets analyzed

The scanner reads dependency manifests and lock files from your working tree across every ecosystem SonarQube SCA supports. For the full list of languages, package managers, and recognized manifest and lock-file names, see Supported languages and package managers in the SonarQube SCA documentation. SonarQube CLI uploads those manifest and lock files to SonarQube for analysis and sends the resolved dependency snapshot derived from them; your source code stays on your machine. Each run also prints a beta notice and a reminder about this upload on stderr before the scan starts.

SonarQube CLI applies the project's file-exclusion settings (sonar.exclusions, sonar.scm.exclusions.disabled, sonar.sca.*) to the snapshot before sending it. It fetches the current values from the server on each run, so changes made in the SonarQube UI take effect immediately.

Warning: SonarQube CLI doesn't report issue locations for dependency risks. Each finding identifies the package and version that carries the risk, not the line where the dependency is declared. To find the manifest that pulls in a vulnerable package, use your package manager's tooling (for example, npm ls <package> or mvn dependency:tree).

Filter by status

By default, sonar analyze dependency-risks shows active risks (NEW, OPEN, CONFIRM). Override with --statuses. The flag accepts presets, raw statuses, or a comma-separated mix. The result is the union, and matching is case-insensitive.

Presets:

Preset
Expands to

active

NEW, OPEN, CONFIRM

to_fix

NEW, OPEN, CONFIRM, ACCEPT

all

NEW, OPEN, CONFIRM, ACCEPT, SAFE, FIXED

Raw statuses: NEW, OPEN, CONFIRM, ACCEPT, SAFE, FIXED. SonarQube CLI reports NEW for risks that aren't yet known to the server. The other statuses reflect the lifecycle state stored on the server.

Output formats

Pass --format to switch between the default table output and structured JSON.

Table (default)

The default table output groups risks by package. Each package gets a header line with its coordinates and risk count, the manifest or lock file it was found in, and one row per risk (severity, status, and a short description), followed by a per-group recommendation footer. A summary footer reports the totals, the resolved filter, and any cross-package recommendations:

JSON

For AI agents and scripts:

The JSON payload has the shape:

  • Each packages[] entry corresponds to one analyzed dependency. The package field is the purl string. Additional fields include newlyIntroduced, riskCount, filePaths (manifests and lock files where the package appears), and chains (transitive-dependency chains as arrays of purls).

  • Each groups[] entry groups risks by type (VULNERABILITY, PROHIBITED_LICENSE, or MALWARE). It exposes selectedRisks[] (those matching your --statuses filter), recommendation (the suggested action, such as UPGRADE_PACKAGE, REMOVE_PACKAGE, REVIEW_LICENSE, or NO_FIX_AVAILABLE, and the fixVersions[] that clear every vulnerability in the group), and totalKnownRisksCount.

  • Each risk has a severity (BLOCKER, HIGH, MEDIUM, LOW, or INFO) and a status (NEW, OPEN, CONFIRM, ACCEPT, SAFE, or FIXED; NEW is synthesized for newly introduced packages with no server-side status yet). Vulnerability risks add vulnerabilityId, cvssScore (a string, or null), and partialFixes[]. Each partialFixes entry clears that specific vulnerability but may leave others in the package unresolved; use recommendation.fixVersions[] for versions that clear every vulnerability in the group. License risks add spdxLicenseId and releaseLicenseExpression (either may be null).

Pipe through jq to flatten or filter:

With an AI agent

An AI coding agent can call sonar analyze dependency-risks like any other shell command, read the JSON output, and propose a version bump that clears the vulnerabilities. For example:

"Run sonar analyze dependency-risks --project my-org_my-app --format json and, for any BLOCKER risk, propose the smallest version bump that clears the CVE."

Troubleshooting

SCA is not enabled on this connection

Your SonarQube plan or project doesn't include SonarQube Advanced Security with SCA. Confirm:

  • On SonarQube Cloud, your organization is on a plan that includes Advanced Security.

  • On SonarQube Server, the instance is 2026.4 or later and SCA is enabled on the project's Advanced Security configuration.

Project not found or wrong project picked

SonarQube CLI doesn't yet auto-detect a project for SCA analysis. Pass --project <YourProjectKey> explicitly.

Authentication required

Run sonar auth status to inspect the active connection, and sonar auth login if no token is saved. See the quickstart for setup.

Last updated

Was this helpful?