Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.endorlabs.com/llms.txt

Use this file to discover all available pages before exploring further.

The Package Firewall is Endor Labs’ 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 enters your environment, forcing reactive cleanup. The Package Firewall closes that gap by intercepting every package installation request before it completes. Integrate Artifactory with the Package Firewall so Artifactory uses Endor Labs as the remote for public registry traffic. The Package Firewall blocks any malicious package instantly and returns an error, so it never reaches your environment. Legitimate packages pass through unchanged, keeping your developers productive and your pipeline secure. You can configure a Package Firewall policy to customize which packages the firewall flags and how it responds. The firewall can flag packages based on malware, restricted licenses, or minimum age threshold violations. For each criteria, you can choose between two responses:
  • Warn: Records the event and allows the package installation without interrupting your CI pipeline.
  • Block: Prevents the package installation entirely and returns an error.
You can also define exceptions to allow specific packages through regardless of policy. See Package Firewall policy to learn more. The Package Firewall checks every package in the dependency tree individually, including transitive dependencies. If it flags any dependency, the installation is blocked. Configured Package Firewall policies apply to transitive dependencies as well. The Package Firewall supports any package manager that uses the npm or PyPI registry, such as npm and pip.
License requirementEnsure that you have the Package Firewall license. See Licenses for more information.

​
How it works

The Package Firewall inspects package requests before serving them. 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 the firewall inspects every package request before downloading the package. The following steps describe how Package Firewall intercepts each package installation request and its response.
  1. Route traffic through the Package Firewall: Artifactory forwards each request to the Package Firewall so that the firewall evaluates every package before serving it 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. Evaluate each package request: For each package request, the Package Firewall parses the ecosystem, package name, and version, and checks it against the Endor Labs’ malware database. If a Package Firewall policy is configured, the firewall also evaluates restricted licenses, minimum package age, and exceptions before deciding on the action.
  4. Firewall decision: Based on the malware check and policy conditions, the Package Firewall either blocks package installations or allows it with a warning log. If no criteria matches, the package is allowed and no log is recorded.
    • The Package Firewall blocks the request and Artifactory returns HTTP 404 if the package is found in Endor Labs’ malware database, or if a policy condition matches with Block. The Package Firewall records an event with the package, version, and reason.
    • The Package Firewall allows the installation and redirects the client with HTTP 307 if a policy condition matches with Warn. The Package Firewall records a warning event with the package, version, and reason.
    • The Package Firewall allows the installation and redirects the client with HTTP 307 if no malware is detected. The client then downloads the package directly from the public registry through this redirect.
  5. View Package Firewall logs: Package Firewall logs the actions the firewall takes on package installation requests, which is helpful for debugging and compliance. The logs include details such as the package, version, time of the event, and the reason the package was blocked or allowed with a warning. If no criteria matches, the package is allowed and no log is recorded.

​
Prerequisites

  • You must have the Package Firewall license.
  • 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 integrate JFrog Artifactory with the Endor Labs Package Firewall:
  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. JFrog Artifactory uses this key 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. Use these credentials when you configure 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.
  1. Log in to JFrog Artifactory.
  2. Select Administration > Repositories from the left sidebar.
  3. Click Create a Repository and select Remote.
  4. Select npm as the package type. Select npm
  5. Enter a Repository Key, for example endor-firewall-npm.
  6. Enter the repository URL: https://factory.endorlabs.com/v1/namespaces/<namespace>/firewall/npm/. Replace <namespace> with your Endor Labs namespace.
  7. Enter the User Name and Password you saved when creating the API key.
  8. Click Create Remote Repository. Configure npm
  1. Log in to JFrog Artifactory.
  2. Select Administration > Repositories from the left sidebar.
  3. Click Create a Repository and select Remote.
  4. Select PyPI as the package type. Select PyPI
  5. Enter a Repository Key, for example endor-firewall-pypi.
  6. Enter the repository URL: https://factory.endorlabs.com/v1/namespaces/<namespace>/firewall/pypi/. Replace <namespace> with your Endor Labs namespace.
  7. Enter the User Name and Password you saved when creating the API key.
  8. In PyPI Settings, set Registry URL to the same URL you entered in step 6.
  9. Click Create Remote Repository. Configure 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.
    Local setup for developers

