Skip to main content

​
Overview

The Semgrep Malware Firewall checks package downloads against Semgrep’s continuously updated malware database and blocks known malicious packages before they install on your machine.
Semgrep Malware Firewall is in private beta. To use it, you need an active Semgrep account and Semgrep Guardian enabled. Contact Semgrep Support if you need access.
The firewall runs locally on each developer machine as a lightweight client proxy. It sits in front of package installs and gates downloads on a verdict from Semgrep’s backend.

​
Prerequisites

To use the Semgrep Malware Firewall, you must meet the following requirements:
  • Have an active Semgrep account
  • Enable Semgrep Guardian
  • Have access to a macOS or Linux terminal or shell

​
Supported package managers

The firewall monitors package-manager traffic to known registries, not source code in your repository. When a package manager fetches an artifact, the firewall checks the specific package version before the download completes.

​
Install and verify

You can install the firewall with the Semgrep Guardian skill or manually with the install script. If you already use Semgrep Guardian, the /install-mfw skill is the quickest path, which installs and configures everything for you.
Semgrep Guardian ships with an /install-mfw skill that installs and sets up the firewall for you.
1
In your AI coding agent with the Semgrep Guardian plugin installed (such as Claude Code), run:
2
Follow the prompts. The skill downloads the mfw client, adds a local certificate authority to your trust store, sets up shell integration and a background daemon, and walks you through signing in.
3
Restart your Terminal / shell so the proxy environment variables take effect.
Verify the install:
You should see:

​
Test the firewall

Use a known-safe demo package to confirm that the firewall blocks malicious installs without touching real malware.
1
Open or create a test directory and initialize a project:
2
Attempt to install the demo malware package:
3
Expected result: the install is blocked. The firewall should intercept and reject the package.
The install should be blocked by the Semgrep Malware Firewall. If the install succeeds, the firewall isn’t intercepting traffic correctly. Review the mfw doctor output, and see Troubleshooting. Optional: repeat the test with pip:
If you run both tests, both installation attempts should be blocked.
The demo malware package is published to PyPI only. There’s no equivalent artifact on Maven Central yet, so Java (Maven and Gradle) installs can’t be checked with a demo package. Use mfw doctor to confirm the firewall is active, and see Check a dependency to query the backend for a specific Maven coordinate.

​
Check a dependency

Use mfw api to determine whether a specific version of a package is malicious. Python example:
Java example:
For Java, the ecosystem is maven (for both Maven and Gradle projects) and the package name is the groupId:artifactId coordinate, such as com.google.guava:guava.

​
View firewall activity

Semgrep AppSec Platform shows basic firewall reporting, including scanned and blocked dependencies, in the Malware firewall section of the Dashboard.

​
How the firewall works

The firewall has three parts:
  1. A lightweight client proxy that runs on every machine. You set it up once with mfw install. For most package managers, it sets the standard proxy environment variables HTTP_PROXY and HTTPS_PROXY so they respect it automatically; no per-tool configuration is needed. For example, you don’t need to set up tool.uv.index manually for uv. It watches traffic to known package registry URLs such as registry.npmjs.org (npm) and repo.maven.apache.org (Maven Central), identifies package-download requests (including tarballs, wheels, JARs, and similar artifacts), and gates those requests on a response from the Semgrep backend before the download completes. All other traffic is proxied through transparently.
  2. The Semgrep-operated malware firewall backend, which receives requests from the local proxy containing an ecosystem, package name, and version, and replies with a verdict.
  3. The malware database, continuously updated from a variety of threat feeds and maintained by Semgrep’s security research team.

​
Request cycle

  1. On install, the firewall runs mfw login to sign you in. Each verdict request is then authenticated with a short-lived bearer token.
  2. When you run a normal package install, the local proxy intercepts every package the installer tries to fetch.
  3. The proxy asks the Semgrep backend whether the specific version of that package is malicious.
  4. The backend matches the version to the malware database and returns a verdict.
  5. If the package is safe, the install proceeds normally. If it matches known malware, the proxy blocks the download and reports why.

​
Limitations and special cases

​
Maven and Gradle proxy behavior

Java build tools don’t read HTTP_PROXY or HTTPS_PROXY. Instead, mfw routes them through command-line shims:
  • Maven: a generated --global-settings file, applied automatically on each run
  • Gradle: JVM proxy system properties, applied automatically on each run
You still don’t configure anything by hand. Only mvn and Gradle commands invoked from your shell are gated.

​
Existing Gradle dependencies aren’t re-fetched

Gradle keys its cache by checksum. Dependencies already in ~/.gradle/caches aren’t re-fetched, so coverage starts at the next cache miss.

​
User-configured proxies bypass gating

If a build already sets its own proxy (for example, systemProp.https.proxyHost in gradle.properties, or an active <proxy> in your Maven settings.xml), mfw doesn’t gate that run rather than override the existing configuration.

​
No built-in cooldown configuration

The firewall doesn’t currently support configuring a cooldown period before a newly published package version can be installed. You can configure cooldowns at the package-manager level. See cooldowns.dev for a guide across ecosystems.

​
How quickly malware data is updated

  • For active, high-severity supply chain incidents, Semgrep’s security research team works to issue and deploy an advisory as soon as a threat is identified rather than waiting for it to be published to sources like the Open Source Vulnerabilities (OSV) database.
  • For all other findings, the malware database syncs from OSV every 2 hours.

​
Troubleshooting

​
Uninstall the firewall

To remove the firewall and its proxy configuration from a machine:
This clears the HTTP_PROXY and HTTPS_PROXY environment variables that mfw install configured and removes the local proxy process. Restart your terminal or shell afterward to confirm that the variables are cleared. To verify removal:
It should no longer report Semgrep mfw is protecting this machine ✅.