Configure the Package Firewall with direct integration

Direct integration routes package installation requests from your package managers through the Package Firewall directly, without an intermediary registry such as JFrog Artifactory or Google Artifact Registry. 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 registry such as JFrog Artifactory or Google Artifact Registry. 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 a <user>@<machine> label into those credentials, so the firewall attributes every request to a developer and machine instead of the shared API key. 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 managers 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.

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]

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

Set the credentials as environment variables in your CI/CD environment. uv derives the variable names from the index name in uppercase, so endor-firewall becomes ENDOR_FIREWALL. Use your Package Firewall API key as the username and your API secret as the password. For more information, refer to the uv environment variable reference.
export UV_INDEX_ENDOR_FIREWALL_USERNAME=<api-key> export UV_INDEX_ENDOR_FIREWALL_PASSWORD=<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

Configure uv 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

​Configure uv 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

Configure uv for CI/CD

Next steps