​
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.
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 E404 error code and 404 Not Found response confirm that the firewall blocked the package.
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.
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 E404 error code and 404 Not Found response confirm that the firewall blocked the package.
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. Select Findings from the left sidebar.
  2. Select Package Firewall.
  3. Select an event to view the following details:
    • Info: Package name, package version, API key, remote address, request URL, action taken, the reason the event was flagged, and when the event occurred.
    For malware events, you can also view the following:
    • Risk Details: Explanation of why the package was flagged and remediation guidance.
    • Metadata: Ecosystem, package release date, advisory published date, CWE ID, and OSV ID when available.
    • Malware Info: Malware detection record in raw JSON format.
    For minimum package age events, you can also view the package age in hours. For restricted license events, you can also view the detected package license.

​
Filter Package Firewall logs

Use filters to narrow Package Firewall logs by ecosystem, action, rule reason, or time.
  1. Select Findings from the left sidebar.
  2. Select Package Firewall.
  3. Toggle the filter panel to show the filters.
  4. Set any of the following filters to narrow the log list.
    • Ecosystem - Filter logs by their package ecosystem.
    • Action: Filter logs by the action taken on the package installation, either Warning or Blocked.
    • Reason: Filter logs by why the package was flagged, which can be Malware detected, Minimum package age not met, or Restricted license.
    • All Time - Filter logs by when the event was recorded. You can select All Time, Last Day, Last Week, Last Month, Last 60 Days, Last 90 Days, or a custom range.
    You can use the same filters to query logs through endorctl. See Query Package Firewall logs using endorctl.

​
Query Package Firewall logs using endorctl

The Package Firewall logs record every action the firewall takes on package installation requests. 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, and spec.package_version. 
    endorctl api list -r PackageFirewallLog -n <namespace> --filter 'spec.ecosystem==<ecosystem_variable> and spec.package_name=="<package_name>" and spec.package_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.
You can use a combination of filters to narrow your query.
Artifactory uses the API key created with SYSTEM_ROLE_PACKAGE_FIREWALL to route traffic through the Package Firewall. It does not grant access to the Package Firewall Log API.To query logs, create an API key with at least the Read-only role. For more information about roles and permissions, see Authorization roles.

​
Troubleshooting and FAQ

No. The Package Firewall blocks only the specific package versions that Endor Labs flags as malware in the malware database.
The Package Firewall checks each package individually when the client requests it during installation. If any dependency, direct or transitive, contains malware, the firewall blocks that specific package installation and stops the overall installation process.
No. The impact on installation time is minimal.
If Endor Labs flags a package as malware after Artifactory cached it, Artifactory continues to serve it until the cache expires. Use a short cache duration to reduce that window.
  • Verify that the Package Firewall URL in Artifactory is correct.
  • Ensure network connectivity from Artifactory to the Package Firewall.
  • Ensure the firewall rules allow outbound connections from Artifactory.
  • Verify the API key and secret are correct and that the key has the SYSTEM_ROLE_PACKAGE_FIREWALL role.
  • Ensure that the credentials are in the format Artifactory expects.
  • Check the Artifactory logs for authentication errors.
  • Verify that Artifactory has sufficient storage for the cache.
  • Set cache expiration to short durations so that more requests hit the Package Firewall.
  • Check the cache hit and miss rates. Clear the cache if you need to test with a fresh request.
The package manager resolves version ranges as usual. The Package Firewall checks the resolved version when the client requests it for download. If Endor Labs flags that version as malware, the firewall blocks the installation.