Skip to main content

Configure a package manager

All configuration options require a Package Firewall access token because Package Firewall uses authentication. To copy an access token, see copy an access token.

In the following examples, <FIREWALL_TOKEN> represents your access token. Ensure that you replace it with the token you generated.

note

You can configure a single firewall to support multiple package managers.

Cargo registry​

The Package Firewall Cargo registry is based on Cargo's sparse Registry Index API.

cargo​

To use the Package Firewall Cargo registry, add it to a .cargo/config.toml file. On UNIX you can use ~/.cargo/config.toml to make the registry available to all projects.

[registries]
veracode = { index = "sparse+https://cargo.firewall.veracode.com/" }

This configuration makes the Package Firewall registry available to all Cargo projects. However, by default, Cargo still uses the official registry. To ensure all requests go through Package Firewall, override the crates.io registry in the .cargo/config.toml file. You can use a project-specific Cargo config if you don't want to run all installs globally through Package Firewall.

The easiest way to enable Package Firewall is by replacing the crates.io source with Package Firewall's registry. This has the advantage of creating Cargo.toml and Cargo.lock files that are identical to the ones created for the official registry.

[source.crates-io]
replace-with = "veracode"

Because replacing the Cargo source prevents you from using the official registry, this approach is unsuitable if you need certain packages to remain installable without using Package Firewall. In this case, set Package Firewall as the default registry instead:

[registry]
default = "veracode"

Since Package Firewall's registry requires authentication, you'll also need to configure a credential provider in your .cargo/config.toml file:

[registry]
global-credential-providers = ["cargo:token"]

Once the file-based cargo:token credential provider is configured, you can add your authentication details to the .cargo/credentials.toml file.

First, convert the Package Firewall API key to Base64:

printf "-:<FIREWALL_TOKEN>" | base64
note

Do not accidentally save your token into your shell history.

After you convert the token to Base64, add it as a basic authentication token to your credentials:

[registries.veracode]
token = "Basic <BASE64_OUTPUT>"

A blocked package appears in cargo output as missing:

    Updating `veracode` index
error: no matching package named `libc` found
location searched: registry `veracode`
required by package `testing v0.1.0 (/tmp/testing)`

If all versions of a package are blocked, the output explicitly states that the package failed analysis:

error: failed to query replaced source registry `crates-io`

Caused by:
  download of li/bc/libc failed

Caused by:
  failed to get successful HTTP response from `https://cargo.firewall.veracode.com/li/bc/libc`, got 424
  body:
  "libc" failed Veracode analysis

Alternatively, if a specific version constraint matches the blocked version:

    Updating `veracode` index
error: failed to select a version for the requirement `libc = "=0.2.155"`
candidate versions found which didn't match: 0.2.158, 0.2.157, 0.2.156, ...
location searched: `veracode` index
required by package `testing v0.1.0 (/tmp/testing)`

If a version range is accepted by the manifest, the package manager automatically uses a version that passes Package Firewall policy.

Golang proxy​

The Package Firewall Golang proxy is based on Golang's Proxy API.

go​

To use the Package Firewall Golang proxy, set the GOPROXY environment variable:

export GOPROXY="https://:<FIREWALL_TOKEN>@golang.firewall.veracode.com"
note

Do not accidentally save your token into your shell history.

A blocked package will show up in go output as missing:

go: example.org/malicious: no matching versions for query "upgrade"

If all versions of a package are blocked, the output explicitly states that the package failed analysis:

go: module example.org/malicious: reading https://golang.firewall.veracode.com/example.org/malicious/@v/list: 424 "example.org/malicious" failed Veracode analysis
    server response: "example.org/malicious" failed Veracode analysis

Alternatively, if a specific version was requested:

go: example.org/[email protected]: reading https://golang.firewall.veracode.com/example.org/malicious/@v/v1.2.3.info: 424 Failed Dependency

If a version range is accepted by the manifest, the package manager automatically attempts to use a version that passes Package Firewall's policy.

Maven registry​

The Package Firewall Maven registry is based on Maven central.

mvn​

