GitHub - esamattis/mitmwall: A mitmproxy-based egress WAF that restricts connections to allowlisted HTTP routes

GitHub

9 min read Original article ↗

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.

image

How?

  • systemd mitmwall.service starts mitmweb in transparent HTTP(S) proxy mode and DNS proxy mode.
  • ExecStartPre temporarily switches an /etc/resolv.conf containing external nameservers to systemd-resolved's loopback stub. PVE commonly writes upstream nameservers directly to /etc/resolv.conf in LXC containers, which is incompatible with mitmwall's local UDP DNS REDIRECT path.
  • ExecStartPre installs iptables/ip6tables rules that:
    • move mitmwall's filter OUTPUT jump and managed NAT rules ahead of unrelated rules on every start, so an earlier terminal rule cannot bypass enforcement
    • keep custom and time-sync NAT bypasses ahead of the generic redirects
    • redirect outbound TCP port 80 and 443 traffic to the HTTP(S) proxy
    • redirect outbound TCP/UDP port 53 traffic to the DNS proxy
      • only allow the dedicated mitmwall user, configured bypass_users, systemd-resolve, and installed time-sync service users to make required upstream connections
        • the proxy is running as the mitmwall user
        • the default bypass_users include root for host administration and troubleshooting
        • the default bypass_users include _apt because root-invoked APT download workers intentionally drop privileges to that dedicated user
        • 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, or ntp are left able to perform NTP synchronization on UDP/123 and direct DNS queries on UDP/TCP 53
    • accept established/related traffic globally only in conntrack's reply direction, preserving responses for inbound sessions such as SSH without preserving ordinary users' outbound connections across service startup or restart
    • accept ICMPv6 so Linux can perform Neighbor Discovery, router discovery, address configuration, error reporting, and Path MTU Discovery; this applies only to IPv6 and does not permit ordinary TCP or UDP egress
    • drop other outbound traffic so applications cannot bypass the proxies
    • allow any existing local accounts listed in bypass_users to bypass all proxy and outbound firewall restrictions
  • 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 and restores the original /etc/resolv.conf 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.

Install

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:

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.

Usage

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

Allowlist rules

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

Credential injection

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.

System environment variables

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.

Configuration

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 default configuration grants root and APT's _apt sandbox user unrestricted outbound access. Remove either entry to subject that account to mitmwall's proxy and outbound firewall policy. To grant other trusted local accounts unrestricted outbound access, list them in bypass_users. Every named account must already exist:

bypass_users = ["root", "_apt", "buildbot", "deployment"]

Traffic from these users is not visible in mitmweb and is not checked against the allow rules.

mitmproxy configuration

Native mitmproxy settings are stored in /opt/mitmwall/mitmweb/config.yaml. The installer creates this file with a generated web interface password and web_port: 58081 if it does not already exist. Reinstalling or upgrading mitmwall preserves existing settings.

For example, to make the mitmweb interface listen on all IPv4 interfaces, add:

Restart mitmwall after changing the file:

sudo systemctl restart mitmwall

Web interface

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
image

DNS filtering

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. The mitmwall proxy user, configured bypass_users (root and _apt by default), and the systemd-resolve user are excluded so 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.

How secure is this?

Well, first of, AI agents helped creating this. So there is that 😅

The security model relies on Linux user permissions: the dedicated mitmwall user and accounts listed in bypass_users can access the network freely. The default configuration lists root so administrators can manage and troubleshoot the host without going through the proxy, and _apt so APT can retain its normal privilege separation when invoked by root. Operators can remove either default. So if the attacker can do privilege escalation:

  • to the mitmwall user they can access the network
  • to the _apt user they can access the network when its default bypass remains
  • to root they can access the network when its default bypass remains, and can stop the service regardless

DNS-based exfiltration

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.

Allowlisted-domain exfiltration

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.

Raw sockets

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.

The IPv6 filter therefore accepts all ICMPv6 rather than maintaining a fixed message-type list. ICMPv6 is IPv6 control-plane traffic, and RFC 4890's required and recommended messages cover more than Neighbor Discovery and can evolve with the Linux IPv6 stack. A type list is more likely to break IPv6 configuration or Path MTU handling. Unprivileged Linux ping sockets are limited to echo requests, so this broader kernel-facing allowance does not let regular processes construct arbitrary ICMPv6 packets or weaken the TCP/UDP egress policy.

Bottomline

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.