Skip to content

Releases

Egress Guard 0.6.0 alpha

Pre-release

Choose a tag to compare

@SulaymanB2024 SulaymanB2024 released this 21 Nov 14:28

Egress Guard 0.6.0 is an alpha that redesigns every surface: the Chrome companion popup, the warning and scanner-link pages, and the web dashboard. The proxy's filtering code is unchanged; only the dashboard's web/ files and the version number differ from 0.5.0, and the dependency locks are unchanged. HTTPS is still passed through with the origin's certificate; no certificate authority is installed.

Design system

  • docs/design/DESIGN.md now governs every surface, with one token file, docs/design/tokens.css. It sets five principles (One answer first, Colour means state, Space before lines, Whole and unexplained, Safe is easy), a five-size type scale and a 4/8 spacing scale. Colour is used for state only.
  • High-fidelity mockups and a capture-and-audit script (docs/design/review/capture.mjs) are included.
  • Tests fail if a surface's tokens drift from the shared file, or if extension CSS uses a literal colour, an off-scale spacing value or a sixth font size.

Chrome companion popup

  • Rebuilt as one view that fits 520 px without scrolling, with Blocked, Rules and Settings in tabs beside the main view.
  • Allow 15 min shows only on the hovered, focused or selected row.
  • Pause is a real timed pause: it covers the current site for 15 minutes and ends by itself. Malware and phishing blocking and your own block rules stay on. Only the popup can start or end a pause.

Warning page and scanner-link page

  • Rebuilt as decision pages: the headline at display size, the hostname second, one filled button which is the safe action, and the state colour used once.

Dashboard

  • Status, blocked today, the 24-hour chart and four reason counts fit above the fold at 1440 x 900.
  • Activity, Top blocked and Threats are tabs. Stopped threats are the only use of the threat colour.
  • A Details disclosure holds the proxy, block lists, canary alerts and setup information. A 24-hour / 7-day switch changes the chart. Long hostnames shorten in the middle by whole labels.

Upgrading from 0.5.0

  • Rebuild the companion with node scripts/build-browser.mjs and reload it on chrome://extensions. Permissions are unchanged. The dashboard updates with the Python package.

Validation: 243 Python tests; 132 Node tests of the companion; a 14/14 headless Firefox run; headless Chrome 29/29, service-worker lifecycle 15/15 and privacy 60/60 and a clean design audit, run before the version bump. The wheel was installed into a clean target with no dependencies and reported 0.6.0, initialised, refused to run with an empty feed cache, and check example.com exited 2 with indeterminate.

Not covered: the popup has not been opened from a real toolbar (it was tested as a page and headlessly). Dashboard captures use a seeded ledger with a simulated healthy proxy and were taken in headless Chrome only. The Firefox build keeps working but has the per-site rules only, with no built-in lists. The Chrome companion is unsigned and loaded unpacked. No YouTube in-stream ad blocking. Upstream Tornado advisories remain tracked in the dependency notes. Not notarized. Clients that are not configured to use the proxy are not protected.

Check SHA256SUMS before installing. The installer still refuses to overwrite an existing environment.

Egress Guard 0.5.0 alpha

Pre-release

Choose a tag to compare

@SulaymanB2024 SulaymanB2024 released this 21 Nov 07:50

Egress Guard 0.5.0 is an alpha that is almost entirely the Chrome companion (now 0.3.1): link and cookie cleaning, first-party tracker blocking from EasyPrivacy and EasyList, per-site protection levels, and fixes from an independent security review. The Python proxy is unchanged apart from the version number. HTTPS is still passed through with the origin's certificate; no certificate authority is installed.

