mitmwall is an egress Web Application Firewall (WAF) for Ubuntu. It combines
iptables
with mitmproxy to ensure that only explicitly allowed HTTP(s) routes can be reached. Any network connection that does not match the allowlist is blocked. This prevents:
Data exfiltration— compromised npm/pypi/cargo etc. packages, rogue AI agents, or other untrusted processes stealing credentials, API keys, or source code.Backdoor connections— malware phoning home to command-and-control servers.
The built-in mitmweb interface can be used to monitor all proxied traffic in real time.
Read this blog post for background Protecting against npm and AI agents
The name is a wordplay for mitmproxy + firewall = mitmwall.
- systemd
mitmwall.service
startsmitmweb
in transparent HTTP(S) proxy mode and DNS proxy mode. ExecStartPre
installsiptables
/ip6tables
rules that:- redirect outbound TCP port
80
and443
traffic to the HTTP(S) proxy - redirect outbound TCP/UDP port
53
traffic to the DNS proxy- only allow root, the dedicated
mitmwall
user,systemd-resolve
, and installed time-sync service users to make required upstream connections- the proxy is running as the
mitmwall
user - root is left unrestricted for host administration and troubleshooting
systemd-resolve
is left able to perform resolver recursion without looping back into the DNS proxy- installed time-sync service users such as
systemd-timesync
,_chrony
, orntp
are left able to perform NTP synchronization on UDP/123 and direct DNS queries on UDP/TCP 53
-
the proxy is running as the
-
only allow root, the dedicated
-
drop other new outbound traffic so applications cannot bypass the proxies
-
redirect outbound TCP port
-
The mitmproxy addon in
src/addon
loads TOML files from/etc/mitmwall/rules.d
and:- kills HTTP(S) flows whose host, method, and pathname do not match the allowlist
- refuses DNS queries whose hostname does not match any allow rule
ExecStopPost
removes the firewall rules when the service stops.
If /etc/mitmwall/rules.d
is missing or any rule file is invalid, mitmwall fails closed and blocks all proxied HTTP(S) traffic and DNS resolution.
You should also read the How mitmproxy works -article.
Run on the Ubuntu server as a sudo-capable user:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/esamattis/mitmwall/main/web-install.sh)"
Or, from a local checkout:
sudo ./install.sh
The installer creates a mitmwall
system user, installs mitmproxy under
/opt/mitmwall
, creates /etc/mitmwall/config.toml
and /etc/mitmwall/rules.d
,
installs the systemd service, generates the mitmproxy CA, and adds the CA to
the system trust store with update-ca-certificates
.
The scripts can be also used for upgrading mitmwall.
Enable at boot and start immediately:
sudo systemctl enable --now mitmwall
Restart after changing rules:
sudo systemctl restart mitmwall
Stop mitmwall and remove its iptables/ip6tables rules:
sudo systemctl stop mitmwall
Start again with
sudo systemctl start mitmwall
View logs:
sudo journalctl -u mitmwall.service -f
Rules are stored as TOML files in /etc/mitmwall/rules.d
. Each *.toml
file
can contain zero or more [[allow]]
tables. Traffic is blocked unless the request hostname, HTTP method, and optional pathname filter match at least one allow rule. Files are loaded in alphabetical filename order.
The example-rules.toml file in this repository is
installed to /etc/mitmwall/rules.d/5-examples.toml
. It contains a fully commented reference covering syntax, constraints, matching behavior, and examples.
After editing files in /etc/mitmwall/rules.d
, restart the service:
sudo systemctl restart mitmwall
inject_headers
can add custom headers to requests, which can be used to transparently supply credentials. This can be a powerful way to avoid exposing credentials to untrusted users. A typical workflow is to first configure the tools that require the credentials, inspect in mitmweb how the credentials are used, write a matching rule that injects the credential headers, and finally replace the real credentials with dummy values so the tool still thinks credentials are configured. Credential injection also prevents malware from using their own credentials.
The installer reads the plain env file system_enviroment to build the mitmwall-managed CA environment block written to
/etc/environment
.
These variables point common runtimes and TLS libraries at the mitmproxy CA
certificate or the rebuilt system CA bundle so HTTPS clients can trust
certificates generated while mitmwall is intercepting traffic. The values apply
to new login sessions after installation.Settings are stored in /etc/mitmwall/config.toml
. The installer creates this file if it does not already exist. See the default config for the available settings.
Restart the service after changing addon configuration:
sudo systemctl restart mitmwall
The mitmweb
web interface can be used to inspect traffic, which makes it
easier to create accurate rules. Rules added through the options interface are
applied immediately without a service reload and are persisted to
/etc/mitmwall/rules.d/2-web.toml
- mitmweb listens on port
58081
. - The password can be viewed as an administrator from the generated mitmweb config:
sudo grep '^web_password:' /opt/mitmwall/mitmweb/config.yaml
mitmwall runs mitmproxy in both transparent HTTP(S) mode and DNS mode. The
firewall redirects ordinary users' TCP/UDP port 53 traffic, including attempts to
query local resolvers such as 127.0.0.53
or public resolvers such as 1.1.1.1
,
to mitmproxy's local DNS listener. Root, the mitmwall
proxy user, and the
systemd-resolve
user are excluded so administration, proxy upstream lookups, and system resolver recursion do not loop back into the proxy.
By default, the mitmproxy addon applies the same rule files in
/etc/mitmwall/rules.d
to DNS queries before forwarding them upstream. DNS
policy is hostname-only: domain
, domain_regex
, and include_subdomains
decide whether a query may be resolved, while HTTP-specific filters such as
methods
, pathname_pattern
, pathname_regex
, and inject_headers
still
apply only to web requests. Queries for the machine's local hostname are also
allowed. Other queries that do not match any allow rule are answered with DNS
REFUSED
and are not resolved upstream.
Set block_dns = false
in /etc/mitmwall/config.toml
to disable addon-level DNS filtering and pass through all DNS queries. This does not change the firewall redirection rules.
Well, first of, AI agents helped creating this. So there is that 😅
The security model relies on Linux user permissions: Only root and the
mitmwall
user can access the network freely. Root is intentionally exempt so administrators can manage and troubleshoot the host without going through the proxy. So if the attacker can do privilege escalation:
- to the
mitmwall
user they can access the network - to root they can access the network and can just stop the service
DNS filtering closes the obvious DNS-based exfiltration path where a process
encodes data into lookup names, for example secret-token.attacker.example
, and relies on the normal DNS resolution path to reveal that full query to an attacker-controlled authoritative nameserver. Because mitmwall refuses names outside the configured allowlist before resolving them, those synthetic exfiltration domains are never sent upstream.
Allowed domains should still be chosen carefully: if an attacker can control a
subdomain under an allowed rule, or if a broad domain_regex
allows untrusted names, DNS can still be used as a data channel within that allowed namespace.
Allowed domains can still be used for credentials dumping, especially when a
rule allows write-capable methods such as POST
, PUT
, or PATCH
, or uses
methods = "ANY"
. For example, if github.com
is allowed with a method that can create or update content, malware could post secrets to an attacker-controlled issue, gist, repository, or workflow log without violating the hostname and method allowlist.
The default method policy only allows GET
and HEAD
, which blocks many common
write paths. When a write-capable method is needed, prefer narrowing the rule
with pathname_pattern
or pathname_regex
instead of allowing the whole domain. For example, a GitHub rule can allow only the repository path needed for a Git operation rather than every issue, gist, repository, or workflow endpoint on the host.
Pathname filters reduce accidental exfiltration risk, but they do not make an allowed domain safe: secrets may still be leaked through URLs, query strings, headers, or any endpoint where an allowed method causes data to leave the host.
Regular non-root processes on Ubuntu do not have CAP_NET_RAW
, so they cannot
create raw sockets that would bypass iptables. Only root and processes explicitly
granted this capability (for example via setcap
) can craft packets that skip the firewall rules. This makes raw socket-based circumvention impractical for the threat model mitmwall targets.
But the idea is not to protect from targeted attacks, but from rogue AI agents gone mad and from general credentials dumping malware as seen on the npm registry lately.