Example Documentation: Service discovery with SRV
1. Goal
SRV records, priority, weight, port and target are checked.
2. What is done
The example validates local artifacts and creates evidence below work/.
3. Why it is done
DNS failures need evidence about RCODE, zone, TTL, delegation and resolver path.
4. Typical commands
dig example.test SOA +norecurse 2>/dev/null || true
named-checkzone example.test zones/db.example.test 2>/dev/null || true
5. Verify success
- Artifacts are valid.
- Evidence exists.
- No production data is used.
6. Common mistakes
- wrong RRtype.
- TTL ignored.
- resolver cache confused with authoritative data.
7. Security aspects
DNS configurations must not contain real secrets or provider credentials.
8. Realistic use
The pattern applies to change reviews, operations and incident response.
9. Workshop flow
- Read artifacts.
- Run script.
- Inspect evidence.
- Document risk.
10. Review matrix
| Review field | Expectation |
|---|---|
| Zone | Zone and name are clear. |
| Answer | RCODE is explained. |
| Operations | TTL and rollback are evaluated. |
Official References
- RFC 1034: https://datatracker.ietf.org/doc/html/rfc1034
- RFC 1035: https://datatracker.ietf.org/doc/html/rfc1035
- RFC 8499: https://www.rfc-editor.org/info/rfc8499/
- RFC 6891 EDNS(0): https://datatracker.ietf.org/doc/html/rfc6891
- RFC 4033 DNSSEC: https://datatracker.ietf.org/doc/html/rfc4033
- RFC 9364 DNSSEC BCP: https://www.rfc-editor.org/info/rfc9364/
Example Appendix: Evidence, Operations and Transfer
This appendix makes the example complete as a training component. It describes how a local DNS model becomes reliable analysis without touching production domains or provider credentials.
B.1 Define scope
Define scope is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.2 Validate artifacts
Validate artifacts is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.3 Name DNS role
Name DNS role is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.4 Interpret RCODE
Interpret RCODE is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.5 Evaluate TTL
Evaluate TTL is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.6 Check delegation
Check delegation is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.7 Record security boundaries
Record security boundaries is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.8 Write rollback
Write rollback is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.9 Clean evidence
Clean evidence is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.10 Run cleanup
Run cleanup is required because DNS failures are often explainable only by combining zone, resolver path, cache and transport. The assessment must state whether an artifact only explains, validates locally or would be applied to a real zone.
| Question | Expectation |
|---|---|
| What is affected? | Stub, resolver, authoritative server, zone, delegation, cache, DNSSEC or transport is named. |
| What is proven? | A file or output below work/evidence/ shows the finding. |
| What remains open? | Requirements for real zones or providers are documented as boundary. |
Review points:
- no production zones
- no real TSIG or DNSSEC keys
- no provider API tokens
- no unreviewed TTL or delegation changes
- cleanup possible by removing
work/
B.11 Completion
An example is complete when the script runs successfully, all artifacts are syntactically valid, the DNS role is named and evidence contains no confidential data.