Firewall for Docker
Firewall for Docker
Modern software development relies on Docker containers for their portability and efficiency. As organizations adopt containers, ensuring their compliance with internal security policies is critical. Repository Firewall supports policy enforcement capabilities to containerized applications.
Traditional security scanners lack the ability to actively prevent vulnerable containers from being downloaded to your development environments, leaving a critical gap in your security posture while they perform their analysis.
Repository Firewall analyzes and quarantines Docker containers as they are requested through your container proxy repository, ensuring that only trusted and compliant images are used throughout your development and deployment pipelines.
Benefits of Firewall for Docker
Automatic Policy Enforcement for Docker
Extend your existing Repository Firewall policies to Docker container images by automatically evaluate incoming container images against your policies.
Preventing Risky Deployments
Repository Firewall actively quarantines Docker images that violate your policies, preventing them from being downloaded by developers or deployed to your environments.
Streamlined Developer Workflow
Developers receive immediate feedback on policy violations in the requested Docker images, identifying the specific components within a container that trigger a violation. This enabling them to address issues early in the development cycle, reducing costly rework and accelerating secure software delivery.
Simplified Waiver Management
As individual violations in containers are not addressed by your development teams, failing violations may be waived with a single action for a specific container image. This significantly speeds up the review and approval process for accepting container risk.
Enabling Firewall for Docker
Setting the BaseURL
The base URL tells the server how to form links so that the servers may be reached when generating external reports. Nexus Repository uses the headers X-Forwarded-Host and X-Forwarded-Host when the value is not set in the Nexus Repository BaseURL configuration.
In releases before Nexus Repository 3.87.0, the base URL setting is required for Nexus Repository. This is not required in Nexus Repository Cloud deployments.
See Nexus Repository Base URL Capability
Audit and Quarantine
Audit and quarantine for Firewall for Docker is enabled as you would any other repository.
See Repository Firewall Getting Started
Containers Dashboard
Repository Firewall includes a unique dashboard for managing your containers and their violations.
Enable Containerd
We recommend enabling containerd on your clients to receive the clear custom error response which includes the link to the Docker image report. Clients based on dockerd receive a generic error that looks like a permission error when encountering a quarantined image.
See Using containerd vs dockerd
Optimizing the Container Analysis
You may greatly reduce the time for each container analysis by following these recommendations for optimizing the temporary directory of Nexus Repository architecture.
See Optimizing the Container Analysis
Using HTTP Settings to Access Remote Registries
Early versions of Firewall for Docker did not use the network settings configured on proxy repositories in Nexus Repository when downloading images from Docker registries. As a result, Firewall for Docker could not download the Docker images for scanning.
Beginning with Nexus Repository release 3.86.0 and IQ Server version 197, Firewall for Docker now supports downloading container image content (manifests and layers) using the HTTP configuration defined on proxy repositories in the integrated Nexus Repository instance. This includes the use of configured certificates. This functionality requires Nexus Repository version 3.86.0+ and Sonatype IQ Server version 197+.
When using an older version of IQ Server, Firewall for Docker falls back to its previous behavior, which downloads and scans images without applying the proxy repository’s HTTP settings.
Container Analysis Workflow
Repository Firewall performs the following when when a new Docker image is requested from a protected proxy repository. There is a delay in pulling down the container for the first time to allow for the scan to happen.
Analyze the Container Manifest
Generate a manifest of components found in the container and analyze the manifest for known risk. Repository Firewall's Audit and Quarantine capability must be configured on the Docker proxy repository before requesting an image to analyze.
See Firewall Audit and Quarantine Capability
Quarantine Risky Containers
Quarantine the container from being downloaded when a component found in the container has at least one failing violation. Repository Firewall will quarantine containers with a policy violation set to fail on the proxy stage. When a container is quarantined it will not be available for download from the proxy repository.
Containers Dashboard
Report the status of the container in the containers dashboard.
See Containers Dashboard section below
Container Report
Compile a comprehensive violation report of the containers' components.
See Container Report section below
Waive All Failing Violations
When viewing the container report, use the button for single-click remediation of any failing violations by your security team to release the container from quarantine. Once released, future requests for the image are downloaded through the proxy.
Supported Functionality
Supporting nearly all modern Docker images on Docker Hub
Docker schema 2 (both single-manifest and multi-architecture).
Beginning with release 3.86.0, Firewall for Docker also supports manifest lists (used for multi-architecture images), images without layers, and uncompressed image layers.
Firewall for Docker does not currently support scanning Docker schema 1.
Supported OS distributions for container analysis
Docker for Firewall supports detection for OS-level package managers including the following;
APK (Alpine Package Keeper), APT for Debian, RPM, DNF
The package type APT is not currently supported in Lifecycle.
Support for OCI added in Nexus Repository 3.84.0
As of the 3.84.0 release of Nexus Repository, the Repository FIrewall scanner is able to process images with manifest using the “OCI Image Manifest Specification”. The following is an example of the media type supported:
application/vnd.oci.image.manifest.v1+json
Support proxies of any container registry in Nexus Repository
Supports containers when proxied from any proxy repository in Nexus Repository, not just Docker Hub. Due to the complexity of analyzing containers, this feature is not supported in Firewall for Artifactory.
Pulling docker images using a digest is not currently supported in Firewall for Docker
While pulling a docker images using the digest hash is possible in Nexus Repository doing so bypassed the Repository Firewall container analysis and is not recommended or supported.
Namespace Confusion Protection is not currently supported in Firewall for Docker
Sonatype does not ingest or retain container data
The container analysis is performed by temporarily downloading the container locally to the Nexus Repository at the time of the request using Sonatype's built in toolings to precisely identify open source components found in the container.
Optimizing the Container Analysis
Internal testing has found significant performance differences when running Firewall for Docker depending on the environment used for Nexus Repository. Container analysis occurs locally to the server in a temporary directory and the type of storage used may introduce latency and poor throughput under load. Network-attached or shared file systems such as EFS are likely to result in degraded performance.
Note
Container analysis performs best with fast local disk storage. Network-attached or shared storage (for example, NFS, Azure Blob, or EFS) is not supported for the Firewall for Docker work directory and can introduce latency, which may result in timeouts such as java.util.concurrent.TimeoutException: 10 minutes timeout.
The best observed performance is when the temporary directory is backed by a local disk. You do not need to change this when the sonatype work directory is already sitting on a local disk.
In HA environments, each node requires a dedicated local disk for the temporary scan directory.
The default temporary directory is set to the following location:
${work-dir}/tmp/sonatype-firewall-container-images
- Customize the temporary directory to use a local disk by setting the following property in the
nexus.propertiesfile. This path is used as the temporary directory.
nexus.firewall.container.workdirectory=/my/happy/place
See Configuring the Runtime Environment
Containers Dashboard
Containers analyzed and quarantined are displayed in the containers dashboard view. Selecting a container from this view opens the Container Report.
- Threat / Policy: The highest policy violation found from components in the container
- Quarantine Time: Timestamp of when the container analysis was performed.
- Container: The repository path, namespace, image, and tag for the container.
- Repository: The repository protected by Repository Firewall where the container was requested. Selecting the repository opens the repository results view.
Repository Results for Containers
Similar results to the Container Docker dashboard however the results are only for the repository where the containers are requested.
Use the filters and navigation to search through the containers analyzed by Repository Firewall.
Container Report
The container report is an audit of all of the components found in the container along sorted by the threat level of the policy violations of the components. When configured to aggregate by components only the highest risk policy violation is shown for the component. A given component many have multiple failing violations that are causing the container to be quarantined.
- Threat/Policy Name: The policy violation with the highest threat risk when aggregated by components.
- Component: Selecting the component name will navigate to the Component Details Page where you may view the metadata associated with the component and all policy violations. Policy violations may be waived individually or by all violations for the container.
- Waive All Fail Policy Violations: use this button to waive the violations causing the container to be quarantined.
Waive All Failing Violations
To release a container from quarantine, all of the policy violations set to fail at the proxy level for this repository must have a waiver applied. Waivers may be reviewed and added to each individual violation during a security audit or accepted all at once to release a container critical to your build pipeline.
Consider the following when applying waivers to container violations.
- The failing violations are listed at the top of the waiver view for reference. These violation may be viewed in detail by navigating back to the container report view and reviewing the component causing the violation.
- As a best practice, apply a waiver reason and comments as to why the container was waived.
- The API may be used to waive all failing violations for a container using a single endpoint.
See Firewall APIs
Using containerd vs dockerd
The "Use containerd for pulling and storing images" option changes Docker Desktop's underlying image management architecture:
When checked (containerd mode): - Uses containerd directly for image operations - Bypasses the traditional Docker daemon for registry interactions - containerd handles HTTP responses from registries more transparently
When unchecked (traditional mode): - Uses the legacy Docker daemon architecture - Docker daemon intercepts and processes registry responses - May transform/mask specific error details
This behavior differs as containerd preserves the original HTTP response body from Repository Firewall, showing the detailed quarantine message. The traditional Docker daemon appears to interpret any non-200 response as a generic authentication failure and replaces the specific firewall error with the following:
unauthorized: access to the requested resource is not authorized
This suggests containerd has better error transparency for registry interactions, while the Docker daemon applies more aggressive error normalization that can mask useful debugging information.