Package Firewall

The Package Firewall is Endor Lab’s SaaS solution that offers real-time protection against malicious packages during software installations. It safeguards your software supply chain by preventing malicious packages from reaching your developers. Positioned between package managers and public package registries, it automatically blocks the installation of packages containing malware while allowing safe packages to install normally.

Security teams often discover malware only after it has already been installed, forcing engineers to perform reactive cleanup. The Package Firewall closes that gap by intercepting every package request before it completes. You must configure Artifactory to route package traffic through Endor Labs as the remote source. Any package flagged as malicious is blocked instantly and returns an error, so it never reaches your environment. Legitimate packages pass through unchanged, keeping your developers productive and your pipeline secure.

The Package Firewall is supported for the following ecosystems:

• npm
• pip

How it works

The Package Firewall inspects package requests before they are served. When a developer or CI pipeline requests a package to download, the request goes to your private registry, such as JFrog Artifactory.

Configure Artifactory to use the Package Firewall URL as its remote source instead of upstream package registries. This setup ensures that every package request is inspected before the package is downloaded.

The following steps describe how traffic flows through the Package Firewall, how each package is inspected, and how blocked requests are recorded.

1. Route traffic through the Package Firewall: Artifactory forwards each request to the Package Firewall so that every package fetch is inspected before it is served to the developer or pipeline.

2. Authenticate and control access: Requests to the Package Firewall require an Endor Labs API key with the appropriate role and license.

3. Inspect each package request: For each package and version, the Package Firewall parses the ecosystem, package name, and version and checks them against Endor Labs’ malware database. The check happens in real time so the Package Firewall can allow or block the request before the client receives the package.

4. Firewall decision: Based on the malware check, the Package Firewall either blocks or allows the install.

   • If malware is detected, the Package Firewall blocks the request. Artifactory returns HTTP 404 to the client and the package is not installed. The Package Firewall also records an event with the package, version, and reason.
   • If malware is not detected, the Package Firewall allows the install and redirects the client with HTTP 307 to the upstream registry. The package is then downloaded directly from the public registry through this redirect.

5. View events and blocked packages: Package Firewall logs record blocked requests. You can review these logs for debugging and compliance. The logs include details such as blocked package, version, time of the event, and the malware detection reason.

Prerequisites

• You must have either of the following Endor Labs licenses: OSS Pro or Supply Chain.
• JFrog Artifactory with permission to create remote repositories and configure credentials.
• Download and install endorctl. See Install and configure endorctl for more information.

Configure the Package Firewall

Complete the following steps to set up the Package Firewall with JFrog Artifactory:

1. Create an API key for the Package Firewall.
2. Configure JFrog Artifactory.
3. Verify that the Package Firewall is blocking malware.
4. Query Package Firewall logs.

Create an API key for the Package Firewall

You must create an API key with the SYSTEM_ROLE_PACKAGE_FIREWALL role. This key is used by JFrog Artifactory to authenticate to the Package Firewall. 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 username and password in a secure location. These credentials are used when configuring the JFrog Artifactory remote repository.

• Username: spec.key
• Password: spec.secret

Configure JFrog Artifactory

Configure a remote repository in JFrog Artifactory so package traffic goes through the Package Firewall. Use the steps below for either npm or PyPI.

Local setup for developers

Update your package manager to use Artifactory as its source, routing all installs through the Package Firewall instead of the public registry. Once you create the Artifactory remote:

1. Navigate to Administration > Repositories.

2. Click the three vertical dots next to the repository you configured and select Set Me Up.

3. Enter Your JFrog account password if prompted.

4. Click Generate Token & Create Instructions.

5. Follow the instructions to configure your local machine, .npmrc or pip.conf, based on your package type. Refer to JFrog Artifactory documentation for more information.

6. Run the following command to verify that your local registry is pointing to the Artifactory remote. Ensure the output matches the Artifactory remote URL you configured.

   • For npm packages, run npm config get registry.
   • For PyPI packages, run pip3 config list | grep index-url.

   

