Skip to content

Commit 2fa0ce8

Browse files
committed
docs: add dnst-scanner basic scan issue draft
1 parent 4f41361 commit 2fa0ce8

1 file changed

Lines changed: 49 additions & 0 deletions

File tree

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Basic Scan (Step 1)
2+
3+
**Depends on:** #1 (Project Scaffolding), #2 (Resolver List Fetcher)
4+
5+
## Summary
6+
7+
Test resolver IPs with connectivity checks and multi-domain DNS queries to identify working resolvers and their behavior characteristics.
8+
9+
**Motivation:** First filtering step to reduce the large raw IP list (~10k+) to resolvers that respond and behave well. Different query types help identify resolvers suitable for DNS tunneling.
10+
11+
## Design
12+
13+
### Scan Steps
14+
15+
1. **Ping check**: Verify basic connectivity before DNS queries
16+
2. **Normal domain queries**: Test basic DNS resolution
17+
- `google.com` - commonly whitelisted in Iran
18+
- `microsoft.com` - another baseline test
19+
3. **Blocked domain query**: Test censorship behavior
20+
- `facebook.com` or `x.com`
21+
- Iranian resolvers often hijack and return `10.x.x.x` ranges
22+
- Resolvers that properly resolve blocked domains are often better for tunneling
23+
4. **Custom tunnel domain query**: Test if resolver can reach our NS subdomain
24+
- Provided via `--tunnel-domain` flag
25+
- Tests if resolver can resolve the NS record used for tunneling
26+
27+
### Output
28+
29+
Filter out non-responding IPs and non-DNS servers. For each working resolver, include:
30+
31+
- IP address
32+
- Response times for each query type
33+
- Normal domain results (google.com, microsoft.com)
34+
- Blocked domain result (actual IP vs hijacked 10.x.x.x)
35+
- Tunnel domain resolution result (success/fail)
36+
- Classification: `clean` (properly resolves blocked domains) vs `censored` (hijacks)
37+
38+
### Implementation Notes
39+
40+
- Concurrent workers with configurable parallelism (`--workers`)
41+
- Configurable timeout per resolver (`--timeout`)
42+
- Use Go's `net` package or [miekg/dns](https://github.com/miekg/dns) library
43+
44+
### Regarding NS vs A Record Testing
45+
46+
For basic scan, testing NS subdomain resolution is sufficient:
47+
- NS subdomain (e.g., `t.example.com`) returns NS record pointing to `ns.example.com`
48+
- This confirms resolver can reach our authoritative DNS
49+
- Actual tunnel data flow testing happens in E2E validation (#4) via health check endpoints

0 commit comments

Comments
 (0)