> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semgrep.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Semgrep Malware Firewall
> The Semgrep Malware Firewall prevents malicious packages from being installed on developer machines by checking each requested package against Semgrep's continuously updated malware database.
Semgrep Malware Firewall is in **private beta**.
## Overview
The Semgrep Malware Firewall prevents malicious packages from being installed on your machine. It sits in front of your package installs, checks each requested package against Semgrep's continuously updated database of known malware, and blocks anything that matches.
## How it works
The firewall has the following parts:
1. A lightweight **client proxy** that runs on every machine.
* You set it up once with `mfw install`. It sets the standard proxy environment variables `HTTP_PROXY` and `HTTPS_PROXY` so package managers 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`, identifies package-download requests specifically—including tarballs, wheels, and similar artifacts—and gates those artifact 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** that is continuously updated from a variety of threat feeds and maintained by Semgrep's security research team.
The 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.
### Advisory and database sync objectives
* 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](https://osv.dev) (OSV) database.
* For all other findings, the malware database syncs from OSV every 2 hours.
### Cooldowns
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](https://cooldowns.dev/) for a guide across ecosystems.
## Reporting
Semgrep AppSec Platform shows basic firewall reporting, including scanned and blocked dependencies, in the **Malware firewall** section of the **Dashboard**.
## Prerequisites
* You must have an active Semgrep account
* You must have [Semgrep Guardian](/guardian) enabled
* You must have access to a macOS or Linux terminal or shell
## Supported languages
The firewall works with projects written in Go, JavaScript, Python, and Rust.
## 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](/guardian), the `/install-mfw` skill is the quickest path — it installs and configures everything for you.
Semgrep Guardian ships with an `/install-mfw` skill that installs and sets up the firewall for you.
In your AI coding agent with the [Semgrep Guardian](/guardian) plugin installed (such as Claude Code), run:
```bash theme={null}
/install-mfw
```
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.
Restart your Terminal / shell so the proxy environment variables take effect.
Open your terminal.
Download and install the firewall:
```bash theme={null}
curl -fsSL https://semgrep.dev/dist/mfw/install.sh | sh
```
When prompted, confirm with `y`.
Restart your terminal or shell so the proxy environment variables take effect.
Verify the install:
```bash theme={null}
mfw doctor
```
You should see:
```
Semgrep mfw is protecting this machine ✅
```
## Test the firewall
Use a known-safe demo package to confirm that the firewall blocks malicious installs without touching real malware.
Open or create a test directory and initialize a project:
```bash theme={null}
uv init
```
Attempt to install the demo malware package:
```bash theme={null}
uv add --no-cache semgrep-malware-demo-aws-cred-read
```
**Expected result:** the install is blocked. The firewall should intercept and reject the package.
To test with a second package manager, repeat with pip:
```bash theme={null}
pip install --no-cache semgrep-malware-demo-aws-cred-read
```
Both these packages should be blocked by the Semgrep Malware Firewall. If either install succeeds, the firewall isn't intercepting traffic correctly. Review the `mfw doctor` output, and see [Troubleshoot `mfw doctor` failures](#troubleshoot-mfw-doctor-failures).
## Determine whether a specific dependency version is malicious
The `mfw api` command can be used to determine if a specific version of a package is malicious:
```bash theme={null}
mfw api command
# example usage: mfw api pypi pydantic 2.13.4
```
## Uninstall the firewall
To remove the firewall and its proxy configuration from a machine:
```bash theme={null}
mfw uninstall
```
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:
```bash theme={null}
mfw doctor
```
It should no longer report `Semgrep mfw is protecting this machine ✅`.
## Troubleshoot `mfw doctor` failures
| Symptom | Likely cause | Suggested fix |
| :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| `mfw doctor` reports that the firewall isn't protecting the machine right after install | The shell wasn't restarted, so `HTTP_PROXY` and `HTTPS_PROXY` aren't set in the current session | Restart your terminal or shell, then re-run `mfw doctor` |
| `mfw doctor` reports an authentication error | You haven't run `mfw login`, or the short-lived bearer token has expired | Run `mfw login` again |
| Package installs are slow or time out | The local proxy can't reach the Semgrep verdict backend because of network or firewall rules that block egress | Confirm that outbound access to Semgrep's backend is allowed; review corporate proxy or VPN settings |
| A known-safe package is unexpectedly blocked | The backend returned a stale or incorrect verdict, or a false-positive match in the malware database | Notify us in the [Semgrep Community Slack](https://go.semgrep.dev/slack) channel |
| `mfw doctor` isn't found, or the command isn't recognized | The install script didn't complete, or the shell `PATH` wasn't updated | Re-run the install command from [Install and verify](#install-and-verify), then restart your shell |