Because the Package Firewall authorization header expects a Base64 token, convert your Package Firewall access token first:

printf "-:<FIREWALL_TOKEN>" | base64
note

Do not accidentally save your token into your shell history.

Custom Maven registries can be configured in the ~/.m2/settings.xml file. Replace [BASE64_OUTPUT] in this XML with the token you created in the previous step:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>veracode</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Basic [BASE64_OUTPUT]</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>

  <mirrors>
    <mirror>
      <id>veracode</id>
      <name>Veracode</name>
      <url>https://maven.firewall.veracode.com</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

A blocked package will show up in mvn output as missing:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.871 s
[INFO] Finished at: 2024-10-29T18:44:40+01:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal on project demo: Could not collect dependencies for project io.veracode:demo:jar:1.0-SNAPSHOT
[ERROR] Failed to read artifact descriptor for commons-io:commons-io:jar:2.17.0
[ERROR]     Caused by: The following artifacts could not be resolved: commons-io:commons-io:pom:2.17.0 (absent): Could not transfer artifact commons-io:commons-io:pom:2.17.0 from/to veracode (https://maven.firewall.veracode.com): status code: 424, reason phrase: Failed Dependency (424)
[ERROR]
[ERROR] -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/DependencyResolutionException

If all versions of a package are blocked, the output explicitly states that the package failed analysis:

[WARNING] Could not transfer metadata org.apache.maven.plugins:maven-archetype-plugin/maven-metadata.xml from/to veracode (https://maven.firewall.veracode.com): status code: 424, reason phrase: "pkg:maven/org.apache.maven.plugins/maven-archetype-plugin" failed Veracode analysis (424)
[WARNING] Plugin not found in any plugin repository: org.apache.maven.plugins:maven-archetype-plugin
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.753 s
[INFO] Finished at: 2025-03-17T17:28:12+01:00
[INFO] ------------------------------------------------------------------------
[ERROR] Error resolving version for plugin 'org.apache.maven.plugins:maven-archetype-plugin' from the repositories [local (/Users/cdurr/.m2/repository), veracode (https://maven.firewall.veracode.com)]: Plugin not found in any plugin repository -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/PluginVersionResolutionException

If a version range is accepted by the manifest, the package manager automatically attempts to use a version that passes Package Firewall's policy.

Gradle​

Custom registries can be configured in the ~/.gradle/init.gradle file:

allprojects {
    repositories {
        // Deactivate all registries which aren't protected.
        all { ArtifactRepository repo ->
            if (repo.url.toString() != "https://maven.firewall.veracode.com") {
                remove repo
            }
        }

        maven {
            url = "https://maven.firewall.veracode.com"
            credentials {
                username = "veracode"
                password = "<FIREWALL_TOKEN>"
            }
        }
    }
}

A blocked package appears in gradle output as failed:

runtimeClasspath - Runtime classpath of source set 'main'.
+--- com.google.code.gson:gson:2.10.1 FAILED
+--- com.google.code.gson:gson:{strictly 2.10.1} -> 2.10.1 FAILED
\--- com.google.code.gson:gson:2.10.1 FAILED

If a version range is accepted by the manifest, the package manager automatically attempts to use a version that passes Package Firewall's policy.

NPM registry​

The Package Firewall NPM registry is based on NPM's Public Registry API.

npm and pnpm​

You can set custom NPM registries for both npm and pnpm using npm:

npm config set replace-registry-host never
npm config set registry https://:<FIREWALL_TOKEN>@npm.firewall.veracode.com/
note

Do not accidentally save your token into your shell history.

A blocked package will appear in npm output as E403:

npm error code E403
npm error 403 Could not download <malicious>@<version> due to policy violations:
npm error 403 Blocked by package firewall.
npm error 403 In most cases, you or one of your dependencies are requesting
npm error 403 a package version that is forbidden by your security policy, or
npm error 403 on a server you do not have access to.

If you use pnpm, the output appears as follows:

ERR_PNPM_NO_VERSIONS No versions available for malicious. The package may be unpublished.

If all versions of a package are blocked, the output explicitly states that the package failed analysis:

ERR_PNPM_FETCH_424 GET https://npm.firewall.veracode.com/malicious: "malicious" failed Veracode analysis - 424
ERR_PNPM_NO_MATCHING_VERSION No matching version found for malicious@latest while fetching it from https://npm.firewall.veracode.com/

If a version range is accepted by the manifest, the package manager automatically attempts to use a version that passes Package Firewall's policy.

yarn​

Custom NPM registries can be configured with yarn:

yarn config set -H npmRegistryServer "https://npm.firewall.veracode.com/"
yarn config set -H npmAuthIdent "-:<FIREWALL_TOKEN>"
yarn config set -H npmAlwaysAuth true
note

Do not accidentally save your token into your shell history.

A blocked package appears in yarn output as missing:

➤ YN0027: malicious@unknown can't be resolved to a satisfying range
➤ YN0001: TypeError: Cannot read properties of undefined (reading 'dist')
    at Fv.getCandidates (/home/chris/.cache/node/corepack/v1/yarn/4.5.3/yarn.js:688:7154)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async Pg.getCandidates (/home/chris/.cache/node/corepack/v1/yarn/4.5.3/yarn.js:141:1271)
    at async uH (/home/chris/.cache/node/corepack/v1/yarn/4.5.3/yarn.js:401:9441)
    at async /home/chris/.cache/node/corepack/v1/yarn/4.5.3/yarn.js:401:8776
    at async C (/home/chris/.cache/node/corepack/v1/yarn/4.5.3/yarn.js:401:7127)
    at async T2 (/home/chris/.cache/node/corepack/v1/yarn/4.5.3/yarn.js:401:8456)
    at async /home/chris/.cache/node/corepack/v1/yarn/4.5.3/yarn.js:402:531
    at async Promise.all (index 0)
    at async /home/chris/.cache/node/corepack/v1/yarn/4.5.3/yarn.js:402:488

➤ Errors happened when preparing the environment required to run this command.

If all versions of a package are blocked, the output explicitly states that the package failed analysis:

➤ YN0027: malicious@unknown can't be resolved to a satisfying range
➤ YN0035: The remote server failed to provide the requested resource
➤ YN0035:   Response Code: 424 ("malicious" failed Veracode analysis)
➤ YN0035:   Request Method: GET
➤ YN0035:   Request URL: https://maven.firewall.veracode.com/malicious

Alternatively, if only a specific version is affected:

➤ YN0000: · Yarn 4.5.3
➤ YN0000: ┌ Resolution step
➤ YN0082: │ malicious@npm:1.0.0: No candidates found
➤ YN0000: └ Completed in 4s 398ms
➤ YN0000: · Failed with errors in 4s 405ms

NuGet registry​

The Package Firewall NuGet registry is based on NuGet's Server API.

dotnet​

To use the Package Firewall NuGet registry, first disable the original nuget.org registry:

dotnet nuget disable source nuget.org

Once the official registry is disabled, the Package Firewall source can be added. If you aren’t running Windows, add the --store-password-in-clear-text flag.

dotnet nuget add source https://nuget.firewall.veracode.com/v3/index.json \
    --protocol-version 3 \
    --name Veracode \
    --valid-authentication-types basic \
    --username veracode \
    --password <FIREWALL_TOKEN>
note

Do not accidentally save your token into your shell history.

A blocked package appears in dotnet output as missing:

/Demo.csproj : error NU1102: Unable to find package Example.Vulnerable with version (= 1.2.3)
/Demo.csproj : error NU1102:   - Found 42 version(s) in Veracode [ Nearest version: 2.0.0 ]

If all versions of a package are blocked, the output explicitly states that the package failed analysis:

error: NU1301: Failed to retrieve information about 'Example.Vulnerable' from remote source 'https://maven.firewall.veracode.com/v3-flatcontainer/example.vulnerable/index.json'.
error:   Response status code does not indicate success: 424 ("example.vulnerable" failed Veracode analysis).
error: Value cannot be null. (Parameter 'version')

If a version range is accepted by the manifest, the package manager automatically attempts to use a version that passes Package Firewall's policy.

nuget​

To use the Package Firewall NuGet registry, first disable the original nuget.org registry:

nuget sources Disable -Name nuget.org

Once the official registry is disabled, the Package Firewall source can be added. If you aren’t running Windows, add the --store-password-in-clear-text flag.

nuget sources Add \
    -Source https://maven.firewall.veracode.com/v3/index.json\
    -ProtocolVersion 3 \
    -Name Veracode
    -UserName veracode
    -Password <FIREWALL_TOKEN>
note

Do not accidentally save your token into your shell history.

A blocked package appears in nuget output as missing:

Package 'Example.Vulnerable 1.2.3' is not found in the following primary source(s): 'https://nuget.firewall.veracode.com/v3/index.json'. Please verify all your online package sources are available (OR) package id, version are specified correctly.

If all versions of a package are blocked, the output explicitly states that the package failed analysis:

Feeds used:
  https://nuget.firewall.veracode.com/v3/index.json

Installing package 'Example.Vulnerable' to '/private/tmp/path'.
  GET https://nuget.firewall.veracode.com/v3/registration5-gz-semver2/example.vulnerable/index.json
  FailedDependency https://nuget.firewall.veracode.com/v3/registration5-gz-semver2/example.vulnerable/index.json 2399ms
An error occurred while retrieving package metadata for 'Example.Vulnerable' from source 'Veracode'.
  Response status code does not indicate success: 424 ("example.vulnerable" failed Veracode analysis).

If a version range is accepted by the manifest, the package manager automatically attempts to use a version that passes Package Firewall's policy.

PyPI registry​

The Package Firewall PyPI registry is based on Python's Simple repository API.

pip​

The easiest way to install a package through the Package Firewall PyPI registry is using pip's --index-url option:

pip install --index-url https://:<FIREWALL_TOKEN>@pypi.firewall.veracode.com/simple/ <requirement specifier>

To make this permanent for all pip commands, add it to the pip configuration:

pip config set global.index-url https://:<FIREWALL_TOKEN>@pypi.firewall.veracode.com/simple/
note

Do not accidentally save your token into your shell history.

A blocked package appears in pip output as missing:

ERROR: Could not find a version that satisfies the requirement <malicious> (from versions: none)
ERROR: No matching distribution found for <malicious>

If a version range is accepted by the manifest, the package manager automatically attempts to use a version that passes Package Firewall's policy.

poetry​

With Poetry, the source URL can be configured per-project in the pyproject.toml file by using the following commands from within the project directory:

poetry source add --priority primary Veracode https://pypi.firewall.veracode.com/simple/
poetry config http-basic.veracode "veracode" "<FIREWALL_TOKEN>"
note

Do not accidentally save your token into your shell history.

A blocked package appears in poetry output as missing:

Could not find a matching version of package <malicious>

If all versions of a package are blocked, the output explicitly states that the package failed analysis:

424 Client Error: Failed Dependency for url: https://pypi.firewall.veracode.com/simple/malicious/

If a version range is accepted by the manifest, the package manager automatically attempts to use a version that passes Package Firewall's policy.

RubyGems registry​

The Package Firewall RubyGems registry is based on Ruby's compact index API.

bundle​

A mirror for Ruby's default repository can be configured using bundle config. Set a fallback timeout of 9999 to prevent Ruby from silently falling back to the official registry if the Package Firewall mirror goes down.

bundle config set --global mirror.https://rubygems.org https://rubygems.firewall.veracode.com
bundle config set --global mirror.https://rubygems.org.fallback_timeout 9999

After you set up the mirror, provide the Package Firewall API key for authorization:

bundle config set --global rubygems.firewall.veracode.com veracode:<FIREWALL_TOKEN>
note

Do not accidentally save your token into your shell history.

A blocked package appears in bundle output as missing:

Could not find gem 'bad_gem' with platform 'x86_64-linux' in rubygems repository https://rubygems.org/ or installed locally.
Last updated on