Link cleaning

  • Tracking and attribution parameters are removed on every navigation and again at click time: 147 names everywhere, plus 214 more on the 67 sites that use generic names for tracking. Amazon /ref= path segments are cut. The right-click menu has Copy clean link, and addresses that a client-side redirect has decorated are cleaned in the address bar.
  • Unsubscribe and preference pages keep every parameter, and sign-in, payment, cloud-console and advertiser or affiliate console hosts are left alone.
  • Redirect wrappers (Google, Facebook, LinkedIn, Reddit, Slack and others) are unwrapped only when the navigation starts on the wrapper's own site. A wrapped link arriving from email, another site or the address bar keeps the redirector's own warning page. Affiliate and email click trackers with no safety check (href.li, Skimlinks, Rakuten, Awin, Mandrill) are unwrapped from anywhere.
  • Microsoft Safe Links, Proofpoint, Mimecast, Barracuda and Trend Micro links show a local page with the real destination and a choice; the default is Continue through the scanner.
  • Every unwrapped destination is checked against the malware and phishing list first.

Tracking cookies

  • 44 reviewed name patterns, scoped to their vendors where the name is not unique, are deleted the moment they are set. Opt-out and consent cookies are never deleted. Cookies are stripped from third-party requests to tracker hosts.

First-party and path-based trackers

  • EasyPrivacy and EasyList network filters are compiled at build time into declarativeNetRequest rules by a hardened compiler: exceptions must be anchored to a host, no list line can produce an allow-everything rule, the build fails on a suspicious change in a list, and each list's SHA-256 is shown in NOTICE.txt and the popup.
  • Fingerprinting and session-replay loaders are blocked by path, common tracker APIs (ga(), gtag, fbq, analytics.*, googletag) get inert local stubs, third-party beacons are blocked, Global Privacy Control is sent, and full-address referrers are tightened.

Site modes

  • Per site: Relaxed, Standard, Strict and No scripts. Under Strict and No scripts, embeds are held behind a click-to-load placeholder and load without cookies by default.
  • Strict is not the default. In a 23-site trial, 18 sites rendered in the control run; Standard broke none of them, while Strict hung or degraded 5 of the 18: tomsguide.com hung, the Guardian and Food Network lost their own scripts, Stripe's docs fell back to default fonts, and Microsoft sign-in rendered blank until its CDNs were added to the functional list (fixed in this release). Standard stays the default.

Fixed after an independent review, before this release

  • Unwrapping skipped the redirector's own safety page, which a phishing link could rely on. It now applies only from the redirector's own site.
  • A list exception could lift cookie stripping and other tiers on a host. Exceptions now apply only to the tier they belong to.
  • A hostile list line could compile to an allow-everything rule. The compiler now refuses unanchored exceptions and the build fails on suspicious lines.
  • Some cookie patterns were too broad, including one that deleted a VPN session cookie (DSID). Broad names are now limited to their vendor's domains.
  • The click-to-load placeholder could be clickjacked by the page around it. A click now counts only when the button has been fully visible and unobscured for half a second.
  • A service worker could serve a site's pages and scripts past No scripts. Switching a site to No scripts or Strict now unregisters its service workers and clears its Cache Storage.
  • An experimental fingerprint-noise setting was removed: its keying made third-party frames linkable.

Also since 0.4.0

  • A feasibility write-up for a Safari on iOS extension (docs/safari-ios.md). It is research only; nothing is built.
  • The proxy's code and the dependency locks are unchanged from 0.4.0.

Upgrading from 0.4.0

  • Rebuild with node scripts/build-browser.mjs and reload the extension on chrome://extensions. Chrome will ask for new permissions: cookies, context menus, offscreen documents, clipboard write, scripting and browsing data (site data and service workers). The minimum Chrome version is now 128.
  • See the companion guide for the full list of what is cleaned, blocked and left alone.

Validation: 234 Python tests; 116 Node tests of the companion; a 14/14 headless Firefox run; headless Chrome 29/29, service-worker lifecycle 12/12 and privacy 59/59, run before the version bump. The wheel was installed into a clean target with no dependencies and reported 0.5.0, initialised, refused to run with an empty feed cache, and check example.com exited 2 with indeterminate.

