# Egress Guard

[All work](https://sulayman-bowles.dev/work)

I built Egress Guard to block ad, tracker and malware domains on a Mac without decrypting a single HTTPS connection.

ProblemBlock listsDashboardJudgment

## Reading HTTPS means trusting a new certificate

A filter that inspects HTTPS content has to install a certificate authority your Mac trusts for every site. Whoever holds that key can read the traffic. Egress Guard decides from the hostname instead. A blocked connection is refused before it reaches the internet, and an allowed one passes through with the site’s own certificate and its contents still encrypted.

It runs as a local proxy on 127.0.0.1:18080 with a private dashboard beside it. It needs no root daemon, no browser certificate and no account. Version 0.1.1 is MIT-licensed on GitHub, with a hash-checked installer for macOS and a portable Python core.

**What the proxy does with each request**

| Request | What happens |
| --- | --- |
| HTTPS to a listed ad, tracker or threat domain | Refused before any connection to the site |
| HTTPS to any other domain | Passed through encrypted, with the original certificate |
| Plain HTTP to an outside host carrying a cookie or login header | Refused before it is forwarded |
| A host you allowed from the dashboard | Passed until the exception expires |

- [Architecture and threat model](https://github.com/SulaymanB2024/egress-guard/blob/1b9a52deef37779254c792aa93dce6209141d603/docs/architecture.md)

## A broken download never empties the list

The lists come from HaGeZi’s Multi PRO++ ad and tracker list, HaGeZi’s threat intelligence feed and AdGuard’s CNAME data, which catches trackers dressed up as a site’s own subdomain. They refresh daily when the background service is on.

The failure I designed against is quiet: a truncated file that replaces a good one and lets everything through. Each feed has a fixed HTTPS address, a minimum size and shrink protection, and swaps in atomically. A download that fails any check keeps yesterday’s list, and the dashboard shows the feed’s age apart from whether the last download worked.

**Default feeds and the smallest file each will accept**

| Feed | What it catches | Minimum domains |
| --- | --- | --- |
| HaGeZi Multi PRO++ | Ads and trackers | 50,000 |
| HaGeZi Threat Intelligence (Medium) | Malware, phishing and scam hosts | 100,000 |
| AdGuard CNAME-cloaked trackers | Trackers behind first-party subdomains | 20,000 |
| AdGuard CNAME-cloaked ads | Ads behind first-party subdomains | 1,000 |

CNAME entries match exact hostnames only, so one alias can’t block a whole parent domain.

## Six security fixes before the first release

The dashboard explains each decision, checks any domain, pauses ad filtering, adds rules and allows one host for a while. A control panel on localhost is also a target: a malicious web page can try to reach it through your own browser, by DNS rebinding or by a request from another local port.

So it accepts only its exact loopback address and origin. The launcher and server prove they share a secret key without sending it, the session token lives in the browser tab instead of a cookie, and every change carries a CSRF token. A review before release found six problems, including a session cookie that other local ports could replay and a health check a fake proxy could imitate. All six shipped fixed with regression tests, and 0.1.1 passed 144 test cases across the source and installed-wheel runs.

- [Pre-release security review](https://github.com/SulaymanB2024/egress-guard/blob/1b9a52deef37779254c792aa93dce6209141d603/docs/security-review.md)

## The feature I left out: routing the whole Mac

The obvious next step is pointing all of macOS at the proxy. I left it out of the alpha. macOS keeps proxy settings after you log out, but a per-user process can’t keep its port, so every proxy-aware app would lose the internet whenever the guard stopped. Until an OS-managed service can own that port across reboots, logouts and crashes, you point individual apps at the proxy and the rest of the Mac is untouched.

Method & limits: this is an alpha, tested on Apple silicon with Python 3.12. It filters only apps that use the proxy. Apps that bypass it, encrypted tunnels and ads served from a site’s own domain need other tools, so a browser blocker is still worth running beside it. Next I want a reproducible benchmark that scores blocked requests and broken pages, because a rule count says nothing about either.

- [Egress Guard on GitHub](https://github.com/SulaymanB2024/egress-guard)
- [Releases 0.1.0 and 0.1.1](https://github.com/SulaymanB2024/egress-guard/releases)

[All work](https://sulayman-bowles.dev/work)[Continue with Chegg](https://sulayman-bowles.dev/work/chegg)

---
Source: https://sulayman-bowles.dev/work/egress-guard · Sulayman Bowles
