Skip to main content

Sonatype Container Security

Sonatype Container Security provides build-time protection for container images. It integrates with your CI/CD pipeline to scan for known vulnerabilities (CVEs) and enforce security policies before images are pushed or deployed, helping you catch issues early and block non-compliant builds.

Sonatype Container Scanner is now the default for container scanning in IQ CLI and all supported CI integrations (Jenkins, GitHub Actions, GitLab, Azure DevOps, Bamboo).

We strongly recommend migrating to the Sonatype Container Scanner before the NeuVector end-of-support date in September 2026. The Sonatype Container Scanner offers better Windows support, and eliminates Docker-in-Docker requirements.

What this means

  • No action required if you want to use the Sonatype Container Scanner (recommended).

  • The Sonatype Container Scanner becomes the default for all new and existing scans.

  • The NeuVector-based scanner remains available for backward compatibility until September 2026.

Sonatype Container Scanner

Starting with IQ Server 1.196.0, Sonatype Lifecycle adds Sonatype Container Scanner.

Benefits

  • Uses Sonatype vulnerability intelligence alongside NeuVector data.

  • Eliminates the need for Docker-in-Docker (DinD).

  • Scans remote images without a running Docker daemon.

  • Runs on Windows.

Prerequisites for Sonatype Container Scanner

  • IQ Server 1.196.0 or later.

  • IQ CLI 2.6.0 or later.

    • macOS IQ CLI bundle: not yet supported.

    • Other integration clients: not yet supported.

Container Vulnerability Data Sources

Container scanning analyzes both operating system (OS)-level packages and application dependencies within container images using Sonatype vulnerability intelligence.

Container scanning combines OS-specific vulnerability data sources with Sonatype’s broader vulnerability intelligence platform to identify known vulnerabilities across the full container stack.

For more details, see Container Vulnerability Data Sources and Operating System Coverage.

Scanning with Sonatype Container Scanner

Sample Usage

Note

Alpine Image must be present in local container daemon before running the containerScannerMode=sonatype

To ensure the alpine:3.4 image is available:

docker pull alpine:3.4
podman pull alpine:3.4
java -jar nexus-iq-cli*.jar \ -a admin:admin123 \ -D containerScannerMode=sonatype \ -i test-app \ -t build \ -s http://localhost:8070 \ container:alpine:3.4

OS Package Coverage (Inside Images)

Advanced Container Scanning reads distro package databases to identify OS-level packages.

  • APK (Alpine) — supported.

  • RPM / DNF (RHEL, CentOS, Fedora) — supported.

  • APT (Debian) — supported.

App-level package ecosystems (e.g., Maven, npm, PyPI) remain supported regardless of base OS.

Note

Scanning Windows-based container images is not supported.

Container Scanner Data Source Priority

The container scanner now prioritizes Sonatype vulnerability data as the primary source for vulnerability detection. External data sources are used only as a fallback when Sonatype data is not available. This change ensures consistent results between Container Scanner and CLI evaluations.

Data Source Logic

When scanning a container image, vulnerability data is selected using a priority-based approach: Sonatype vulnerability data is used as the primary source, and external vulnerability data is used as a fallback. If Sonatype data is available, it is used; otherwise, external data is used.

Impact

  • Scan results may change for some images.

  • Results are now consistent between Container Scanner and CLI.

  • External data is only used when Sonatype data is unavailable.

Scanning a local image

This will look for an image in your local Docker instance and scan it when found. This is useful for scanning images built locally and before pushing them to a registry.

Scanning a local image using the default configuration does not require setting environment variables. Use the container:<image>:<version> format as the scan target.

container:alpine:3.4

Example with the Sonatype CLI

java -jar nexus-iq-cli*.jar \ -a admin:admin123 \ -i test-app \ -t build \ -s http://localhost:8070 \ container:alpine:3.4

Refer to the Sonatype CLI documentation for parameter details.

Scanning an application along with the container

Analyze an application and container simultaneously by specifying both as targets in the CLI command. Use a space between the path to the application and the container.

/app_path container:alpine:3.4

Example with application binary and base container

java -jar nexus-iq-cli*.jar \ -a admin:admin123 \ -i test-app \ -t build \ -s http://localhost:8070 \ ./my_application.war container:alpine:3.4

Scanning a remote image

Include the container's url to scan an image stored on a remote server. We recommend you set the registry's username and password environment variables to authenticate on the remote registry. Credentials are required for private images.

export NEXUS_CONTAINER_IMAGE_REGISTRY_USER=anyuser export NEXUS_CONTAINER_IMAGE_REGISTRY_PASSWORD=xxxxxxxxxxxxxx
java -jar nexus-iq-cli*.jar \ -a admin:admin123 \ -i test-app \ -t build \ -s http://localhost:8070 \ container:https://registry.hub.docker.com/library/alpine:3.4