Not covered: no YouTube in-stream ad blocking; anti-adblock and consent walls are out of scope; the Firefox build has the per-site rules only, with no built-in lists or the new features. The Chrome companion is unsigned, loaded unpacked, and has not been run as a packed build. Egress Guard sends no fake traffic to trackers by design. Upstream Tornado advisories remain tracked in the dependency notes; the dependency locks are unchanged. Not notarized. Clients that are not configured to use the proxy are not protected.

Check SHA256SUMS before installing. The installer still refuses to overwrite an existing environment.

Egress Guard 0.4.0 alpha

Pre-release

Choose a tag to compare

@SulaymanB2024 SulaymanB2024 released this 21 Nov 03:39

Egress Guard 0.4.0 is an alpha that widens threat coverage, cuts the proxy's memory use, rebuilds the dashboard around outcomes, and adds an experimental Chrome companion. HTTPS is still passed through with the origin's certificate; no certificate authority is installed.

Threat coverage

  • HaGeZi Threat Intelligence full tier is the default (threat_tier = "medium" still selects the smaller feed). New feeds: Phishing Army, URLhaus via malware-filter (malware domains and IP addresses) and HaGeZi's DoH server list.
  • block_encrypted_dns = true by default, so clients cannot resolve privately over DoH and then connect by IP address. Set it to false under [block] to allow DoH.
  • Punycode look-alike detection for 57 brands, and a built-in 25-host safety list.
  • Threat blocks cannot be overridden by allow rules, exemptions, the ad pause or timed exceptions. Every decision now carries a category.

Footprint

  • Feeds are searched in place in sorted cache files instead of being loaded into memory. Measured proxy RSS fell from about 215 MB to 128 MB while holding about 2.3 times as many domains. scripts/measure-coverage.py repeats the measurement.

Dashboard

  • Rebuilt around outcomes: blocked today, share of connections, change versus yesterday, a 24-hour and 7-day timeline, threats called out, a breakdown by reason, top blocked domains, and searchable activity with a per-row allow or block.
  • One-line health, dark mode, and real states for full, aggregate and none history. New authenticated GET /api/insights.
  • Day boundaries are correct across daylight-saving changes, and periods the ledger never covered show as no data.

Chrome companion (experimental, unsigned, load unpacked)

  • Built-in ad, tracker, CNAME and malware/phishing lists, compiled locally from the proxy's verified feed cache by scripts/build-browser.mjs. A local warning page with a hardened "continue once", tracking-parameter stripping, ad-slot hiding (first-party selector set, per-site switch), per-site rules, an element picker, timed exceptions (not offered for malware hosts) and a restyled popup. See the companion guide.
  • Read-only trial on 18 public sites: none needed an allow rule. Three showed bot interstitials to headless Chrome in both runs, so they say nothing about the extension.

Fixed after an independent review, before this release

  • Continue-once could be redirected to a different host.
  • Continue-once disabled other threat blocks on the page.
  • One-click allow was offered on threat-listed requests.
  • A missing threat feed produced an empty malware ruleset.
  • The extension was detectable by any site.

