feat(cli): restrict dns traffic to trusted servers only

[Mossaka]

Addresses DNS-based data exfiltration vulnerability where DNS traffic
(port 53) was allowed to ANY destination, enabling attackers to encode
sensitive data in DNS queries to malicious DNS servers.

Signed-off-by: Jiaxiao (mossaka) Zhou [email protected]

[github-actions]

Test Coverage Report

Metric	Coverage	Covered/Total
Lines	53.1%	351/661
Statements	52.95%	358/676
Functions	60.56%	43/71
Branches	43.56%	88/202

Coverage Thresholds

The project has the following coverage thresholds configured:

• Lines: 38%
• Statements: 38%
• Functions: 35%
• Branches: 30%

---

Coverage report generated by `npm run test:coverage`

[Copilot]

Pull request overview

This PR implements DNS traffic restriction to trusted servers only, addressing a DNS-based data exfiltration vulnerability. The change prevents attackers from encoding sensitive data in DNS queries to malicious DNS servers by restricting DNS traffic (port 53) to a configurable list of trusted servers.

Key changes:

• Added --dns-servers CLI option (default: Google DNS 8.8.8.8, 8.8.4.4) with IPv4 and IPv6 support
• Implemented host-level iptables/ip6tables filtering to block DNS queries to non-whitelisted servers
• Updated container scripts to configure DNS based on trusted server list
• Docker's embedded DNS (127.0.0.11) remains accessible for container name resolution

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/types.ts	Added dnsServers configuration field with comprehensive documentation
src/host-iptables.ts	Implemented DNS filtering via iptables (IPv4) and ip6tables (IPv6 chain) with trusted server allowlist
src/host-iptables.test.ts	Updated tests to verify DNS filtering for IPv4/IPv6 servers and chain cleanup
src/cli.ts	Added IPv4/IPv6 validation functions and --dns-servers CLI option parsing
src/cli.test.ts	Added comprehensive tests for IP validation and DNS server parsing
src/cli-workflow.ts	Updated workflow to pass DNS servers to iptables setup
src/docker-manager.ts	Configured container DNS servers and passed to container via AWF_DNS_SERVERS env var
containers/agent/setup-iptables.sh	Added container-level NAT rules for trusted DNS servers
containers/agent/entrypoint.sh	Updated /etc/resolv.conf generation to use trusted DNS servers
docs/environment.md	Documented AWF_DNS_SERVERS internal environment variable
docs-site/src/content/docs/reference/security-architecture.md	Updated DNS tunneling mitigation documentation
docs-site/src/content/docs/reference/cli-reference.md	Added --dns-servers CLI option documentation
README.md	Added DNS server restriction security section with examples
CLAUDE.md	Added comprehensive DNS configuration documentation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Mossaka]

@copilot open a new pull request to apply changes based on the comments in this thread

[Copilot]

@Mossaka I've opened a new pull request, #69, to work on those changes. Once the pull request is ready, I'll request review from you.

[Mossaka]

@copilot can you address the following suggestions?

1. Potential IPv6 iptables failure (Medium Priority)

In containers/agent/setup-iptables.sh, there's no check for ip6tables availability
before using it:

ip6tables -t nat -F OUTPUT 2>/dev/null || true

While errors are suppressed with || true for the flush command, the later IPv6
rules don't have this protection:

for dns_server in "${IPV6_DNS_SERVERS[@]}"; do
ip6tables -t nat -A OUTPUT -p udp -d "$dns_server" --dport 53 -j RETURN
# No error handling if ip6tables is unavailable

Suggestion: Add a check or wrap IPv6 rules in conditional logic:
if command -v ip6tables &>/dev/null && ip6tables -L -n &>/dev/null; then
# Add IPv6 rules
fi

2. Host iptables missing IPv6 rules (Medium Priority)

src/host-iptables.ts only implements IPv4 rules. If IPv6 DNS servers are
configured, the host-level firewall won't allow them:

// Only IPv4 is handled
for (const dnsServer of dnsServers) {
await execa('iptables', ['-t', 'filter', '-A', 'FW_WRAPPER', '-p', 'udp', '-d',
dnsServer, '--dport', '53', '-j', 'ACCEPT']);

Suggestion: Add ip6tables support for IPv6 DNS servers in host-iptables.ts, or
document this as a limitation.

[Copilot]

@Mossaka I've opened a new pull request, #77, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Security concern: The IPv6 multicast (ff00::/8) and link-local (fe80::/10) blocking rules should be placed before the DNS rules, not after. Currently, if an attacker specifies a multicast or link-local IPv6 address as a "trusted DNS server", it would be allowed by the DNS rules before being rejected by the multicast/link-local rules. Moving these blocks earlier in the chain ensures that multicast and link-local traffic is always rejected regardless of DNS server configuration.