Sonatype Firewall Enterprise

Sonatype Firewall Enterprise provides policy enforcement, waiver, and reporting capabilities for supported third-party repository managers.

It protects your software supply chain by evaluating open-source components against your Firewall policies before the repository manager downloads them from a public package registry.

Introduction

Firewall Enterprise sits between the repository manager and the public registry. When a developer or CI/CD system requests a component that is not already cached, the repository manager sends the request through a URL generated by Firewall Enterprise. Firewall Enterprise evaluates the component and either redirects the repository manager to the public registry or blocks the request, according to policy. Developers and CI/CD systems keep requesting components from the repository manager exactly as before.

Supported Package Formats

Format	Request Behavior
Maven	Maven 2
npm	npm registry
PyPI	PyPI Simple API
NuGet	NuGet V2 and NuGet V3

Configuration Structure

Term	Description
Policy Gateway	A logical configuration that represents one repository-manager connection and groups its proxy repositories. It is not a repository group and stores no package files.
Proxy repository	A format-specific configuration that names the public registry and corresponds to one remote (proxy) repository in your repository manager.
Generated Firewall Enterprise URL	The URL your repository manager uses to send component requests to Firewall Enterprise for evaluation.

Key Capabilities

Capability	Definition
Automatic policy evaluation	Every component request your repository manager sends through Firewall Enterprise is evaluated against your Repository Firewall policies at download time, before the component reaches the repository manager. No change is needed in builds or package clients.
Policy enforcement	Blocks component requests that violate a policy with a `Fail` action at the `Proxy` stage.
Multi-format support	Supports Maven, npm, PyPI, and NuGet (V2 and V3) proxy repositories.
Policy Gateway management	Groups related proxy repositories and applies policies and access settings across them.
Policy Gateway findings and waivers	Records one finding and requires one waiver for each component in each Policy Gateway rather than one waiver per proxy repository.
Policy Gateway Results	One page to review, waive, and re-evaluate every component evaluated across a Policy Gateway.
Self-hosted diagnostics	A dedicated outbound-request log, included with the Firewall Enterprise configuration in the IQ Server support zip.

How Firewall Enterprise Works

Component Request Flow

A developer or CI/CD system requests a component from the repository manager.
The repository manager checks whether the component is already in its cache.
If it is not cached, the repository manager sends the request through the generated Firewall Enterprise URL.
Firewall Enterprise identifies the component and evaluates it against the policies that apply to its Policy Gateway, using component intelligence from Sonatype Data Services.
Firewall Enterprise answers:
- 307 for an allowed component: a redirect to the configured public registry.
- 403 for a blocked component: no redirect.
For an allowed component, the repository manager follows the redirect, downloads the component from the public registry and caches it.

Note

Package bytes do not pass through Firewall Enterprise for redirected requests: the repository manager downloads the component directly from the public registry. Firewall Enterprise can answer an allowed component request from its recorded evaluation for up to one day. After that period, Firewall Enterprise evaluates the component again. A blocked component remains blocked until it is re-evaluated. See Configure Policies.

Metadata Requests

For npm, PyPI, and NuGet, Firewall Enterprise retrieves and rewrites package metadata so that the package-file requests that follow return through Firewall Enterprise for evaluation.

For NuGet, Firewall Enterprise processes the NuGet V3 service index and registration documents and the NuGet V2 OData feed.

Cached Content

A repository manager can serve a component from its cache without asking Firewall Enterprise again. When you validate a policy or waiver change, use a component that is not cached yet, wait for the repository manager's cache to expire, or invalidate the relevant cache before retrying. See Refresh metadata after a change.

Prerequisites Before Continuing

Before you configure Firewall Enterprise, you will need the following:

A valid Firewall Enterprise license. The license enables Firewall Enterprise; there are no feature flags to configure. Sonatype applies and manages the license for a Firewall Enterprise Cloud tenant. For self-hosted IQ Server, a System Administrator installs the license under System Preferences > Product License.
For self-hosted Firewall Enterprise, IQ Server configured to use an external PostgreSQL database. IQ Server refuses a Firewall Enterprise license when it uses the embedded database.
Access to your Firewall Enterprise Cloud tenant or self-hosted IQ Server.
A role with Edit IQ Elements on the Policy Gateways container to create Policy Gateways and proxy repositories. Firewall Enterprise roles are assigned in the Firewall Enterprise UI under Repos and Policies > Access. Organizations and identity-provider connections are managed through my.sonatype.com . See Access Control and Permissions in Sonatype Firewall Enterprise.
Repository Firewall policies with a Fail action at the Proxy stage.
Administrator access to the repository manager instance you want to connect.
A dedicated service account for repository-manager authentication. Assign the Component Evaluator role to the account at the Root Organization or on the Policy Gateways container. The service account must sign in and generate its own IQ user token because an administrator cannot generate a user token for another user. See Access Control and Permissions in Sonatype Firewall Enterprise > Create a Service Account for the Repository Manager.