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, HTTPS, and QUIC).

📦 Archived

This repository has been merged into the main rbmk repository with rbmk#76.

Please, update the import paths as follows:

github.com/rbmk-project/dnscore => github.com/rbmk-project/rbmk/pkg/dns/dnscore
github.com/rbmk-project/dnscore/dnscoretest => github.com/rbmk-project/rbmk/pkg/dns/dnscoretest

This repository is archived for historical reference.

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, DoH, and DoQ.
• 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.

Minimum Required Go Version

We maintain compatibility with the oldest supported version of Go as documented by the Go Release Policy and update our minimum required version of Go as needed.

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_quic_test.go
• example_tcp_test.go
• example_tls_test.go
• example_udp_test.go

for complete examples using DNS over HTTPS, QUIC, 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