Upgrading from 0.3.0

  • Run egress-guard refresh once. Until then the proxy keeps filtering with the cached medium threat tier and reports the feed as degraded.
  • Encrypted-DNS servers are blocked by default.
  • Rebuild and reload the Chrome companion after feeds refresh (one click on chrome://extensions).

Validation: 234 Python tests; 70 Node tests of the companion; a 14-check headless Firefox run; headless Chrome 30/30 with real feeds and a service-worker lifecycle check at 12/12 (run before the version bump). The wheel was installed into a clean target with no dependencies and reported 0.4.0, initialised, refused to run with an empty feed cache, and check example.com exited 2 with indeterminate.

Not covered: no YouTube in-stream ad blocking; the Firefox build has no built-in lists; the Chrome companion has not been run as a packed build or from a real toolbar; the chart's keyboard and screen-reader behaviour was reviewed in code only. No native Network Extension, signed updater or automatic system-wide routing. Not notarized. Clients that are not configured to use the proxy are not protected. Upstream Tornado advisories remain tracked in the dependency notes; the dependency locks are unchanged from 0.3.0.

Check SHA256SUMS before installing. The installer still refuses to overwrite an existing environment.

Egress Guard 0.3.0 alpha

Pre-release

Choose a tag to compare

@SulaymanB2024 SulaymanB2024 released this 20 Nov 22:42

Egress Guard 0.3.0 is an alpha that hardens the filtering proxy after an external engineering review and adds an experimental Firefox companion. HTTPS is still passed through with the origin's certificate; no certificate authority is installed.

Proxy and policy

  • The proxy now tracks the policy it has actually applied. Health replies carry a signed policy revision, and the dashboard shows the saved revision beside the applied one.
  • Every enabled feed, including the CNAME feeds, needs a verified cache before run or start will serve traffic. egress-guard check reports indeterminate (exit code 2) while coverage is incomplete.
  • A CONNECT tunnel is admitted only when the client's first bytes are a complete TLS ClientHello. Other protocols inside a tunnel are closed before anything is forwarded.
  • Analytics-dashboard exemptions are an opt-in preset (exemption_presets = ["analytics-dashboards"]) instead of a default.

Services and ledger

  • start waits for a verified ready proxy, keeps a private, size-capped error log, and stop re-checks a job file before removing it.
  • New history setting: full, aggregate (daily counts only) or none. Dropped ledger writes are counted and shown.

Firefox companion (experimental, unsigned)

  • browser/ holds a Manifest V3 extension with site-scoped endpoint blocking, element hiding, an element picker and timed exceptions. Rules stay local; the extension makes no network requests of its own. Load it as a temporary add-on; see the companion guide.

Upgrading from 0.2.0

  • Run stop with the old version before start with the new one.
  • Run refresh first, or set cname_protection = false if the CNAME feeds cannot be fetched.
  • SSH and other non-TLS protocols through the proxy's CONNECT are refused while the credential guard is on.
  • An existing config.toml keeps its current dashboard exemptions; new installs start with none.

Validation: 199 Python tests, including real loopback transport tests with mitmproxy 12.3.1, on Python 3.14; 32 Node tests of the companion's decision core; a 14-check headless Firefox run. The wheel was installed into a clean target and reported its version, initialised, refused to run with an empty feed cache, and served the packaged dashboard, which was inspected at desktop and narrow widths with isolated empty state.

Not covered: the companion has not been tried on real sites, does not talk to the proxy, and has no sponsor skipping. No native Network Extension, signed updater or automatic system-wide routing. Not notarized. Clients that are not configured to use the proxy are not protected. Upstream Tornado advisories remain tracked in the dependency notes; the dependency locks are unchanged from 0.2.0.

Check SHA256SUMS before installing. The installer still refuses to overwrite an existing environment.

Egress Guard 0.2.0

Egress Guard 0.2.0 Pre-release
Pre-release

Choose a tag to compare

@SulaymanB2024 SulaymanB2024 released this 18 Nov 23:00

Egress Guard 0.2.0 expands explicit coverage analysis while retaining the existing encrypted HTTPS passthrough and filtering policy.

  • Inspect CNAME chains through the configured macOS resolver, or analyze offline observations on other platforms. Original and alias policy decisions remain separate; incomplete/conflicting evidence stays indeterminate. This command changes no live filtering.
  • Explicitly fetch SponsorBlock suggestions using a four-character hash prefix, select the exact video locally, check the supplied duration and export attributed JSON. Existing output files are preserved. No browser history is read and playback is unchanged.
  • Bound JSON structure before decoding; reject malformed responses, ambiguous framing, redirects, overlaps and unsupported timing categories. Resolver workers use isolated imports and bounded native execution.

Technical writeup · CNAME guide · Timing format and privacy

Validation: 37 focused tests passed from the installed wheel on Python 3.12.13; the same 37 passed from source on Python 3.15.2. The installed CLI resolved a public alias chain through the native worker with an empty, unwritten application-state path. Wheel/source contents match reviewed source and exclude private device state. Existing transport/dashboard code and dependency locks are unchanged; their full earlier suite was not repeated for this additive release.

This remains an alpha. The browser companion, reversible updater and automatic system-wide routing are not activated by this release. Native VPN/split-DNS and Intel qualification remain open. Upstream Tornado package advisories remain tracked in the dependency notes.

Download the source archive for the guided installer, hash locks, tests and documentation, plus the wheel if desired. Check SHA256SUMS before extraction/install. Existing environments are preserved; the installer continues to refuse an in-place overwrite. SponsorBlock data is fetched only by explicit command and retains its separate CC BY-NC-SA 4.0 terms.

Egress Guard 0.1.1 alpha

Pre-release

Choose a tag to compare

@SulaymanB2024 SulaymanB2024 released this 18 Nov 20:25

Security and recovery follow-up to the first public alpha.

  • Bounded post-connect feed/canary and local health/launcher responses; malformed, oversized or trickled replies fail cleanly.
  • Safer configuration reads preserve linked entries and refuse special files and oversized/deeply nested input.
  • Exact runtime/build dependency locks with artifact hashes. The installer validates a constrained ASCII format and uses private snapshots, binary dependency wheels, offline local-project installation and pip check.
  • Explicit OSV review tool: offline inventory by default; --online sends only public release package names/versions and distinguishes matches from unavailable results.
  • Validation: 140 unchanged cases passed in the combined run; all four affected proxy tests passed after their old-version fixture was corrected, using the installed wheel. Real source/wheel installer functions, pip check, incorrect-hash refusal, original-TLS passthrough, identity and rule recovery passed with temporary state.

Four Tornado 6.5.10 package advisories remain open under mitmproxy's upstream version constraint. Source/import review found no affected Tornado route through this edition's DumpMaster/h11 proxy or standard-library dashboard. This is not a patched-package or clean-scan claim. See requirements/README.md for advisory links and scope.

Download the source archive for the macOS installer and dependency locks, or the wheel with those locks for portable installation. Check SHA256SUMS. This unsigned alpha still requires per-application proxy configuration. Browser ad/sponsor companion work remains a separate, unshipped review candidate.

Egress Guard 0.1.0 alpha

Pre-release

Choose a tag to compare

@SulaymanB2024 SulaymanB2024 released this 18 Nov 19:07

First public alpha: macOS guided installation and portable Python filtering core.

  • Local domain filtering with validated HaGeZi and exact AdGuard CNAME feeds, encrypted HTTPS passthrough, plaintext credential refusal and bounded domain-only activity.
  • Private dashboard with origin-bound mutual launcher authentication, bearer sessions, temporary controls and optional Thinkst canary-history monitoring.
  • Hardened feed recovery, manual rule handling, request framing, canary deduplication and partial service-start recovery.
  • Validation: 93 integrated tests passed on macOS ARM64 / Python 3.12.13 / mitmproxy 12.3.1; fresh wheel and full dependency installation passed. Phone and desktop comparisons are in docs/dashboard-review.md.

Download the source archive for the macOS installer, or the wheel for portable installation. Check both files against SHA256SUMS before installing. See the README for setup.

This unsigned alpha requires individual clients to use its proxy. Automatic system-wide activation is disabled pending an OS-managed endpoint with safe lifetime ownership. Native routing transactions are mocked in tests; Windows dashboard identity is unavailable. Browser-level embedded and sponsored-content blocking is follow-up work.