Configure the Package Firewall with direct integration

This setup is a package manager client deployment. Direct integration routes package installation requests from your package manager clients through the Package Firewall directly, without a private package registry such as JFrog Artifactory, Google Artifact Registry, or Sonatype Nexus Repository. The Package Firewall evaluates each package request based on the malware check and the configured Package Firewall policy conditions, and handles each request in one of three ways:

Block the installation and return an HTTP 403 when the package is in the Endor Labs malware database, or a policy condition matches Block. The developer sees a generic 403 response without the specific reason. The Package Firewall records a log with the package, version, and reason.
Allow the installation if a policy condition matches with Warn. The Package Firewall records a warning log with the package, version, and reason.
Allow the installation if no malware is detected. No log is recorded.

The Package Firewall records one of the following reasons in the log when it blocks a package:

malware detected for package <name>@<version>: Endor Labs classified the package as malware.
package has a CVSS vulnerability at or above the configured severity threshold: The package has a known vulnerability at or above the CVSS severity threshold set in your policy. Endor Labs uses CVSS 3.x by default and evaluates vulnerability severity using that version. You can change the CVSS version for your namespace in system settings.
package license is restricted: The license violates your Package Firewall policy.
package does not meet min_age_hours requirement: The package is newer than the minimum age set in your policy.

Configure the direct integration for Package Firewall if your organization does not use a private package registry such as JFrog Artifactory, Google Artifact Registry, or Sonatype Nexus Repository. IT administrators can use Mobile Device Management (MDM) scripts to deploy Package Firewall configurations to developer machines, eliminating the need for manual setup on each machine. These scripts update package manager configuration files with the Package Firewall URL and credentials. They also encode an attribution label into those credentials, so the firewall attributes every request to a developer and machine instead of the shared API key. The label defaults to <user>@<machine>, and you can customize it. See User attribution to learn how the label works. The Package Firewall logs show the attributed user on each event, so you can identify who requested a warned or blocked package. See View Package Firewall logs to learn more.

Package Firewall support matrix

The following table outlines the package manager clients and ecosystems the Package Firewall supports through direct integration.

Configure the Package Firewall

Complete the following steps to configure direct integration with the Package Firewall:

Create an API key for the Package Firewall.
Configure your package manager configuration file.
Verify your setup.

Create an API key for the Package Firewall

Create an API key dedicated to the Package Firewall so that can authenticate to it. You can create it through one of the following methods:

Using the Endor Labs user interface, with the Package Firewall User role. See API keys to learn more.
Using endorctl, with the SYSTEM_ROLE_PACKAGE_FIREWALL role. Make sure to install and configure endorctl before you create the key.

To create the key using endorctl, run the following command and replace:

<namespace> with your namespace.
<API key name> with the name of the API key for the Package Firewall use case.
<YYYY-MM-DDTHH:MM:SSZ> with the API key expiration in ISO 8601 UTC format, for example 2026-12-31T23:59:59Z.

export NAMESPACE="<namespace>"
export KEY_NAME="<API key name>"

endorctl api create -r APIKey -n "$NAMESPACE" --data '{
  "meta": { "name": "'"$KEY_NAME"'" },
  "spec": {
    "permissions": { "roles": ["SYSTEM_ROLE_PACKAGE_FIREWALL"] },
    "expiration_time": "<YYYY-MM-DDTHH:MM:SSZ>"
  },
  "propagate": true
}'

From the response, save the following values in a secure location. Use them as your Package Firewall credentials when you configure your package manager configuration file.

API key: spec.key
API secret: spec.secret

Configure your package manager configuration file

Configure your package manager configuration file with the Package Firewall URL, your API key as the username, and your API secret as the password. The Package Firewall authenticates installation requests by validating the username and password pair. Replace <api-key> and <api-secret> with the credentials you saved in the previous step.

Verify your setup

To verify your setup, install a package that Endor Labs has classified as malware. The Package Firewall should block the installation and return an HTTP 403. The following examples show the test command for each package manager client.

npm

Run the following command to test the Package Firewall with npm.

npm install endor-firewall-test@1.0.0

When the Package Firewall blocks the package, the output looks similar to the following. The 403 Forbidden response confirms that the firewall blocked the package.

npm error 403 403 Forbidden - GET https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz - Forbidden
npm error 403 In most cases, you or one of your dependencies are requesting a package version that is forbidden by your security policy, or on a server you do not have access to.
npm error A complete log of this run can be found in: /Users/johndoe/.npm/_logs/2026-06-04T15_04_29_131Z-debug-0.log

