Skip to content

Commit 903630a

Browse files
crazydi4mondcrazydi4mond
committed
docs: add output formatters issue, update #3 and #4 to reference it
1 parent ec3afdf commit 903630a

3 files changed

Lines changed: 156 additions & 9 deletions

File tree

‎issues/dnst-scanner-03-basic-scan.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,14 @@ Test resolver IPs with connectivity checks and multi-domain DNS queries to ident
2626

2727
### Output
2828

29-
Filter out non-responding IPs and non-DNS servers. For each working resolver, include:
29+
Filter out non-responding IPs and non-DNS servers. See #5 (Output Formatters) for complete data structure.
3030

31-
- IP address
32-
- Response times for each query type
31+
Key fields per resolver:
32+
- IP address, ping and response times
3333
- Normal domain results (google.com, microsoft.com)
3434
- 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)
35+
- Tunnel domain resolution result
36+
- Classification: `clean` vs `censored`
3737

3838
### Implementation Notes
3939

‎issues/dnst-scanner-04-e2e-validation.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,10 @@ dnst-scanner scan --tunnel-domain t.example.com --e2e \
4747

4848
### Output
4949

50-
Extends basic scan output with E2E results:
51-
- `e2e_slipstream`: true/false/skipped
52-
- `e2e_dnstt`: true/false/skipped
53-
- `e2e_latency_ms`: tunnel round-trip time
50+
Extends basic scan output with E2E results. See #5 (Output Formatters) for complete data structure.
51+
52+
Key fields added per resolver:
53+
- `e2e.slipstream.domain`: health check domain used
54+
- `e2e.slipstream.success`: true/false
55+
- `e2e.slipstream.latency_ms`: tunnel round-trip time
56+
- `e2e.dnstt.*`: same structure for DNSTT

‎issues/dnst-scanner-05-output-formatters.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Output Formatters
2+
3+
**Depends on:** #3 (Basic Scan), #4 (E2E Validation)
4+
5+
## Summary
6+
7+
Define output data structure and formats for scanner results. Referenced by #3 and #4 for implementation.
8+
9+
**Motivation:** Consistent output structure enables dnstc to parse results reliably. Multiple formats support different use cases (JSON for programmatic, plain text for human).
10+
11+
## Data Structure
12+
13+
```json
14+
{
15+
"scan_metadata": {
16+
"timestamp": "2024-01-26T12:00:00Z",
17+
"total_input": 10000,
18+
"total_responding": 450,
19+
"tunnel_domain": "t.example.com",
20+
"e2e_enabled": true,
21+
"e2e_config": {
22+
"slipstream_health_domain": "hc-s.example.com",
23+
"dnstt_health_domain": "hc-d.example.com"
24+
}
25+
},
26+
"resolvers": [
27+
{
28+
"ip": "1.2.3.4",
29+
"ping_ms": 25,
30+
"dns_queries": {
31+
"google_com": {
32+
"success": true,
33+
"response_ms": 45,
34+
"result": "142.250.185.78"
35+
},
36+
"microsoft_com": {
37+
"success": true,
38+
"response_ms": 52,
39+
"result": "20.70.246.20"
40+
},
41+
"blocked_domain": {
42+
"domain": "facebook.com",
43+
"success": true,
44+
"response_ms": 38,
45+
"result": "157.240.1.35",
46+
"hijacked": false
47+
},
48+
"tunnel_domain": {
49+
"success": true,
50+
"response_ms": 120,
51+
"result": "ns.example.com"
52+
}
53+
},
54+
"classification": "clean",
55+
"e2e": {
56+
"slipstream": {
57+
"domain": "hc-s.example.com",
58+
"success": true,
59+
"latency_ms": 850
60+
},
61+
"dnstt": {
62+
"domain": "hc-d.example.com",
63+
"success": true,
64+
"latency_ms": 920
65+
}
66+
}
67+
},
68+
{
69+
"ip": "5.6.7.8",
70+
"ping_ms": 40,
71+
"dns_queries": {
72+
"google_com": { "success": true, "response_ms": 30, "result": "142.250.185.78" },
73+
"microsoft_com": { "success": true, "response_ms": 35, "result": "20.70.246.20" },
74+
"blocked_domain": {
75+
"domain": "facebook.com",
76+
"success": true,
77+
"response_ms": 15,
78+
"result": "10.10.34.35",
79+
"hijacked": true
80+
},
81+
"tunnel_domain": { "success": true, "response_ms": 95, "result": "ns.example.com" }
82+
},
83+
"classification": "censored",
84+
"e2e": {
85+
"slipstream": {
86+
"domain": "hc-s.example.com",
87+
"success": false,
88+
"error": "timeout"
89+
},
90+
"dnstt": {
91+
"domain": "hc-d.example.com",
92+
"success": false,
93+
"error": "timeout"
94+
}
95+
}
96+
}
97+
]
98+
}
99+
```
100+
101+
## Output Formats
102+
103+
### JSON (default for programmatic use)
104+
105+
Full structure as shown above. Use `--format json`.
106+
107+
### Plain Text (human readable)
108+
109+
```
110+
# dnst-scanner results - 2024-01-26T12:00:00Z
111+
# Input: 10000, Responding: 450
112+
# Tunnel domain: t.example.com
113+
# E2E: slipstream=hc-s.example.com, dnstt=hc-d.example.com
114+
115+
# IP Ping Class Tunnel E2E-Slip E2E-DNSTT
116+
1.2.3.4 25ms clean ok ok ok
117+
5.6.7.8 40ms censored ok fail fail
118+
```
119+
120+
Use `--format plain`.
121+
122+
## CLI
123+
124+
```bash
125+
# JSON to stdout (default)
126+
dnst-scanner scan --tunnel-domain t.example.com --format json
127+
128+
# Plain text to file
129+
dnst-scanner scan --tunnel-domain t.example.com --format plain --output results.txt
130+
131+
# JSON to file
132+
dnst-scanner scan --tunnel-domain t.example.com --output results.json
133+
```
134+
135+
## Field Definitions
136+
137+
| Field | Description |
138+
|-------|-------------|
139+
| `classification` | `clean` = resolves blocked domains properly, `censored` = hijacks to 10.x.x.x |
140+
| `hijacked` | true if blocked domain resolved to 10.x.x.x range |
141+
| `e2e.*.domain` | Health check domain used for the E2E test |
142+
| `e2e.*.success` | true if tunnel connection succeeded |
143+
| `e2e.*.latency_ms` | Round-trip time through tunnel |
144+
| `e2e.*.error` | Error message if failed |

0 commit comments

Comments
 (0)