v1.12.0b (beta) – MITM Proxy & Ad‑Blocking

v1.12.0b (beta) – MITM Proxy & Ad‑Blocking

This beta release introduces an optional MITM proxy that intercepts HTTPS traffic, decrypts it, forwards DoH queries to phantomd, and can inject an ad‑blocking script into web pages.

⚠️ This is a pre‑release – the MITM proxy is experimental. Any feedback on added features will be appreciated.

---

✨ Added

• MITM proxy (Rust) – a standalone binary phantomd-mitm that:
  • Terminates TLS connections using a dynamically generated leaf certificate.
  • Detects DoH requests (POST /dns-query with application/dns-message) and forwards them to phantomd via a Unix socket.
  • Optionally injects a JavaScript snippet to remove common ad elements (configurable).
  • Forwards non‑DoH HTTPS traffic unchanged (or drops it, depending on forward_non_doh).
• New [mitm] section in phantomd.conf – all options documented.
• Installer now downloads pre‑compiled binaries for x86_64 and aarch64 from GitHub releases (fallback to source compilation only if download fails).

🛠️ Changed

• installer.sh – added Rust toolchain only as fallback; by default downloads the binary.
• GitHub Actions – builds phantomd-mitm on tag pushes and attaches binaries to the release.
• core/dserver.py – added DoHSocketHandler to receive DNS queries from the proxy.
• main.py – generates the TOML config for the proxy and manages the systemd service.

🧪 Testing (beta)

• 142 Python tests all pass.

📦 Upgrading to v1.12.0b

• Fresh install: ./installer.sh
• Update existing installation: ./installer.sh --update
  Then edit /opt/phantomd/config/phantomd.conf and add the [mitm] section (see example below).
• Enable MITM proxy:
  • Set enabled = true under [mitm] in the config.
  • Install the root CA certificate from /var/lib/phantomd-mitm/ca/ca.cert on all clients.
  • Redirect port 443 to the proxy using iptables (example provided in the README).
  • Restart phantomd: systemctl restart phantomd

Example configuration snippet