pnpm

Run the following command to test the Package Firewall with pnpm.

pnpm add endor-firewall-test@1.0.0

When the Package Firewall blocks the package, the output looks similar to the following. The Forbidden - 403 response confirms that the firewall blocked the package.

Packages: +1
+
[ERR_PNPM_FETCH_403] GET https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz: Forbidden - 403

This error happened while installing a direct dependency of /Users/local-dev/Code/sample-projecr

//factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/:_auth=ZW5k[hidden]
//factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/:_username=xxxxx
//factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/:_password=[hidden]
Progress: resolved 1, reused 0, downloaded 0, added 0

Yarn Classic (v1)

Run the following command to test the Package Firewall with Yarn Classic.

yarn add endor-firewall-test@1.0.0

When the Package Firewall blocks the package, the output looks similar to the following. The Forbidden - 403 response confirms that the firewall blocked the package.

yarn add v1.22.22
info No lockfile found.
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
error Error: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz: Request failed "403 Forbidden"
    at ResponseError.ExtendableBuiltin (/Users/johndoe/.nvm/versions/node/v24.6.0/lib/node_modules/yarn/lib/cli.js:696:66)
    at new ResponseError (/Users/johndoe/.nvm/versions/node/v24.6.0/lib/node_modules/yarn/lib/cli.js:802:124)
    at Request.<anonymous> (/Users/johndoe/.nvm/versions/node/v24.6.0/lib/node_modules/yarn/lib/cli.js:66750:16)
    at Request.emit (node:events:508:28)
    at module.exports.Request.onRequestResponse (/Users/johndoe/.nvm/versions/node/v24.6.0/lib/node_modules/yarn/lib/cli.js:142287:10)
    at ClientRequest.emit (node:events:508:28)
    at HTTPParser.parserOnIncomingClient (node:_http_client:772:27)
    at HTTPParser.parserOnHeadersComplete (node:_http_common:117:17)
    at TLSSocket.socketOnData (node:_http_client:614:22)
    at TLSSocket.emit (node:events:508:28)
info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command.

Yarn Berry (v2+)

Run the following command to test the Package Firewall with Yarn Berry.

yarn add endor-firewall-test@1.0.0

When the Package Firewall blocks the package, the output looks similar to the following. The 403 (Forbidden) response confirms that the firewall blocked the package.

➤ YN0000: · Yarn 4.16.0
➤ YN0000: ┌ Resolution step
➤ YN0085: │ + endor-firewall-test@npm:1.0.0
➤ YN0000: └ Completed
➤ YN0000: ┌ Fetch step
➤ YN0035: │ endor-firewall-test@npm:1.0.0: The remote server failed to provide the requested resource
➤ YN0035: │   Response Code: 403 (Forbidden)
➤ YN0035: │   Request Method: GET
➤ YN0035: │   Request URL: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz
➤ YN0000: └ Completed in 0s 839ms
➤ YN0000: · Failed with errors in 0s 853ms

Bun

Run the following command to test the Package Firewall with Bun.

bun add endor-firewall-test@1.0.0

When the Package Firewall blocks the package, the output looks similar to the following. The 403 response confirms that the firewall blocked the package.

bun add v1.3.14 (0d9b296a)
error: GET https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/npm/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz - 403

pip

Run the following command to test the Package Firewall with pip.

pip install endor-firewall-test==1.0.0

When the Package Firewall blocks the package, the output looks similar to the following. The 403 response confirms that the firewall blocked the package.

Looking in indexes:
https://<credentials>@factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/simple/

Collecting endor_firewall_test==1.0.0

ERROR: HTTP error 403 while getting:
https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata

ERROR: 403 Client Error: Forbidden for URL:
https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata

Run the following command to test the Package Firewall with uv.

uv pip install endor-firewall-test==1.0.0

When the Package Firewall blocks the package, the output looks similar to the following. The (403 Forbidden) response confirms that the firewall blocked the package.

error: Failed to fetch:
https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata

Caused by:

HTTP status client error (403 Forbidden) for URL:
https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata

Poetry

Run the following command to test the Package Firewall with Poetry.

poetry add endor-firewall-test==1.0.0

When the Package Firewall blocks the package, the output looks similar to the following. The 403 Forbidden response confirms that the firewall blocked the package.

