Skip to main content
Semgrep Malware Firewall is in private beta.
The Semgrep Malware Firewall blocks known malicious packages before they install on employee machines. A lightweight client proxy on each machine intercepts package downloads, checks the requested version against Semgrep’s continuously updated malware database, and allows or blocks the install based 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
  • Have access to a macOS or Linux terminal or shell

​
Supported package managers

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

​
Install and verify

Semgrep Guardian and the Semgrep Malware Firewall protect different components of the development workflow.
  • Guardian scans code generated by AI coding agents before it is committed.
  • Semgrep Malware Firewall blocks malicious packages when developers install dependencies on their local machine.
Installing through Semgrep Guardian is recommended. The /install-mfw skill installs and configures the firewall for you. You can also install the firewall manually.
Semgrep Guardian ships with an /install-mfw skill that installs and sets up the firewall for you.
1
In Claude Code or another AI coding agent that has Semgrep Guardian installed, 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 so it loads the HTTP_PROXY and HTTPS_PROXY environment variables.
To verify the install, run:
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 firewall should block the install. 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, the firewall should block both installs.
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 firewall reporting, including scanned and blocked dependencies, in the Malware firewall section of the Dashboard.

​
How Malware Firewall integrates with your system

Installing Semgrep Malware Firewall makes the following changes to your system:
  • PATH shims: Installing the firewall adds a shim for each package manager to the front of your PATH. Each shim runs the package manager with the required environment variables, such as HTTP_PROXY and NODE_EXTRA_CA_CERTS, so that traffic goes through the firewall proxy. Shims also enable communication with the firewall, allowing it to print the exact reason a package was blocked.
  • Trust store update: The firewall’s certificate is added to your trust store so that the firewall can identify which package version a package manager requests. Package managers send registry requests directly to the firewall proxy. The firewall terminates the connection, captures the package name and version from the request, and reissues the request to the registry. For the TLS handshake between the package manager and the firewall to succeed, the package manager must trust the certificate that the firewall presents. The firewall’s certificate is added alongside existing trusted certificates and does not remove or replace any of them.
  • Background daemon: Keeps the firewall and its configuration, such as private registry locations, up to date. You don’t need to reinstall or manually reconfigure the firewall.

​
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 HTTP_PROXY and HTTPS_PROXY so they use the proxy automatically. You don’t need per-tool configuration, such as tool.uv.index for uv. The proxy watches known package registry URLs such as registry.npmjs.org (npm) and repo.maven.apache.org (Maven Central). It identifies package-download requests, including tarballs, wheels, JARs, and similar artifacts, and waits for a Semgrep backend response before the download completes. All other traffic passes through the proxy.
  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 override that configuration, so it doesn’t gate that run.

​
No built-in cooldown configuration

The firewall doesn’t currently support configuring a cooldown period before a newly published package version can be installed. Semgrep recommends configuring cooldowns in your package managers. 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 ships advisories as soon as an incident is identified, rather than waiting for it to be published to sources that are used otherwise, 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 ✅.