dnscore - DNS Measurement Library

dnscore is a Go library designed for performing DNS measurements. Its high-level API, *dnscore.Resolver, is compatible with *net.Resolver. Its low-level API, *dnscore.Transport, provides granular control over performing DNS queries using specific protocols (including UDP, TCP, TLS, and HTTPS).

Features

• High-level *Resolver API compatible with *net.Resolver for easy integration.
• Low-level *Transport API allowing granular control over DNS requests and responses.
• Support for multiple DNS protocols, including UDP, TCP, DoT, and DoH.
• Utilities for creating and validating DNS messages.
• Optional logging for structured diagnostic events through log/slog.
• Handling of duplicate responses for DNS over UDP to measure censorship.

The package is structured to allow users to compose their own workflows by providing building blocks for DNS queries and responses. It uses the widely-used miekg/dns library for DNS message parsing and serialization.

Installation

go get github.com/rbmk-project/dnscore

Usage

High-Level API

The *dnscore.Resolver API is compatible with *net.Resolver.

See example_resolver_test.go for a complete example.

See also internal/cmd/lookup/main.go for a simple command line tool that demonstrates how to use the *dnscore.Resolver API along with log/slog to emit structured logs.

Low-Level Transport

The *dnscore.Transport API provides granular control over DNS queries and responses.

See

• example_https_test.go
• example_tcp_test.go
• example_tls_test.go
• example_udp_test.go

for complete examples using DNS over HTTPS, TCP, TLS, and UDP respectively.

See also internal/cmd/transport/main.go for a simple command line tool that demonstrates how to use the *dnscore.Transport API along with log/slog to emit structured logs.

Design

See DESIGN.md for an overview of the design.

Contributing

Contributions are welcome! Please submit a pull requests using GitHub. Use rbmk-project/issues to create issues and discuss features related to this package.

License

SPDX-License-Identifier: GPL-3.0-or-later