Skip to main content
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 blocks the installation of known malicious packages by default 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 this gap by intercepting every package installation request before it completes. It blocks any malicious package instantly and returns an error, so the package 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 criterion, 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 packages to bypass all Package Firewall checks, ensuring critical builds and critical workflows which depend on these packages continue uninterrupted. 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.

​
How it works

The Package Firewall inspects each package request before the package is downloaded. When a developer or CI pipeline requests a package, the request routes through the Package Firewall, either directly or through a private registry such as JFrog Artifactory.
  1. Route traffic through the Package Firewall: Your package manager or private registry forwards each request to the Package Firewall so that it evaluates every package before the download completes.
  2. Authenticate and control access: The Package Firewall verifies that each request presents an Endor Labs API key with the Package Firewall User role.
  3. Evaluate each package request: For each 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. Take action: Based on the malware check and policy conditions, the Package Firewall takes the configured action on the request and records an event with the package, version, and reason. When a package passes all checks, the installation proceeds and no log is recorded.
  5. Package Firewall logs: Package Firewall records 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 firewall flagged the package.

​
Configure the Package Firewall

You can route package installations through the Package Firewall in two ways. Choose the integration that fits your environment.

Direct integration

Direct integration routes installation requests from your machine through the Package Firewall directly, without an intermediary registry.

JFrog Artifactory

JFrog Artifactory uses the Package Firewall as its remote source instead of upstream package registries. Use this approach when your organization already uses Artifactory for package distribution.

​
View Package Firewall logs

To view Package Firewall logs in the Endor Labs application:
  1. Select Package Firewall from the left sidebar.
  1. 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 Package Firewall from the left sidebar.
  2. Toggle the filter panel to show the filters.
  3. 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, ECOSYSTEM_PYPI for PyPI, and ECOSYSTEM_GO for Go.
    • <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, ECOSYSTEM_PYPI for PyPI, and ECOSYSTEM_GO for Go.
    • <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.
The API key created with SYSTEM_ROLE_PACKAGE_FIREWALL routes 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.
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.