177 lines
4.4 KiB
Markdown
177 lines
4.4 KiB
Markdown
# DNS Leak Detector - Implementation Guide (v0.4)
|
|
|
|
This document explains how to implement the DNS leak detector as a new subcrate in WTFnet.
|
|
|
|
## 1) New crate: `wtfnet-dnsleak`
|
|
|
|
### 1.1 Module layout
|
|
|
|
crates/wtfnet-dnsleak/src/
|
|
- lib.rs
|
|
- policy.rs # safe path constraints + presets
|
|
- sensor.rs # passive capture -> normalized TrafficEvent stream
|
|
- classify.rs # transport classification + confidence
|
|
- route.rs # interface/route classification (tunnel/physical/loopback)
|
|
- rules.rs # Leak-A/B/C/D evaluation
|
|
- report.rs # LeakEvent + SummaryReport builders
|
|
- privacy.rs # full/redacted/minimal redaction logic
|
|
|
|
## 2) Core data types
|
|
|
|
### 2.1 TrafficEvent (raw from sensor)
|
|
Fields:
|
|
- ts: timestamp
|
|
- proto: udp/tcp
|
|
- src_ip, src_port
|
|
- dst_ip, dst_port
|
|
- iface_name (capture interface if known)
|
|
- payload: optional bytes (only for plaintext DNS parsing)
|
|
|
|
### 2.2 ClassifiedEvent
|
|
Adds:
|
|
- transport: udp53/tcp53/dot/doh/unknown
|
|
- doh_confidence: HIGH/MEDIUM/LOW (only if doh)
|
|
- qname/qtype: nullable
|
|
|
|
### 2.3 EnrichedEvent
|
|
Adds:
|
|
- route_class: loopback/tunnel/physical/unknown
|
|
- process info: pid/ppid/name (nullable)
|
|
- attribution_confidence: HIGH/MEDIUM/LOW/NONE
|
|
- attrib_failure_reason: optional string
|
|
|
|
### 2.4 LeakEvent (final output)
|
|
Adds:
|
|
- leak_type: A/B/C/D
|
|
- severity: P0..P3
|
|
- policy_rule_id
|
|
- evidence: minimal structured evidence
|
|
|
|
## 3) Platform integration: Process Attribution Engine (PAE)
|
|
|
|
### 3.1 Trait addition (wtfnet-platform)
|
|
|
|
Add:
|
|
trait FlowOwnerProvider {
|
|
fn owner_of(
|
|
&self,
|
|
proto: Proto,
|
|
src_ip: IpAddr,
|
|
src_port: u16,
|
|
dst_ip: IpAddr,
|
|
dst_port: u16,
|
|
) -> FlowOwnerResult;
|
|
}
|
|
|
|
FlowOwnerResult:
|
|
- pid, ppid, process_name (optional)
|
|
- confidence: HIGH/MEDIUM/LOW/NONE
|
|
- failure_reason: optional string
|
|
|
|
Design rule: attribution is best-effort and never blocks leak detection.
|
|
|
|
## 4) Transport classification logic
|
|
|
|
### 4.1 Plain DNS
|
|
Match:
|
|
- UDP dst port 53 OR TCP dst port 53
|
|
Parse QNAME/QTYPE from payload.
|
|
|
|
### 4.2 DoT
|
|
Match:
|
|
- TCP dst port 853
|
|
|
|
### 4.3 DoH (heuristic)
|
|
Match candidates:
|
|
- TCP dst port 443 AND (one of):
|
|
- dst IP in configured DoH resolver list
|
|
- dst SNI matches known DoH provider list (if available)
|
|
- frequent small HTTPS bursts pattern (weak)
|
|
|
|
Attach confidence:
|
|
- MEDIUM: known endpoint match
|
|
- LOW: traffic-shape heuristic only
|
|
|
|
## 5) Policy model
|
|
|
|
Policy defines "safe DNS path" constraints:
|
|
- allowed interfaces
|
|
- allowed destinations (IP/CIDR)
|
|
- allowed processes
|
|
- allowed ports
|
|
|
|
A DNS event is a leak if it violates safe-path constraints.
|
|
|
|
### 5.1 Built-in profiles
|
|
|
|
full-tunnel:
|
|
- allow DNS only via tunnel iface or loopback stub
|
|
- any UDP/TCP 53 on physical iface => Leak-A
|
|
|
|
proxy-stub (default):
|
|
- allow DNS only to loopback stub
|
|
- allow stub upstream only to proxy destinations
|
|
- flag direct DoH/DoT outside proxy path => Leak-C
|
|
|
|
split:
|
|
- allow plaintext DNS only for allowlist
|
|
- enforce unknown => proxy resolve (Leak-B)
|
|
|
|
## 6) Leak rules (A/B/C/D)
|
|
|
|
Leak-A (plaintext escape):
|
|
- transport udp53/tcp53
|
|
- route_class != allowed
|
|
- dst not in allowed destination set
|
|
|
|
Leak-B (split policy intent leak):
|
|
- qname matches proxy-required set or "unknown"
|
|
- query observed going to ISP/domicile resolver or non-tunnel iface
|
|
|
|
Leak-C (encrypted bypass):
|
|
- DoT or DoH flow exists
|
|
- not via approved egress path (iface/destination)
|
|
|
|
Leak-D (mismatch indicator):
|
|
- correlate qname to later TCP/TLS flows (optional v0.4 NICE)
|
|
|
|
## 7) Privacy modes
|
|
|
|
Because domains and cmdlines are sensitive, support:
|
|
- Full: store full qname and cmdline
|
|
- Redacted (default): hash qname or keep eTLD+1 only; truncate cmdline
|
|
- Minimal: no domains/cmdline; keep leak counts + resolver IPs + process name
|
|
|
|
Privacy mode applies in report builder, not in sensor.
|
|
|
|
## 8) CLI integration
|
|
|
|
Add under `dns` command group:
|
|
|
|
- `dns leak status`
|
|
- `dns leak watch`
|
|
- `dns leak report`
|
|
|
|
`watch` returns:
|
|
- summary report (human) by default
|
|
- `--json` returns structured report with events list
|
|
|
|
## 9) Recommended incremental build plan
|
|
|
|
Phase 1 (core passive detection):
|
|
- sensor: udp/tcp capture
|
|
- classify: udp53/tcp53/dot
|
|
- parse plaintext qname/qtype
|
|
- policy: allowlist + allowed interfaces/dests
|
|
- leak rules: Leak-A + Leak-C (DoT)
|
|
- report: events + summary
|
|
|
|
Phase 2 (process attribution + DoH heuristics):
|
|
- platform FlowOwnerProvider impls
|
|
- DoH heuristic classification + confidence
|
|
- privacy modes
|
|
|
|
Phase 3 (optional correlation / Leak-D):
|
|
- flow tracker correlating DNS -> TCP/TLS connect events
|
|
- mismatch indicator output
|