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, search the same logs by package name and ask for complete entries:

bsfw logs --all-users --firewall <firewall-id> --search <package-name> -o json

--all-users matters here: someone else hit the block, and without it you only see your own requests. If the report came from CI, narrow further 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.

To see the findings behind the decision without replaying the install, ask about the exact version the client wanted. The version has to be exact, no ranges:

bsfw package <ecosystem> <package-name> <version> -o json

This is the same vulnerability and malware data the rules evaluate, so it also answers whether a newer version is clean. An absent malware result means unknown, not proof that the package is clean.

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