feat: implement dns-over-https support

[Copilot]

Adds DNS-over-HTTPS (DoH) support to encrypt DNS queries, preventing DNS MITM attacks and enhancing privacy. Traditional UDP DNS queries can be intercepted or modified; DoH tunnels them over HTTPS.

Changes

CLI

• --dns-over-https [resolver] flag with optional custom resolver URL
• Default resolver: https://dns.google/dns-query
• Validates DoH endpoint domain is in --allow-domains

Container

• Installs cloudflared in agent container as local DoH proxy
• Starts proxy on 127.0.0.53:53 when DoH enabled
• Blocks external UDP DNS via iptables when DoH active

Types

• dnsOverHttps?: boolean and dohResolver?: string in WrapperConfig

Usage

# Default Google DoH resolver
sudo awf --dns-over-https --allow-domains github.com,dns.google -- curl https://github.com

# Custom Cloudflare resolver
sudo awf --dns-over-https https://cloudflare-dns.com/dns-query \
  --allow-domains github.com,cloudflare-dns.com -- curl https://github.com

Documentation

• docs/dns-over-https.md with architecture, supported resolvers, and troubleshooting

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] implement dns-over-https support</issue_title>
<issue_description>## Objective

Add DNS-over-HTTPS (DoH) support to prevent DNS MITM attacks and enhance privacy by encrypting DNS queries.

Context

Current state: DNS queries use unencrypted UDP to trusted servers (8.8.8.8, 8.8.4.4) which could be intercepted or modified.

Risk level: 🟡 MEDIUM - DNS spoofing risk identified in threat model

Implementation Approach

1. Add --dns-over-https CLI flag with optional DoH resolver endpoint
2. Default DoH resolver: https://dns.google/dns-query (Google DNS over HTTPS)
3. Update agent container to use DoH client (e.g., cloudflared or dnscrypt-proxy)
4. Update iptables rules to allow HTTPS to DoH endpoint
5. Fall back to traditional DNS if DoH unavailable

Files to Modify

• src/cli.ts - Add --dns-over-https flag with optional resolver URL
• src/host-iptables.ts - Allow HTTPS traffic to DoH endpoints
• containers/agent/setup-iptables.sh - Configure DoH client in container
• containers/agent/Dockerfile - Install DoH client binary
• src/types.ts - Add DoH config to WrapperConfig interface
• README.md - Document new flag and security benefits

Testing

• Verify DNS queries use HTTPS when --dns-over-https enabled
• Confirm fallback to UDP DNS when DoH unavailable
• Test with custom DoH resolver endpoint
• Validate blocked domains still rejected with DoH

Acceptance Criteria

• --dns-over-https flag enables encrypted DNS queries
• DoH requests visible in Squid logs (HTTPS to dns.google)
• Legacy UDP DNS blocked when DoH enabled
• Custom DoH resolver endpoints supported
• Documentation updated with security rationale
  Related to [plan] security improvements from threat model review #306

AI generated by Plan Command for discussion #302

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] implement dns-over-https support #307

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	77.88%	77.05%	📉 -0.83%
Statements	77.94%	77.13%	📉 -0.81%
Functions	77.29%	77.12%	📉 -0.17%
Branches	71.00%	69.78%	📉 -1.22%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
src/docker-manager.ts	79.1% → 78.2% (-0.90%)	78.4% → 77.5% (-0.85%)
src/cli.ts	35.5% → 36.5% (+1.01%)	35.5% → 36.5% (+1.01%)

---

Coverage comparison generated by scripts/ci/compare-coverage.ts

[github-actions]

🔒 Security Review - PR #318

I've completed a security review of the DNS-over-HTTPS implementation. Overall security posture is good, but I found one issue that should be addressed before merging.

---

⚠️ Issue: Weak URL Validation (Defense-in-Depth Gap)

Severity: Medium (not immediately exploitable, but weakens defense-in-depth)

Location: src/cli.ts lines 140-160 (validateDohResolver() function)

Problem: The URL validation accepts DoH resolver URLs containing shell metacharacters:

// Current validation ACCEPTS these malicious inputs:
validateDohResolver('https://evil.com/dns-query; curl attacker.com')  ✅ ACCEPTED
validateDohResolver('https://evil.com/$(whoami)')                      ✅ ACCEPTED
validateDohResolver('https://evil.com/dns-query && rm -rf /')         ✅ ACCEPTED

Why this matters:

1. While entrypoint.sh properly double-quotes the variable (--upstream "$DOH_RESOLVER"), preventing immediate shell injection
2. The URL is passed to cloudflared, which may have its own parsing vulnerabilities
3. Defense-in-depth principle: validation should reject obviously malicious input at the earliest point

Recommendation: Add explicit validation to reject shell metacharacters:

export function validateDohResolver(resolver: string): string {
  let url: URL;
  try {
    url = new URL(resolver);
  } catch {
    throw new Error(`Invalid DoH resolver URL: ${resolver}`);
  }

  if (url.protocol !== 'https:') {
    throw new Error(`DoH resolver must use HTTPS (got: ${url.protocol})`);
  }

  if (!url.pathname || url.pathname === '/') {
    throw new Error(`DoH resolver URL must include a path (e.g., /dns-query)`);
  }

  // NEW: Reject URLs with shell metacharacters
  if (/[;$`&|<>]/.test(resolver)) {
    throw new Error('DoH resolver URL contains invalid shell metacharacters');
  }

  return resolver;
}

Test case to add:

it('should reject URLs with shell metacharacters', () => {
  expect(() => validateDohResolver('https://evil.com/dns-query; curl attacker.com')).toThrow('shell metacharacters');
  expect(() => validateDohResolver('https://evil.com/$(whoami)')).toThrow('shell metacharacters');
  expect(() => validateDohResolver('https://evil.com/`id`')).toThrow('shell metacharacters');
});

---

ℹ️ Minor Concern: Third-Party Dependency

Location: containers/agent/Dockerfile lines 26-34

The PR adds cloudflared from Cloudflare's package repository. This is reasonable (reputable source, GPG-verified), but introduces a new supply chain dependency.

Recommendation (optional): Consider pinning to a specific cloudflared version for reproducible builds:

apt-get install -y --no-install-recommends cloudflared=2024.1.5

---

✅ Positive Security Aspects

The implementation has several good security practices:

1. Proper DNS isolation: External UDP DNS completely blocked in DoH mode
2. iptables restrictions: Only Docker DNS (127.0.0.11) and local cloudflared (127.0.0.53) allowed
3. Domain allowlist validation: DoH endpoint domain must be in --allow-domains (lines 692-705)
4. Fail-secure: Container fails to start if cloudflared doesn't start within 10s (line 95)
5. No new capabilities: No additional Linux capabilities added
6. Proper shell quoting: $DOH_RESOLVER is double-quoted in entrypoint.sh line 84

---

Summary

Verdict: Approve with changes

Please add the URL validation fix before merging. The rest of the implementation is solid from a security perspective.

AI generated by Security Guard