Skip to main content
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. To view Package Firewall logs:
  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 details:
    • 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. For vulnerability events, you can also view the severity of the detected vulnerability.

​
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, ECOSYSTEM_GO for Go, and ECOSYSTEM_MAVEN for Maven.
    • <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, ECOSYSTEM_GO for Go, and ECOSYSTEM_MAVEN for Maven.
    • <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.