Running a scan from Jenkins

Requirements are a running instance of Jenkins with the Sonatype Platform plugin installed and configured to run policy evaluations in Jenkins.

Consult the Jenkins documentation for examples of setting environment variables.

For this example, the scanPattern of container: is used to target the container.

  1. Create a new pipeline project in Jenkins

  2. Enter and update the example script from below into the Pipeline section

  3. Save the pipeline script and run the build in Jenkins

  4. Once complete, follow the link to the results report

pipeline {
  agent any

  environment {
    NEXUS_CONTAINER_IMAGE_REGISTRY_USER = {anyuser}
    NEXUS_CONTAINER_IMAGE_REGISTRY_PASSWORD = {password}
  }

  stages {
    stage('Policy') {
      steps {
        nexusPolicyEvaluation (
          advancedProperties: '', 
          enableDebugLogging: false,
          failBuildOnNetworkError: false,
          iqApplication: selectedApplication('test-app'),
          iqScanPatterns: [
            [scanPattern: 'container:https://registry.hub.docker.com/library/alpine:3.4'],
            [scanPattern: '**/my_application.war']
          ], 
          iqStage: 'build',
          jobCredentialsId: ''
        )
      }
    }
  }
}

NeuVector-based Container Security

Using the Legacy NeuVector Scanner

If you need to temporarily continue using the legacy NeuVector-based scanner, explicitly specify the scanner mode using the following flag:

-D containerScannerMode=NEUVECTOR

Sample Usage

java -jar nexus-iq-cli*.jar \ -a admin:admin123 \ -i test-app \ -t build \ -s http://localhost:8070 \ -DcontainerScannerMode=NEUVECTOR \ container:alpine:3.4

Warning

The NeuVector-based Container Security is incompatible with Docker 29 and higher. When using Docker 29 and above use the Sonatype Container Scanner instead.

Prerequisites for NeuVector-based Container Security

NeuVector-based Container Security is a feature available to the Lifecycle and SBOM Manager solutions. It utilizes the NeuVector scanner (a third-party component) embedded into the Sonatype CLI to provide container security analysis.

  • MacOS or Linux.

  • A running instance of Docker or Podman client.

  • Set the environment variables as needed.

Container scanning using Windows OS is not supported. The Azure DevOps plugin supports container security build time container: scanning, provided the agent uses macOS or Linux and the other prerequisites are met.

Windows users should refer to Docker Container Analysis.

Running scans with Podman

If you don't have Docker, you may use Podman as an alternative container runtime. Podman is a daemonless container engine for developing, managing, and running OCI (Open Containers Initiative) Containers and Container Images.

Podman can be used with both Sonatype Container Scanner and the NeuVector-based scanner. Ensure that podman is available on $PATH and set NEXUS_CONTAINER_SCANNING_RUNTIME to podman.

When using the NeuVector-based scanner, also set NEXUS_CONTAINER_SOCKET_MAPPING so that the host Podman socket is mounted at /var/run/docker.sock inside the NeuVector scanner container. The destination must be /var/run/docker.sock because that is the socket path the NeuVector scanner container reads. Sonatype Container Scanner does not read NEXUS_CONTAINER_SOCKET_MAPPING.

export NEXUS_CONTAINER_SOCKET_MAPPING=/run/podman/podman.sock:/var/run/docker.sock

Using the Runtime‐Override Environment Variable

  1. Set the runtime to Podman:

    export NEXUS_CONTAINER_SCANNING_RUNTIME=podman

  2. Run the container scan:

    java -jar nexus-iq-cli*.jar \ -i ContainerScan \ -t stage-release \ -s http://localhost:8070 \ -a [username]:[password] \ container:nodered/node-red:2.0.3

    In the logs you’ll see:

    [INFO] Using runtime: Podman

    confirming that Podman, not Docker, is being used.

  3. Verify Podman:

    podman ps

    You should see your Podman containers running. When using the NeuVector-based scanner, this includes NeuVector’s scanner image.

Alternative: symlink Docker to Podman

For environments where you cannot change the runtime via env var, Podman can provide Docker-compatible commands via a symlink:

  1. Verify that the docker command isn’t found on your system:

    % docker zsh: command not found: docker

  2. Confirm that Podman is installed by running the podman command without any arguments. This should display usage information and available options.

    % podman

  3. Alias Docker to Podman or create a symlink that points Docker’s path (/usr/bin/docker ) to Podman (/usr/bin/podman). Keep in mind that paths might change depending on your specific environment:

    % sudo ln -s /usr/bin/podman /usr/bin/docker

  4. Verify the symlink was created correctly:

    % ls -al /usr/bin/docker

    This should return output showing that /usr/bin/docker points to /usr/bin/podman. Ensure the path and target are as expected.

    The symbolic link allows you to use the docker command, which will execute the podman binary.

  5. Enable the Podman socket:

    % sudo systemctl enable --now podman.socket

    This creates a socket at:

    /run/podman/podman.sock

  6. Export the environment variable when running the scan:

    % export NEXUS_CONTAINER_SOCKET_MAPPING=/run/podman/podman.sock:/var/run/docker.sock

  7. Log in to the container registry:

    % podman login

    Enter your username and password. If successful, you'll see the message "Login Succeeded!"

  8. Run your container scan:

    % java -jar /Users/[your username]/Applications/nexus-iq-server-1.176.0-01-bundle/nexus-iq-cli.1.76.0-01.jar -i ContainerScan -t stage-release -s http://localhost:8070 -a [username]:[password] container:nodered/node-red:2.0.3

    The report will be generated without requiring a running Docker daemon, using Podman instead.

