# Software Composition Analysis (SCA) > **Warning:** This product is in Beta stage and we may release breaking changes. `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. Use it after adding or updating a dependency to check it for risks before you commit. ## Prerequisites * [SonarQube CLI is installed and authenticated](/sonarqube-developer-tools/sonarqube-cli/quickstart-guide.md). * 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](https://www.sonarsource.com/products/sonarqube/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: ```bash sonar analyze dependency-risks --project ``` 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](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/analyzing-projects-for-dependencies-sca/#supported-languages-and-package-managers) in the SonarQube SCA documentation. SonarQube CLI sends only the resolved dependency snapshot to the server; your source code stays on your machine. 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 ` 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. ```bash # Default: active risks only sonar analyze dependency-risks --project my-project # Everything, including accepted, safe, and fixed sonar analyze dependency-risks --project my-project --statuses all # Active risks plus accepted (waiting on a fix decision) sonar analyze dependency-risks --project my-project --statuses to_fix # Mix raw statuses sonar analyze dependency-risks --project my-project --statuses new,open,confirm ``` **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) ```bash sonar analyze dependency-risks --project my-project ``` 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: ``` ── axios@0.21.1 (1 risk) ───────────────────────────────────────────────── in: package-lock.json BLOCKER OPEN CVSS 7.5 CVE-2023-4527 Recommended versions without known vulnerabilities: 0.21.4, 0.22.0 ── d3@7.0.0 (1 risk) ───────────────────────────────────────────────────── in: package-lock.json HIGH OPEN GPL-3.0 Review the license usage ════════════════════════════════════════════════════════════════════════════════ Summary: 14 dependencies checked, 3 risks found Filtering by: new, open, confirm ``` ### JSON For AI agents and scripts: ```bash sonar analyze dependency-risks --project my-project --format json ``` The JSON payload has the shape: ```json { "project": "my-project", "packages": [ { "package": "pkg:npm/axios@0.21.1", "newlyIntroduced": true, "riskCount": 1, "filePaths": ["package-lock.json"], "chains": [], "groups": [ { "type": "VULNERABILITY", "totalKnownRisksCount": 1, "selectedRisks": [ { "severity": "BLOCKER", "status": "OPEN", "vulnerabilityId": "CVE-2023-4527", "cvssScore": "7.5", "partialFixes": [ { "version": "0.21.4", "descriptionCode": "NEAREST_PARTIAL", "vulnerabilityIds": ["CVE-2023-4527"] } ] } ], "recommendation": { "action": "UPGRADE_PACKAGE", "fixVersions": [ { "version": "0.22.0", "descriptionCode": "LATEST_STABLE", "vulnerabilityIds": [] } ] } } ] } ], "errors": [], "summary": { "packagesScanned": 14, "totalRisks": 3 } } ``` * 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: ```bash sonar analyze dependency-risks --project my-project --format json \ | jq '.packages[].groups[].selectedRisks[] | select(.severity=="BLOCKER")' ``` ## 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 ` explicitly. ### Authentication required Run `sonar auth status` to inspect the active connection, and `sonar auth login` if no token is saved. See [the quickstart](/sonarqube-developer-tools/sonarqube-cli/quickstart-guide.md) for setup. ## Related pages * [Commands reference](/sonarqube-developer-tools/sonarqube-cli/using-sonarqube-cli/commands.md) * [Analyzing local changes](/sonarqube-developer-tools/sonarqube-cli/analysis/analyzing-local-changes.md) * [Secrets scanning](/sonarqube-developer-tools/sonarqube-cli/analysis/secrets-scanning.md) * [Exit codes](/sonarqube-developer-tools/sonarqube-cli/using-sonarqube-cli/exit-codes.md) * [Output formats](/sonarqube-developer-tools/sonarqube-cli/using-sonarqube-cli/output-formats.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sonarsource.com/sonarqube-developer-tools/sonarqube-cli/analysis/sca.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.