Block malware

Evaluate downloaded and published package artifacts for malware findings and block at a chosen confidence level.

The malware selector function evaluates findings from malicious-package intelligence and package-content analysis. It runs where the artifact is available: the download phase for installs and the upload phase for publishes. A version-metadata rule cannot do this.

Two options shape a rule: how weak a finding may be and still match (confidence), and how much the rule waits for before it decides (effort).

Add the rules

In the dashboard, open the firewall, go to Rules, and create a rule:

Execution phase: download
Selector function: Malware
Minimum confidence: Known malware
Effort: Known findings only
Effect: block and log

If the firewall receives publishes, add the same rule on the upload phase, so infected artifacts cannot enter your own registry through you. That rule is also the best candidate for a higher effort, see Choose the effort.

As JSON:

[
  {
    "id": "block-malware-download",
    "executionPhase": "download",
    "selector": {
      "function": {
        "name": "malware",
        "options": { "minimumConfidence": "known_malware", "effort": "known" }
      }
    },
    "ruleEffect": { "block": true, "log": true },
    "description": "Block malicious artifacts on download"
  },
  {
    "id": "block-malware-upload",
    "executionPhase": "upload",
    "selector": {
      "function": {
        "name": "malware",
        "options": { "minimumConfidence": "known_malware", "effort": "known" }
      }
    },
    "ruleEffect": { "block": true, "log": true },
    "description": "Block malicious artifacts on publish"
  }
]

To apply the JSON without the dashboard: export the config with bsfw config export, add the rules to the rules array, and import it back. See config import.

Choose the confidence level

minimumConfidence is the weakest finding that matches:

Config value	Dashboard label	Matches
`known_malware`	Known malware	Definitive findings only. Default when the option is omitted
`suspicious`	Suspicious or stronger	Suspicious and known-malware findings
`weak_indicator`	Any indicator	Every finding, including weak indicators

Start with Known malware and a blocking effect. If you lower the threshold, use a log-only rule first to review the additional matches before enabling block.

Choose the effort

effort is how much the rule waits for before it decides:

Config value	Dashboard label	The rule decides on	Effect on the request
`known`	Known findings only	Findings that already exist for the artifact: malicious-package intelligence, plus content analysis that has already been done. Default when the option is omitted	Nothing to wait for
`deep`	Wait for deep analysis	The same, and it has the artifact's contents analyzed as part of the request, waiting for that result	Slower. The first request for an artifact nobody has analyzed yet waits for the whole analysis

Effort and confidence are independent. Effort decides how much is known when the rule runs, confidence decides how weak a finding may be and still match.

known is the default, so a rule created without a thought about effort does not hold up installs. deep is the deliberate choice, and worth sizing before you make it: that first analysis can take minutes on a large package. Requests that follow are faster, because the result exists by then.

Publishes are usually the better place to spend that time than installs. A publish is one request by one person who is already waiting for a pipeline, while an install is every developer and every CI job. Set the upload rule to Wait for deep analysis and leave the download rule on Known findings only, and only take the download rule to deep for a firewall where a slow install is acceptable.

{
  "id": "block-malware-upload",
  "executionPhase": "upload",
  "selector": {
    "function": {
      "name": "malware",
      "options": { "minimumConfidence": "known_malware", "effort": "deep" }
    }
  },
  "ruleEffect": { "block": true, "log": true },
  "description": "Block malicious artifacts on publish, after full analysis"
}

What a match looks like

The install fails as a blocked download (see your ecosystem page for the exact client error). The log entry's message identifies the package and finding summary:

Malware detected in <ecosystem>/<package>@<version>: <finding summary>

The rule output carries:

Field	Meaning
`malware`	Finding summary
`scanner`	Detection source
`confidence`	`known_malware`, `suspicious`, or `weak_indicator`
`signals`	Evidence for the finding, such as a signature or advisory reference

If you believe it is a false positive

Do not disable the rule. Add an exception scoped to the exact package and version, with a short expiry and a reason, and report the package to support@bytesafe.dev so the verdict can be reviewed. An exception on the malware rule does not exempt the package from your other rules, and it stops applying when it expires, so the block returns by itself if the verdict turns out to be correct.

Concept: Rule evaluation
Reference: Selector functions
How-to: Manage exceptions, Investigate a blocked install