Environment Variables

These environment variables are to set the authentication to remote servers.

Environment Variable

Example Value

Supported by Sonatype Container Scanner

NEXUS_CONTAINER_IMAGE_REGISTRY_USER

<registry_username>

Confirmed

NEXUS_CONTAINER_IMAGE_REGISTRY_PASSWORD

<registry_password>

Confirmed

These environment variables may be set to override the default configuration.

Environment Variable

Default Value

Supported by Sonatype Container Scanner

NEXUS_CONTAINER_SCANNING_RUNTIME

Since IQ 1.182.0

Set to podman if you want to run scans with Podman instead of Docker.

docker

Confirmed

NEXUS_CONTAINER_SOCKET_MAPPING

Since IQ 1.182.0

When performing container scans, Docker-in-Docker (DinD) is required only if you are scanning local images or using the Docker CLI or GitLab plugin (regardless of whether the target image is local or remote). If you’re scanning a remote image directly, Docker-in-Docker isn’t needed since NeuVector pulls image layers straight from the registry and doesn’t rely on the host OS socket.

/var/run/docker.sock:/var/run/docker.sock

NEXUS_CONTAINER_SCANNING_LICENSE

""

NEXUS_CONTAINER_SCANNING_SCANNER_IMAGE

scanner

NEXUS_CONTAINER_SCANNING_REGISTRY_URL

https://registry.hub.docker.com/neuvector

NEXUS_CONTAINER_SCANNING_REGISTRY_USER

<dockerhub username>

NEXUS_CONTAINER_SCANNING_REGISTRY_PASSWORD

<dockerhub password>

NEXUS_CONTAINER_INCLUDE_ONLY_OS_COMPONENTS

Since IQ 1.185.0

If set to true, container scans will only include OS components. This excludes application dependencies like Java JARs, npm packages, etc., focusing the scan on the OS layer.

Confirmed

NEXUS_CONTAINER_SCANNING_MOUNT_PATH

Deprecated in IQ 1.184.0

When using the mount path for Sonatype Container, the user requires write permissions to the location specified at the mount path. Write permission to /tmp is required when the default value is used.

/tmp

NEXUS_CONTAINER_SCANNING_BIND_MOUNT_SHARED

Only for IQ CLI version 1.183.0 or earlier

false

FAQs

How does Sonatype evaluate containers?

Sonatype leverages Container Security to directly provide information about your images and registries back in the same report, alongside other application vulnerabilities and evaluation results.

Where can I integrate Sonatype Container Security scanning into my SDLC?

Sonatype Container Security scanning in Lifecycle and SBOM Manager is available in the CLI and the Jenkins, Bamboo CI, and Gitlab CI plugins.

How do I configure the shared folder between the Sonatype scanner and NeuVector?

If you're using IQ CLI version 1.183.0 or earlier, the environmental variable NEXUS_CONTAINER_SCANNING_MOUNT_PATH is used to override the shared folder for communication between the Sonatype scanner and the NeuVector container. This is not needed if you're using IQ CLI version 1.184.0 or later.

How can I scan with an SELinux image?

If you're using IQ CLI version 1.183.0 or earlier, there is support for the environmental variable NEXUS_CONTAINER_SCANNING_BIND_MOUNT_SHARED. Setting the property to true will include the ':z' option in the request allowing the bind mount content to be shared among multiple containers. This is not needed if you're using IQ CLI version 1.184.0 or later.

Details are found in the Docker documentation.

Why are components discovered by Sonatype Container Security showing the component's license name as "Not Provided"?

The Sonatype Container Security scan does not show the license information for all the detected components. These are OS-level components where the identity information is provided by a third-party source that only provides vulnerability information. There is no way to get the license information at this time. This feature has been raised as an enhancement request. Submit your interest on ideas.sonatype.com

Why does the component overview page only show one version?

The component overview page only show one version because NeuVector's provided component identity information does not include other versions of the component data.

Does Sonatype support OCI container images?

Yes. Sonatype supports scanning OCI-compliant container images. This support has been available since the initial release of container scanning.