Updating dependencies
Resolving dependencies... (0.8s)
Source (endor-firewall): Failed to retrieve metadata at:
https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata

Resolving dependencies... (2.8s)
Source (endor-firewall): Failed to retrieve metadata at:
https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata

Resolving dependencies... (3.9s)
Source (endor-firewall): Failed to retrieve metadata at:
https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl.metadata

Resolving dependencies... (4.2s)

403 Client Error: Forbidden for URL:
https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/pypi/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl

Run the following command to test the Package Firewall with Go.

go install github.com/endorlabstest/endor-firewall-test@v1.0.0

When the Package Firewall blocks the package, the output looks similar to the following. The 403 Forbidden response confirms that the firewall blocked the package.

go: github.com/endorlabstest/endor-firewall-test@v1.0.0:
reading https://<credentials>@factory.endorlabs.com/v1/namespaces/johndoe/firewall/go/github.com/endorlabstest/endor-firewall-test/@v/v1.0.0.info:
403 Forbidden

Maven

Add io.github.endorlabs:endor-java-webapp-demo:4.1 as a dependency in your pom.xml, then run one of the following commands to test the Package Firewall with Maven.For a project-level settings.xml in your project directory, pass it explicitly with -s:

mvn dependency:resolve -s settings.xml

For a global settings.xml at ${mvn_home}/conf/settings.xml, Maven picks it up automatically:

mvn dependency:resolve

When the Package Firewall blocks the package, the output looks similar to the following. The Forbidden (403) response confirms that the firewall blocked the package.