[mitm]
enabled = true
listen_ip = 0.0.0.0
listen_port = 8443
socket_path = /tmp/phantomd_doh.sock
ad_block_enabled = true
forward_non_doh = true
ca_dir = /var/lib/phantomd-mitm/ca
cert_cache_ttl = 3600```

### ⚠️ Known limitations
- Does not support HTTP/2 yet (only HTTP/1.1).
- Certificate pinning in some apps (e.g., banking, social media) will cause connection errors.
- High CPU usage under heavy load (Rust is fast, but still a proxy).
- Ad‑block injection is basic (removes elements by class/id) – not as complete as browser extensions.

**Full Changelog**: https://github.com/KianiDev/phantomd/compare/v.1.11.1...v1.12.0b

v1.11.1 - Bootstrap DNS & Custom DoH Paths

v1.11.1 – Bootstrap DNS & Custom DoH Paths

This release introduces configurable bootstrap DNS servers to resolve upstream hostnames for encrypted transports (DoT, DoH, DoQ) and custom URL paths for DoH servers. The legacy dns_resolver_server option is removed in favour of the new [bootstrap] section.

---

✨ Added

• Bootstrap DNS servers – Specify a list of DNS servers (IP:port) in [bootstrap] to resolve upstream hostnames. If all bootstrap servers fail, the system resolver is used as fallback.

    [bootstrap]
    servers = 1.1.1.1:53, 8.8.8.8:53
    timeout = 2.0
    retries = 2

• Custom DoH path – Each upstream in [upstreams.<name>] can now define a path (e.g., /dns-query, /x/dns-query, /custom). The default remains /dns-query.
• New tests – 9 unit/integration tests covering bootstrap resolution, fallback, caching, and custom DoH paths (total suite: 142 tests).

🛠️ Changed

• Removed dns_resolver_server from [upstream] section. Migrate existing configurations to the [bootstrap] section.
• DNSResolver._resolve_upstream_ip now uses bootstrap servers if configured, then falls back to the system resolver.
• DoH forwarding methods (_forward_https, _forward_https1/2/3) accept a path parameter and use it in the HTTP request.
• Connection pooling keys for HTTP/2 and HTTP/3 include the path, allowing separate pools for different paths on the same host.

🧪 Testing

• 142 tests passing (unit + integration).
• New bootstrap tests:
  • test_bootstrap_resolves_hostname
  • test_bootstrap_fallback_to_next_server
  • test_bootstrap_fallback_to_system_resolver
  • test_bootstrap_cache
  • test_bootstrap_no_servers_fallback_to_system
• New custom path tests:
  • test_custom_path_https1/2/3
  • test_custom_path_default_when_missing
  • test_custom_path_in_upstream_list

📦 Upgrading

• Update existing installation:
  ./installer.sh --update
  Then edit /opt/phantomd/config/phantomd.conf:
  • Remove any dns_resolver_server = ... line from [upstream].
  • Add a [bootstrap] section (example above).
  • If using multi‑upstream DoH, add path = /your/path under each [upstreams.<name>].
• Fresh install:
  ./installer.sh – the installer will create a default phantomd.conf with the new bootstrap section.
• Restart service:
  systemctl restart phantomd

---

Full Changelog: v1.10.1...v1.11.0

v1.10.1 - Bugfixes

🐛 Bugfixes & Integration Test Suite

This patch fixes two issues: hosts‑map entries being incorrectly added to the blocklist, and the DNS rate limiter not activating when rate_limit_burst= was set to 0. It also adds a comprehensive integration test suite that validates end‑to‑end behaviour with a real server instance.

---

🐛 Fixed

• Hosts‑file entries no longer added to the blocklist – domains from hosts‑format files (e.g., 10.0.0.1 local.test) now resolve correctly
  instead of returning NXDOMAIN.
• DNS rate limiter now activates even when rate_limit_burst = 0 – burst is treated as 1 so the first request is allowed and subsequent requests are rate‑limited as expected.

✨ Added

• Integration test suite – 9 tests that start a real phantomd server on a random port with a mocked upstream, covering:
  • UDP and TCP forwarding
  • NXDOMAIN responses
  • Caching
  • Blocklist actions (NXDOMAIN, ZEROIP)
  • Hosts‑map resolution
  • IPv6 AAAA filtering
  • Rebinding protection (strip)

🧪 Testing

• Total test count: 132 (123 unit + 9 integration).
• All tests run in CI without network access.

📦 Upgrading

• Update: ./installer.sh --update then systemctl restart phantomd
• Fresh install: ./installer.sh

Full Changelog: v1.10.0...v1.10.1

v1.10.0 - Expanded Connection Pooling

🔗 Expanded Connection Pooling – HTTP/2, HTTP/3, and DoQ

Connection pooling now extends beyond TCP/TLS to cover all modern protocols: HTTP/2, HTTP/3 (DoH3), and QUIC (DoQ). Connections are reused transparently, reducing handshake overhead and improving performance for every upstream type.

---

✨ Added

• Pooling for HTTP/2 – httpx.AsyncClient instances are kept and reused.
• Pooling for HTTP/3 – QUIC connections with H3 sessions are pooled per upstream.
• Pooling for DoQ – QUIC connections are reused for raw DNS‑over‑QUIC queries.
• New tests – 3 tests verify reuse of HTTP/2 clients, error‑handling, and DoQ connection pooling. Total test suite: 119 tests.

🛠️ Changed

• pool_max_size and pool_idle_timeout now apply to all pooled protocols (TCP, TLS, HTTP/2, HTTP/3, DoQ). No new configuration keys required.
• _forward_https2, _forward_https3, and _forward_quic borrow/return connections via the new ClientPool class.
• Internal pool cleanup closes idle connections and frees resources automatically.

📦 Upgrading

• Update: ./installer.sh --update then systemctl restart phantomd
• Fresh install: ./installer.sh

Full Changelog: v1.9.0...v1.10.0

v1.9.0 - HTTP/2 & HTTP/3 support for DoH

🌐 Multiple DoH Versions (HTTP/1.1, HTTP/2, HTTP/3) with Auto‑Negotiation

phantomd now supports all major DoH protocols: classic HTTP/1.1, modern HTTP/2 (via httpx), and cutting‑edge HTTP/3 (via QUIC). The new auto mode automatically probes and remembers the best version per upstream, so your server always uses the fastest available transport without manual tuning.

---

✨ Added

• DoH version selection – new global doh_version option in [advanced] and per‑upstream doh_version key for [upstreams.xxx]. Supported values:
  auto (probe best), 1.1 (classic), 2 (HTTP/2), 3 (HTTP/3).
  auto is the default; falls back gracefully through 3 → 2 → 1.1.
• DoH/3 (HTTP/3) implementation using aioquic.h3 – DNS queries sent via QUIC with proper HTTP/3 framing.
• DoH/2 (HTTP/2) implementation using httpx – persistent, multiplexed connections for lower latency.
• Auto‑negotiation cache – probed version is remembered for doh_auto_cache_ttl seconds (default 3600). Hot‑reloadable.
• HTTP/1.1 DoH retained for compatibility and fallback.
• New tests – 5 tests covering auto‑probing, version caching, fallback, explicit version override, and config hot‑reload. Total test suite: 116 tests.

🛠️ Changed

• _forward_https now dispatches to _forward_https1, _forward_https2, or _forward_https3 based on the resolved version.
• Configuration now supports doh_version and doh_auto_cache_ttl options in [advanced], plus per‑upstream doh_version.

📦 Upgrading

• Update: ./installer.sh --update then systemctl restart phantomd
• Fresh install: ./installer.sh
• To use HTTP/2, ensure httpx with H2 support is installed.
• To use HTTP/3, ensure aioquic is installed (same as for DoQ).

Full Changelog: v1.8.0...v1.9.0

v1.8.0 - Connection Pooling for Upstream TCP/TLS

🔗 Connection Pooling for Upstream TCP/TLS

TCP and TLS upstream connections are now pooled and reused, eliminating the overhead of a new TCP/TLS handshake for every single query. This significantly improves performance and reduces latency, especially when using DoT or TCP-based upstreams.

---

✨ Added

• Connection pooling – new [advanced] configuration options: pool_max_size and pool_idle_timeout. The resolver reuses established connections to the same upstream host/port for TCP and DoT, with automatic idle cleanup. Configured with sensible defaults (max 5 connections, 60‑second idle timeout). Hot‑reloadable via SIGHUP.
• New tests – 7 tests cover connection pool logic (get/put, max size, closed connections, independent keys) and end‑to‑end TCP pooling with connection reuse. Total test suite: 111 tests.

🛠️ Changed

• _forward_tcp and _forward_tls now borrow connections from the pool and return them after successful use. Failed connections are discarded.
• Configuration template updated with the new pooling options.

📦 Upgrading

• Update: ./installer.sh --update then systemctl restart phantomd
• Fresh install: ./installer.sh

Full Changelog: v1.7.0...v1.8.0

v1.7.0 - DNS Rebind Protection

🛡️ DNS Rebinding Protection

phantomd can now protect against DNS rebinding attacks by filtering private and special-use IP addresses from upstream responses. This prevents malicious domains from accessing internal network resources—a critical security feature for network‑level DNS filters.

---

✨ Added

• DNS rebinding protection – new [security] configuration options:
  dns_rebind_protection and dns_rebind_action (strip or block).
  When enabled, phantomd removes private IPs (192.168.x.x, 10.x.x.x, etc.) from DNS answers before returning them to clients.
  Default: disabled (dns_rebind_protection = false).
• New tests – 11 tests cover _is_private_ip, _apply_rebind_protection in both modes, disabled behaviour, and end‑to‑end forwarding with rebinding enabled. Total test suite: 104 tests.

🛠️ Changed

• Configuration template (config/phantomd.conf) updated with commented‑out examples for the new rebinding‑protection settings.

📦 Upgrading

• Update: ./installer.sh --update then systemctl restart phantomd
• Fresh install: ./installer.sh

Full Changelog: v1.6.0...v1.7.0

v1.6.0 - DNS Privilege Dropping

🔐 DNS Privilege Dropping

The DNS server can now drop root privileges after binding to the listen port, matching the behaviour already present in the DHCP server. This reduces the attack surface in production deployments.

---

✨ Added

• DNS privilege dropping – new [security] configuration options: dns_privilege_drop_user, dns_privilege_drop_group, and dns_chroot_dir. After binding the UDP/TCP listeners, the server switches to the specified user and group (and optionally chroots). Disabled by default (empty values).
  Hot‑reloading via SIGHUP is not affected, as the listen address/port is unchanged.
• New tests – 5 unit tests verify the privilege‑dropping helper logic (non‑root skip, successful drop, default group, error handling).

🛠️ Changed

• run_server() in core/dserver.py now calls _drop_dns_privileges() after both listeners are created.
• Configuration template (config/phantomd.conf) updated with commented‑out examples for the new privilege‑drop settings.

📦 Upgrading

• Update: ./installer.sh --update then systemctl restart phantomd
• Fresh install: ./installer.sh

Full Changelog: v1.5.0...v1.6.0

v1.5.0 - Optimistic Caching

⚡ Optimistic Caching (Serve‑Stale)

This release adds optimistic caching – when a cached DNS record expires, phantomd now serves the stale response immediately while refreshing the record in the background. This keeps latency low and improves resilience during brief upstream outages, following RFC 8767.

---

✨ Added

• Optimistic caching – serve‑stale with configurable max age and TTL for stale responses. Disabled by default; enable with optimistic_cache_enabled = true in the [advanced] section of phantomd.conf. Hot‑reloadable via SIGHUP.
• New configuration options – optimistic_cache_enabled, optimistic_stale_max_age, and optimistic_stale_response_ttl fully documented in the config template.
• Expanded test suite – 5 new tests cover fresh/stale serving, max‑age expiry, duplicate refresh prevention, and disabled behaviour. Total: 88 tests.

🐛 Fixed

• Wire‑cache query_data storage – internal cache format updated to store original query data, enabling proper background refresh.
• Cache expiry test compatibility – tests now work correctly with all cache backends (cachetools and AsyncTTLCache).

🛠️ Changed

• _wire_cache_set signature – now requires an explicit query_data argument to support background refresh. All internal calls updated.
• _set_response_ttl rewritten to rebuild the entire response, guaranteeing TTL changes apply across all dnspython versions.

📦 Upgrading

• Update: ./installer.sh --update then systemctl restart phantomd
• Fresh install: ./installer.sh

Full Changelog: v1.4.0...v1.5.0

v1.4.0 - Multi‑Upstream Failover

🔀 Multi‑Upstream Failover & Config Enhancements

This release adds support for multiple upstream DNS servers with automatic failover.
You can now define a list of upstreams (each with its own protocol, port, and hostname) and the resolver will try them in order until one succeeds – no more relying on a single provider.

---

✨ Added

• Multi‑upstream failover – new [upstreams] config section allows defining multiple upstream servers with per‑server protocol/port/hostname. The resolver iterates through them until a response is received; if all fail, the last error is returned. Fully hot‑reloadable.
• [upstreams] configuration template – documented example (commented out) in config/phantomd.conf shows how to configure Cloudflare, Google, and Quad9 as fallbacks.
• New tests – 4 additional tests cover multi‑upstream success, failover to second upstream, total failure, and cache‑hit skipping of upstreams. Total suite: 83 tests.

🛠️ Changed

• Internal forwarding methods now accept an optional upstream dictionary (backward‑compatible).
• Single‑upstream configuration (dns_server/dns_protocol) continues to work exactly as before.

📦 Upgrading

• Update: ./installer.sh --update then systemctl restart phantomd
• Fresh install: ./installer.sh

Full Changelog: v1.3.0...v1.4.0