Verify that the Package Firewall is blocking malware

After configuring .npmrc or pip.conf, try installing a package that Endor Labs has classified as malware. The Package Firewall blocks the installation and Artifactory returns a 404.

The following are examples of packages classified as malware in the Endor Labs.

npm install endor-firewall-test@1.0.0

npm error code E404
npm error 404 Not Found - GET https://johndoe.jfrog.io/artifactory/api/npm/johndoe/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz
npm error 404
npm error 404  The requested resource 'endor-firewall-test@https://johndoe.jfrog.io/artifactory/api/npm/johndoe/endor-firewall-test/-/endor-firewall-test-1.0.0.tgz' could not be found or you do not have permission to access it.
npm error 404
npm error 404 Note that you can also install from a
npm error 404 tarball, folder, http url, or git url.

pip install endor-firewall-test==1.0.0

Defaulting to user installation because normal site-packages is not writeable
Looking in indexes: https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/simple
Collecting endor-firewall-test==1.0.0
ERROR: HTTP error 404 while getting https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/packages/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=4df734939186708c595e72e50f5d31296d2ea9e54d5a0afc9e69d4e7d6f0d4b9 (from https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/simple/endor-firewall-test/) (requires-python:>=3.7)

ERROR: Could not install requirement endor-firewall-test==1.0.0 from https://johndoe.io/artifactory/api/pypi/johndoe/packages/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=4df734939186708c595e72e50f5d31296d2ea9e54d5a0afc9e69d4e7d6f0d4b9 because of HTTP error 404 Client Error:  for url: https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/packages/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl for URL https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/packages/packages/61/05/6e99035fec6c7e407fffc052a0060495f6a2fcae2143db3239c7399d5b6e/endor_firewall_test-1.0.0-py3-none-any.whl#sha256=4df734939186708c595e72e50f5d31296d2ea9e54d5a0afc9e69d4e7d6f0d4b9 (from https://johndoe.jfrog.io/artifactory/api/pypi/johndoe/simple/endor-firewall-test/) (requires-python:>=3.7)

View Package Firewall logs

To view Package Firewall logs in the Endor Labs user interface:

1. Sign in to Endor Labs and select Findings from the left sidebar.

2. Select Package Firewall under Events.

3. Select a blocked package to view the following details.

   • Info: Contains the package name, blocked version, API key, remote address, request type, request URL, and the timestamp when the package was blocked.
   • Risk Details: Explanation of why the package was blocked and remediation guidance.
   • Metadata: Displays the CWE ID, OSV ID, ecosystem, package release date, and advisory published date.
   • Malware Info: Provides the full malware detection record in raw JSON format.

   

Query Package Firewall logs

The Package Firewall Logs record blocked package requests as events. You can view them by querying the endorctl API.

• To list all Package Firewall logs in your namespace, run the following command. Replace <namespace> with your namespace.

  endorctl api list -r PackageFirewallLog -n <namespace>
  

• To list logs only for a specific ecosystem, add a filter.

  endorctl api list -r PackageFirewallLog -n <namespace> --filter 'spec.ecosystem==<ecosystem_variable>'
  

  Replace:

  • <ecosystem_variable> with ECOSYSTEM_NPM for npm and ECOSYSTEM_PYPI for PyPI.
  • <namespace> with your namespace.

• To list logs for a specific package in an ecosystem, use a filter with spec.ecosystem, spec.package_name, spec.version.

  endorctl api list -r PackageFirewallLog -n <namespace> --filter 'spec.ecosystem==<ecosystem_variable> and spec.package_name=="<package_name>" and spec.version=="<package_version>"'
  

  Replace:

  • <namespace> with your namespace.
  • <ecosystem_variable> with ECOSYSTEM_NPM for npm and ECOSYSTEM_PYPI for PyPI.
  • <package_name> with the package name you want to query.
  • <package_version> with the package version you want to query.

Troubleshooting and FAQ