[INFO] Scanning for projects...
[INFO]
[INFO] -----------------------< com.example:my-app >------------------------
[INFO] Building my-app 1.0.0
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
Downloading from endor-firewall: https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/maven/io/github/endorlabs/endor-java-webapp-demo/4.1/endor-java-webapp-demo-4.1.pom
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  1.600 s
[INFO] Finished at: 2026-06-09T19:37:32+05:30
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal on project my-app: Could not collect dependencies for project com.example:my-app:jar:1.0.0
[ERROR] Failed to read artifact descriptor for io.github.endorlabs:endor-java-webapp-demo:jar:4.1
[ERROR] 	Caused by: The following artifacts could not be resolved: io.github.endorlabs:endor-java-webapp-demo:pom:4.1 (absent): Could not transfer artifact io.github.endorlabs:endor-java-webapp-demo:pom:4.1 from/to endor-firewall (https://factory.endorlabs.com/v1/namespaces/johndoe/firewall/maven): status code: 403, reason phrase: Forbidden (403)
[ERROR]

Store Package Firewall credentials as CI/CD secrets

Store your Package Firewall API key and API secret as secrets in your CI/CD system, such as repository or runner secrets. Expose them to pipeline jobs as environment variables. Don’t write credentials directly in pipeline steps or commit them to your repository. The following table maps each package manager configuration file to the environment variables it reads. The uv and Poetry variable names derive from the endor-firewall index or source name used in the following sections. To store secrets and map them to environment variables, refer to the documentation for your CI/CD system, for example GitHub Actions, GitLab CI/CD, Azure DevOps, CircleCI, Jenkins, or Harness.

Configure uv for CI/CD

When you run uv lock with the Package Firewall configured, uv writes the Firewall URL, including your namespace, into uv.lock. Every package resolves through Endor Labs instead of a canonical PyPI source. Since the lockfile references authenticated Firewall URLs, reproducible installs fail in CI/CD when credentials to factory.endorlabs.com are absent. uv commands that require a connection to the lockfile URLs, such as uv sync --locked or uv sync --frozen, return 401 Unauthorized unless credentials are provided. To install from the lockfile in CI/CD without committing credentials to your repository, give your index a name and pass the credentials as environment variables.

In your existing uv index in pyproject.toml or uv.toml, add a name and remove the credentials from the URL. uv matches credentials to an index by this name.

pyproject.toml

[[tool.uv.index]]
name = "endor-firewall"
url = "https://factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/pypi/simple/"
default = true

uv.toml

[[index]]
name = "endor-firewall"
url = "https://factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/pypi/simple/"
default = true

In your CI/CD system, store the credentials as secrets and expose them to jobs as the following environment variables. uv derives the variable names from the index name in uppercase, so endor-firewall becomes ENDOR_FIREWALL. For more information, refer to the uv environment variable reference.
- UV_INDEX_ENDOR_FIREWALL_USERNAME: Your Package Firewall API key.
- UV_INDEX_ENDOR_FIREWALL_PASSWORD: Your Package Firewall API secret.

Configure npm for CI/CD

When you run npm install with the Package Firewall configured, npm writes the Firewall URL, including your namespace, into package-lock.json. Every package resolves through Endor Labs instead of a canonical npm registry. Since the lockfile references Firewall URLs, reproducible installs fail in CI/CD when credentials to factory.endorlabs.com are absent. Commands that install from the lockfile, such as npm ci, return 401 Unauthorized unless credentials are provided. To install from the lockfile in CI/CD without committing credentials to your repository, keep the registry URL in .npmrc and pass the encoded credentials as an environment variable.

In the project .npmrc file, set the Package Firewall registry and read _auth from an environment variable.

registry=https://factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/npm/
//factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/npm/:_auth=${NPM_AUTH}
always-auth=true

Generate the Base64 encoding of <api-key>:<api-secret> with your Package Firewall API key and API secret. This is the same encoding as the configuration wizard.
echo -n "<api-key>:<api-secret>" | base64
In your CI/CD system, store the encoded value as a secret and expose it to jobs as the NPM_AUTH environment variable. For more information, refer to the npm CI/CD documentation.

Configure pnpm for CI/CD

pnpm reads the same .npmrc registry as npm. When that file points at Package Firewall, pnpm install and pnpm add go through Endor Labs. By default, pnpm-lock.yaml stores integrity hashes and does not store tarball URLs. Set the same .npmrc credentials in CI/CD as you do for npm. See Configure npm for CI/CD to set NPM_AUTH. Commands such as pnpm install --frozen-lockfile then resolve through Package Firewall. If the lockfile-include-tarball-url setting is true, pnpm writes Firewall tarball URLs into pnpm-lock.yaml. Reproducible installs then return 401 Unauthorized when credentials to factory.endorlabs.com are absent.

Configure Poetry for CI/CD

When you run poetry lock with Package Firewall set as a source, Poetry writes the Firewall URL, including your namespace, into poetry.lock. Every package resolves through Endor Labs instead of a canonical PyPI source. Since the lockfile references Firewall URLs, reproducible installs fail in CI/CD when credentials to factory.endorlabs.com are absent. Commands that install from the lockfile, such as poetry install, return 401 Unauthorized unless credentials are provided. To install from the lockfile in CI/CD without committing credentials to your repository, keep the source URL in pyproject.toml and pass the credentials as environment variables.

In pyproject.toml, add the Package Firewall source with a name and no credentials in the URL. Poetry matches credentials to a source by this name.

[[tool.poetry.source]]
name = "endor-firewall"
url = "https://factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/pypi/simple/"
priority = "primary"

In your CI/CD system, store the credentials as secrets and expose them to jobs as the following environment variables. Poetry derives the variable names from the source name in uppercase, so endor-firewall becomes ENDOR_FIREWALL. For more information, refer to the Poetry repositories documentation.
- POETRY_HTTP_BASIC_ENDOR_FIREWALL_USERNAME: Your Package Firewall API key.
- POETRY_HTTP_BASIC_ENDOR_FIREWALL_PASSWORD: Your Package Firewall API secret.

Next steps

Configure which packages the firewall flags and how it responds. See Package Firewall policy to learn more.
Review the events the firewall records. See View Package Firewall logs to learn more.

Introduction

Set up

Configure

Operate

Configure the Package Firewall with direct integration

Package Firewall support matrix

Configure the Package Firewall

Create an API key for the Package Firewall

Configure your package manager configuration file

Verify your setup

Store Package Firewall credentials as CI/CD secrets

Configure uv for CI/CD

Configure npm for CI/CD

Configure pnpm for CI/CD

Configure Poetry for CI/CD

Next steps

​Package Firewall support matrix

​Configure the Package Firewall

​Create an API key for the Package Firewall

​Configure your package manager configuration file

​Verify your setup

​Store Package Firewall credentials as CI/CD secrets

​Configure uv for CI/CD

​Configure npm for CI/CD

​Configure pnpm for CI/CD

​Configure Poetry for CI/CD

​Next steps

Package Firewall support matrix

Configure the Package Firewall

Create an API key for the Package Firewall

Configure your package manager configuration file

Verify your setup

Store Package Firewall credentials as CI/CD secrets

Configure uv for CI/CD

Configure npm for CI/CD

Configure pnpm for CI/CD

Configure Poetry for CI/CD

Next steps