> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/container-scanning.md). # Container scanning Container scanning extends the capabilities of SonarQube Advanced Security to the analysis of container images. {% hint style="info" %} Container scanning is in beta. For more information on release stages, see [Product release lifecycle](/sonarqube-cloud/appendices/product-release-lifecycle.md). {% endhint %} By running the container scanning client CLI tool against an image, you can track the components of that image and what vulnerabilities are present. Container scanning analyzes containers looking for two types of risks: * Malicious packages: whether known malicious software is present in the container * Vulnerabilities: whether components in the container image contain known, public, vulnerabilities License risks and license policy is not available for container images, as licensing constraints for the use of container images are different than for code projects. ### Supported base container operating systems Vulnerability tracking is available for the same base container runtimes that are supported by [SonarQube’s SBOM import](https://docs.sonarsource.com/sonarqube-cloud/advanced-security/analyzing-projects-for-dependencies-sca#sbom-import-requirements), notably: * Red Hat Enterprise Linux * Debian (11 and higher) * Ubuntu * Alpine ### Download the scanner The scanner is available for: * Linux x64 * Linux arm64 * macOS x64 * macOS arm64 * Windows x64 Download the binary for your platform from [binaries.sonarsource.com](https://binaries.sonarsource.com/?prefix=CommercialDistribution/sonar-container-scanner/). On Linux and macOS, make `sonar-container-scanner` available in your `PATH`, for example by installing the executable in `~/.local/bin`: ```shell chmod +x sonar-container-scanner--.bin mkdir -p ~/.local/bin mv sonar-container-scanner--.bin ~/.local/bin/sonar-container-scanner ``` ### Run the analysis After you’ve downloaded the scanner, run the following command to analyze a container image: ```shell sonar-container-scanner --organization --token ``` We recommend passing your organization and token as environment variables, especially in CI, so the token doesn’t appear in command history or logs: | Environment variable | Equivalent flag | | ------------------------------- | ---------------- | | `SONAR_CONTAINER_SCANNER_ORG` | `--organization` | | `SONAR_CONTAINER_SCANNER_TOKEN` | `--token` | ```shell export SONAR_CONTAINER_SCANNER_ORG= export SONAR_CONTAINER_SCANNER_TOKEN= sonar-container-scanner alpine:3.19 ``` #### Supported image inputs | Input | Example | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | Container image reference | `alpine:3.19`, `myregistry/app@sha256:` | | Local `.tar` archive ([docker-archive](https://docs.docker.com/reference/cli/docker/image/save/) or [OCI layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md)) | `./my-image.tar` | | Local directory containing an OCI layout | `./my-image-oci/` | The image must already be available locally, for example after `docker build` or `docker pull`. #### Image identity The scanner automatically detects the image’s registry, repository and tag from the input. If it can’t identify a single image, platform or origin, it stops with exit code `2` rather than guessing. In that case, or whenever you want to set the identity yourself, use these flags: | Flag | Purpose | Example | | -------------- | ----------------------- | ---------------- | | `--registry` | Registry of the image | `docker.io` | | `--repository` | Repository of the image | `library/alpine` | | `--tag` | Tag of the image | `3.19` | ### Failing your pipeline on risky images Use `--fail-on` to make the scanner exit with a failing code when it finds risks at or above a given severity. Your CI pipeline can then stop vulnerable images before they ship. ```shell sonar-container-scanner my-app:1.4.0 --fail-on high ``` Accepted values: `none`, `info`, `low`, `medium`, `high`, `blocker`. The default is `high`. Use `none` to never fail on risk severity. #### Example: scan an image after building it in CI ```shell docker build -t my-app:${BUILD_TAG} . sonar-container-scanner my-app:${BUILD_TAG} --fail-on high ``` Set `SONAR_CONTAINER_SCANNER_ORG` and `SONAR_CONTAINER_SCANNER_TOKEN` as secret environment variables in your CI system. #### Speeding up CI runs with caching The scanner includes an embedded SBOM generator ([syft](https://github.com/anchore/syft)). On the first run, it extracts this generator into a local cache, which takes a few seconds. To avoid paying that cost on every CI job, cache the scanner’s cache directory between jobs. The scanner uses the first of these locations that is set: 1. `$SONAR_CONTAINER_SCANNER_CACHE_DIR`, used as-is. Useful for a read-only `$HOME` or a locked-down CI environment. 2. `$SONAR_USER_HOME/container-scanner` 3. `$HOME/.sonar/container-scanner` (`%USERPROFILE%\.sonar\container-scanner` on Windows) ### Configuration options Use the following options to configure the container scanner: | Flag | Values | Default | Description | | --------------------------------------- | -------------------------------------------------- | ------------- | ----------------------------------------------------------------------- | | `--organization` | Organization key | - | SonarQube Cloud organization to scan under | | `--token` | Token | - | SonarQube Cloud user token | | `--registry` / `--repository` / `--tag` | Text | Auto-detected | Override the image identity | | `--fail-on` | `none`, `info`, `low`, `medium`, `high`, `blocker` | `high` | Exit with a failing code when risks at or above this severity are found | | `--format` | `json`, `table` | `json` | CLI output format | | `--timeout-secs` | Integer | `300` | Timeout for subprocesses, in seconds | | `-v` / `-vv` | - | Off | Debug logging | | `--help` | - | - | List all options | ### Viewing the results in SonarQube Cloud 1. Open your organization in SonarQube Cloud. 2. Select **Container images** in the sidebar. 3. You’ll see every image analyzed in your organization, with its tag, the number of risks, the most severe risk, and when it was last analyzed. Use the search box to find an image, and **Sort by** to change the order. 4. Select an image to see its versions and their dependency risks. Manage risks with the same workflow you use for dependency risks in your projects. #### Keeping results up to date SonarQube Cloud automatically re-checks analyzed images for newly published vulnerabilities, based on your organization’s re-analysis settings. You don’t need to re-scan an image to learn about new vulnerabilities in it. To refresh an image’s results after it changes, run the scanner again. On-demand re-scans from the UI are not available yet. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.sonarsource.com/sonarqube-cloud/advanced-security/container-scanning.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.