Investigate a blocked install

A developer or a CI job reports a failed install. This guide takes you from the error message to the responsible rule to a resolution.

1. Recognize the two failure shapes

Download blocked. The client got an explicit block: an error response from the firewall naming the package and a request ID. The rule behind it can sit on either the download or the versions phase, since an artifact request is evaluated against both. With npm, for example:

lodash@4.17.20 is blocked. Check firewall log entries for request <request-id> for details

The request ID in the message identifies the matching log entry. The named package is the one that was blocked, which is often a transitive dependency rather than the package that was installed. Each ecosystem page shows the exact error per package manager.

Version filtered. The client reports a version as not found even though it exists on the public registry. A rule on the versions phase filtered it out of the metadata the client resolved against, most commonly a delay rule. There is no request ID in the client error; search the logs by package name.

2. Find the log entry

In the dashboard, open Logs on the firewall and search for the package. Select a likely row and compare its request field with the ID from the client error. From the terminal, list the firewall's compact log summaries:

bsfw logs --firewall <firewall-id>

If the report came from CI, filter by that pipeline's interaction ID or the Service Access Token user.

3. Read the entry

The log entry tells you:

• Rule. Which rule matched, and its description.
• Rule output. Selector-function details, for example the CVEs, CVSS, and EPSS values behind a vulnerabilities match.
• Blocked. Whether the request was actually blocked or only logged.
• User, timestamp, upstream. Who hit it, when, and where the package would have come from.

4. Resolve

Three options, in order of preference:

1. Change the dependency. If the block is legitimate (real vulnerability, malware, too-new release), the right fix is usually a different version. Often the version range already permits an older, allowed release.
2. Add an exception. The package is needed as-is and the risk is understood. Create an exception scoped to the exact package and version, with reason and expiry. This unblocks one case and leaves the rule intact.
3. Adjust the rule. Only when the log shows a pattern of false positives, not for one blocked install. Consider switching the rule to log-only while retuning.

If there is no log entry

A missing entry does not mean nothing happened. Work through these:

• The rule blocks without logging. block and log are independent effects, so a rule with { "block": true, "log": false } fails the install and records nothing. Check the firewall's rules for blocking rules with logging off; this is the one case where the client fails and the log stays empty by design.
• The request never reached the firewall. Check the client's registry config and the lockfile's resolved URLs.
• Authentication failed. A 401 happens before rule evaluation and creates no rule log entry. Check the token.

Related

• How-to: View logs, Manage exceptions
• Concept: Rule evaluation