Skip to main content
Package Firewall records the actions it takes on package installation requests, providing an audit trail for debugging and compliance. The logs include details such as the package name, version, event time, the reason the package was flagged, and the user who initiated the request. To view Package Firewall logs:
  1. Select Package Firewall from the left sidebar.
  2. Select an event to view the package name, when the event occurred, and the following details:
    • Request details: The request type and request URL, and who made the request: user attribution, API key, and remote address.
    • Action: The action taken and the reason the event was flagged. The reason shows the policy setting that applied at that time, such as the minimum package age, the CVSS severity threshold, or the restricted license that matched. Older events show only the reason.
    • Log raw data: The full log entry in JSON format.
    User Attribution shows who made the request. The client adds this label to the Package Firewall credentials it sends, and the MDM deployment scripts use <user>@<machine> by default. The label is free-form, so each deployment reports whatever value it sets. See User attribution to learn more. For malware events, you can also view the following details:
    • Malware risk details: Explanation of why the package was flagged, the reasoning behind it, and remediation guidance.
    • Malware metadata: Package release date, advisory published date, CWE ID, and OSV ID when available.
    For minimum package age events, you can also view the following details:
    • Actual package age: How old the package version was when the request was made, in hours.
    • Eligible by: The date and time when the package version becomes old enough to pass your minimum package age policy. Requests for this version after this time are not blocked for package age.
    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. For package not evaluated events, the reason also shows whether the policy fails close or fails open, such as Package not evaluated : Fail-close. Older events, and events where Package Firewall could not read your policy settings or find the package’s registry metadata, show only Package not evaluated. Package not evaluated event For curated events, you can also view the list of unsafe versions that were blocked, each labeled with its reason for blocking, either malware or minimum package age. Versions blocked for minimum package age also show the package age, the minimum age, and the date when the version becomes eligible. See Allow safe versions to learn more. Curated events
For VS Code extensions, the Package Firewall records only malware and minimum package age events.

​
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, Blocked, or Allowed safe versions.
    • Reason: Filter logs by why the package was flagged, which can be Malware, Minimum Package Age, Restricted License, Vulnerability, Curated, or Package not evaluated.
    • 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.
    Curated events with the Allowed safe versions action are hidden by default. Select Curated in the Reason filter to view those logs.
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.
  • To list logs only for a specific ecosystem, add a filter.
    Replace:
    • <ecosystem_variable> with ECOSYSTEM_NPM for npm, ECOSYSTEM_PYPI for PyPI, ECOSYSTEM_GO for Go, ECOSYSTEM_MAVEN for Maven, ECOSYSTEM_NUGET for NuGet, ECOSYSTEM_GEM for RubyGems, and ECOSYSTEM_VSCODE for VS Code.
    • <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.
    Replace:
    • <namespace> with your namespace.
    • <ecosystem_variable> with ECOSYSTEM_NPM for npm, ECOSYSTEM_PYPI for PyPI, ECOSYSTEM_GO for Go, ECOSYSTEM_MAVEN for Maven, ECOSYSTEM_NUGET for NuGet, ECOSYSTEM_GEM for RubyGems, and ECOSYSTEM_VSCODE for VS Code.
    • <package_name> with the package name you want to query.
    • <package_version> with the package version you want to query.
  • To list logs attributed to a specific developer, use a filter with spec.user.
    Replace:
    • <namespace> with your namespace.
    • <attributed-user> with the exact attribution label you want to query, such as <user>@<machine> from the MDM scripts or an email address from a JFrog worker.
  • To count events for each attributed user, group logs by spec.user. Replace <namespace> with your namespace.
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.