Firewall Enterprise (FWE)

Setup logs in when you provide your password or user token. For CI and other non-interactive environments, configure the connection details and provide the password or user token through the SONATYPE_CLI_FWE_TOKEN environment variable. The auth login command requires an operating system credential store and exits with code 4 on Linux. The fwe run command does not read credentials saved with --credential-store file.

For example, configure an npm repository in a CI pipeline and store the token in your CI secret store:

sonatype config set fwe.url https://<iq-server>
sonatype config set fwe.username <iq-user>
sonatype config set fwe.policyGatewayName <policy-gateway-name>
sonatype config set fwe.repositoryId.npm <repository-id>
export SONATYPE_CLI_FWE_TOKEN=<password-or-user-token>
sonatype fwe run npm ci

On macOS, install the CLI certificate once before running dotnet. The CLI suggests the command when doctor reports that the certificate is missing:

sonatype ca install

Without the certificate, sonatype fwe run dotnet is refused with exit code 4 and a message naming sonatype ca install. To remove the certificate later, run:

sonatype ca uninstall

On Linux, the supported package managers do not need the CLI certificate. If you run sonatype ca install for another reason, it requires an interactive terminal and root privileges; you can use --sudo to run the trust-store commands. On a macOS build agent, run sonatype ca install once interactively before using dotnet in CI. The command exits with code 4 when CI=true.

Run a supported package manager with sonatype fwe run. For example:

sonatype fwe run npm install

When a component is blocked, the terminal output looks like this. For details about these messages and observe mode, see Evaluation results.

To generate a JSON report, include run and put the output options before the package manager name:

sonatype fwe run --output json --output-file ./report.json npm install

The --output-file option does not produce a report unless you also specify --output json.

Set these Firewall Enterprise settings in a configuration file with sonatype config set. They do not have environment-variable equivalents.

These are the supported fwe.* settings. There are no FWE settings for timeouts, proxies, or certificates.

Block mode is the default. Firewall Enterprise enforces your policies. When IQ Server reports that a component violates policy, the download is denied and the package manager fails. If IQ Server cannot evaluate a component, for example because it cannot be reached, the credential is wrong, or a setting is missing, the download is denied too.

Observe mode reports findings without blocking downloads. For a component that block mode would deny, the CLI still prints the same BLOCK message and summary; read this as “would be blocked.” If IQ Server cannot be reached, the build is not affected and the CLI prints a could not evaluate line instead.

Set the mode for every run of the profile. There is no per-command mode option, and the output does not identify the active mode.

sonatype config set fwe.mode observe
sonatype config set fwe.mode block

While sonatype fwe run runs your package manager, Firewall Enterprise prints messages to standard error. Each line starts with [fwe]; the package manager’s normal output is unchanged. In a colour terminal at least 80 columns wide, the summary is displayed as a table. In CI, a log file, or a narrow terminal, it is printed as plain lines.

A run with no policy violations ends with a summary like this:

[fwe] run summary: no blocked components observed (4 request(s) observed, 1 coordinate(s) evaluated, 0 blocked, 0 could NOT be evaluated).

The counts show requests sent through the local proxy, components evaluated, components that violated policy, and components IQ Server could not evaluate. A coordinate is one component and version.

When a component violates policy, the CLI prints a BLOCK message and the package manager reports its own error. For example:

[fwe] BLOCK pkg:npm/[email protected]
[fwe]   reason: Quarantined by policy 'Banned-Components' (threat level 10).
[fwe]   policy: Banned-Components [threat level 10, OTHER]
[fwe]   view in IQ: <findings URL, when provided by IQ Server>
npm ERR! code E403
[fwe] run summary: 1 blocked component(s) observed (4 request(s) observed, 1 coordinate(s) evaluated, 1 blocked, 0 could NOT be evaluated):

Package managers report blocked downloads differently. npm reports E403; Maven, Gradle, pip, and uv report HTTP 403; and dotnet reports HTTP 409.

The view in IQ line appears only when IQ Server provides a findings link. In observe mode, the CLI still prints BLOCK and the summary, but nothing is blocked by the CLI; read the message as “would be blocked.” The package manager usually succeeds. For example:

[fwe] BLOCK pkg:npm/[email protected]
[fwe] run summary: 1 blocked component(s) observed (4 request(s) observed, 1 coordinate(s) evaluated, 1 blocked, 0 could NOT be evaluated):

See Block mode and observe mode.

Use the summary to distinguish a clean evaluation from a run where nothing was checked:

In a JSON report, status can be ok even when a component was blocked. For CI checks, use the blocked field or the process exit code.

The report does not include the active mode, components IQ Server could not evaluate, or the package manager’s exit code. Use the process exit code for those details.

sonatype setup requires a terminal. In Linux and container agents, configure the fwe.* settings and provide the credential through SONATYPE_CLI_FWE_TOKEN from your CI secret store. The Authentication section has a configuration example.

Use the explicit run command to write a JSON report:

sonatype --output json fwe run --output-file ./report.json npm ci

In block mode, let the pipeline fail on a non-zero exit code. In observe mode, check blocked in the JSON report because the package manager can succeed when a component violates policy. Start from a clean package cache; cached packages are not evaluated.

The CLI does not support chaining through an upstream HTTP proxy. If your environment requires a corporate egress proxy to reach the registry, the wrapped package manager cannot use the CLI through that proxy.

Only downloaded package files are evaluated. Packages already in the package manager’s local cache are not checked; use a clean cache when you need a complete evaluation.

Provide users with the IQ Server URL, the username and password or user token they should use, and the Policy Gateway name registered in IQ for their Nexus Repository instance. Users also need the repository ID for each package format unless their package manager downloads through a Nexus Repository proxy URL that includes the repository name.