WAIT — Stale — last commit 2y ago

• 17 active contributors
• EUPL-1.2 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 82% of recent commits
• ⚠ Non-standard license (EUPL-1.2) — review terms
• ⚠ Scorecard: marked unmaintained (0/10)
• ⚠ Scorecard: default branch unprotected (0/10)

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard}

dog is a command-line DNS client written in Rust that replaces dig with colored, human-friendly output and modern protocol support. It implements DNS queries over UDP/TCP/TLS/HTTPS, outputs JSON, and targets systems where dig's verbosity is unwieldy. The core capability is translating DNS queries into responses with optional protocol tunneling (DoT, DoH) and structured output formats. Workspace monorepo: root src/main.rs is the CLI binary, dns/ crate handles protocol parsing (record types in dns/src/record/*.rs), and dns-transport/ abstracts over UDP/TCP/TLS/HTTPS transports (dns-transport/src/{udp,tcp,tls,https}.rs). Output formatting (colors, JSON) is in root src/, test infrastructure includes shell completions and fuzz targets.

Systems administrators, DevOps engineers, and security researchers who need DNS lookups from the CLI but want readable output instead of dig's terse format. Also useful for developers debugging DNS resolution issues who prefer colored, structured output over traditional nameserver responses.

Actively maintained but pre-release (v0.2.0-pre as of Cargo.toml). Has CI via Travis, comprehensive shell completions (bash/zsh/fish/PowerShell), and organized issue templates. The codebase is ~254KB of Rust with workspace structure and fuzzing tests in dns/fuzz/, indicating production-grade quality but still iterating on the CLI interface.

Single-maintainer project (ogham@bsago.me) with pre-release versioning suggests breaking changes are possible. Depends on native TLS (dns-transport/with_nativetls) which adds platform-specific compilation complexity. No visible GitHub stars/release data provided, but the EUPL-1.2 license (stronger copyleft than MIT) may limit adoption in proprietary software.

Currently at v0.2.0-pre, suggesting active development toward a stable release. Dockerfile and Justfile present indicate containerization work. No recent commit info visible, but the comprehensive GitHub issue templates and organization suggest ongoing maintenance and issue triage.

git clone https://github.com/ogham/dog.git
cd dog
cargo build --release
./target/release/dog example.net

Daily commands:

cargo run -- example.net
cargo run -- example.net MX @1.1.1.1 -T
cargo run -- example.net --json

• src/main.rs — Entry point for the CLI application; orchestrates argument parsing, DNS query execution, and output formatting
• dns/src/lib.rs — Core DNS protocol library; defines record types, wire format parsing, and DNS message construction used by all queries
• dns-transport/src/lib.rs — Abstraction layer for DNS transport protocols (UDP, TCP, TLS, HTTPS); critical for protocol selection and network I/O
• src/options.rs — Command-line argument parsing and validation; defines the user-facing interface and all query configuration options
• src/output.rs — Response formatting module; handles colored terminal output and JSON serialization of DNS results
• src/resolve.rs — High-level DNS resolution orchestrator; bridges CLI options to transport layer and coordinates query execution
• dns/src/record/mod.rs — DNS record type definitions and display formatting; central to understanding all supported record types (A, AAAA, MX, TXT, etc.)

Add support for a new DNS record type

1. Create a new record type module in dns/src/record/ (e.g., dns/src/record/newtype.rs) implementing the record-specific parsing and formatting logic (dns/src/record/newtype.rs)
2. Add the new type to the RecordType enum in dns/src/types.rs and include a mapping entry in wire parsing (dns/src/types.rs)
3. Import and register the new record type in dns/src/record/mod.rs as a variant in the Record enum (dns/src/record/mod.rs)
4. Add test cases for wire parsing and building in dns/tests/wire_parsing_tests.rs and dns/tests/wire_building_tests.rs (dns/tests/wire_parsing_tests.rs)
5. Add integration test configuration in xtests/madns/ to verify the new record type works end-to-end (xtests/madns/newtype-records.toml)

Add a new transport protocol variant

1. Create a new transport implementation in dns-transport/src/newprotocol.rs with async transport methods (dns-transport/src/newprotocol.rs)
2. Add the new variant to the Transport enum in dns-transport/src/lib.rs and implement the transport trait (dns-transport/src/lib.rs)
3. Update dns-transport/src/auto.rs to include auto-selection logic if applicable (dns-transport/src/auto.rs)
4. Add command-line option flag in src/options.rs to allow users to select the new transport (src/options.rs)
5. Update transport selection logic in src/resolve.rs to handle the new protocol option (src/resolve.rs)
6. Add integration tests in xtests/live/newprotocol.toml to verify functionality (xtests/live/newprotocol.toml)

Add a new command-line output format

1. Define the new output format variant in src/output.rs output enum or formatting logic (src/output.rs)
2. Add a new command-line flag in src/options.rs to allow users to select the output format (src/options.rs)
3. Implement the formatting logic in src/output.rs to serialize DNS responses to the new format (src/output.rs)
4. Add color/styling support in src/colours.rs if the new format requires terminal coloring (src/colours.rs)
5. Add integration tests in xtests/features/outputs/ to verify the new format output is correct (xtests/features/outputs/newformat.txt)

• Rust with async/await (Tokio) — Enables safe concurrent DNS queries with zero-cost abstractions; prevents memory safety bugs in network code
• Workspace structure (dns + dns-transport + main) — Modularizes DNS protocol logic from transport and CLI, enabling reuse and independent testing of each layer
• DNS-over-TLS and DNS-over-HTTPS support — Provides privacy-preserving DNS lookups; aligns with modern security practices and supports encrypted DNS resolvers
• Colored terminal output + JSON export — Makes results human-readable in terminals while supporting machine parsing and scripting workflows

• Custom DNS protocol implementation vs. using an existing library

  • Why: Provides full control over wire format, error handling, and supported record types; enables deep integration with output formatting
  • Consequence: Higher maintenance burden; risk of protocol bugs; but enables precise behavior matching to design goals

• Modular transport abstraction (UDP/TCP/TLS/HTTPS)

  • Why: Allows users to choose the right protocol for their use case; enables auto-selection logic based on query requirements
  • Consequence: More code paths to test; potential performance overhead from abstraction; but greatly improves flexibility

• Synchronous API design exposed through CLI vs. async internals

  • Why: Users interact with a simple command-line tool; internally async for efficient resource use
  • Consequence: Simplified user model; potential latency in sequential queries; but excellent for one-shot CLI invoc

Feature gates for TLS (with_nativetls, with_rustls, with_nativetls_vendored) are mutually exclusive but not enforced in Cargo.toml, risking compile failures if multiple are enabled. Windows relies on ipconfig crate to discover nameservers—may fail silently if ipconfig service is disabled. build.rs uses datetime crate for compile-time version info, requiring correct system clock during build. dns/fuzz/ is a separate Cargo project inside the workspace; fuzzing tests require running from dns/fuzz/ directory, not root. No IDNA support by default unless with_idna feature is enabled, so international domain names will fail without it.

• DNS-over-TLS (DoT) — dog's dns-transport/src/tls.rs implements DoT (RFC 7858), wrapping DNS queries in TLS; essential for understanding how dog provides privacy vs plaintext UDP DNS
• DNS-over-HTTPS (DoH) — dns-transport/src/https.rs encodes DNS messages as HTTP requests per RFC 8484; dog's most modern protocol mode, required to understand POST/GET encoding and HTTP client integration
• EDNS (Extension Mechanisms for DNS) — OPT pseudo-record handling in dns/src/record/opt.rs and --edns flag parsing in src/main.rs; enables modern DNS features like DNSSEC and larger payloads, common source of compatibility bugs
• DNS Transaction ID (TXID) — Random 16-bit field generated by rand crate in src/main.rs and used in dns/src/lib.rs to match responses to queries; dog exposes --txid flag for testing, important for understanding DNS protocol state
• DNS Wire Format (Binary Serialization) — dns/src/lib.rs hand-implements DNS packet serialization/deserialization without a general parser combinator; understanding byte-level DNS encoding (labels, compression pointers) is essential for modifying record parsing
• Workspace Feature Gates (Cargo features) — Cargo.toml defines feature flags (with_tls, with_https, with_idna) conditionally compiled into binaries; dog uses this heavily to support optional TLS backends and reduce binary size, critical for cross-platform builds
• IDNA (Internationalized Domain Names in Applications) — Enabled via with_idna feature in Cargo.toml, converts Unicode domain names to ASCII punycode; necessary for non-ASCII domain lookups but adds dependency weight

• miekg/dns — Golang DNS library; dog was partly inspired by Go's simpler DNS APIs and is often compared to dig-style tools written in Go
• devsnd/dig — Another Rust DNS client alternative; direct competitor with similar goals but different architecture (worth studying for design choices)
• hickory-dns/hickory-dns — Rust async DNS resolver; dog could use hickory instead of hand-rolled parsing, or vice versa—ecosystem standard for DNS in Rust
• isc-projects/bind — Reference implementation of DNS and dig itself; understanding BIND's behavior and output is essential for dog's compatibility goals
• getdnsapi/getdns — Modern DNS client library supporting DoT/DoH; dog's DNS-over-TLS and HTTPS implementation parallels getdns's transport abstraction

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for DNS-over-TLS and DNS-over-HTTPS transports

The dns-transport crate has separate modules for TLS (tls.rs, tls_stream.rs) and HTTPS (https.rs) protocols, but there are no integration tests validating these transports work end-to-end. The dns/tests/ directory only has wire-level tests (wire_parsing_tests.rs, wire_building_tests.rs). Adding integration tests would ensure DoT and DoH queries work correctly against real nameservers and catch regressions in the transport layer.

• [ ] Create dns-transport/tests/integration_tests.rs with test cases for TLS transport
• [ ] Add test cases for HTTPS transport with various nameserver endpoints
• [ ] Test automatic transport selection in dns-transport/src/auto.rs
• [ ] Verify error handling from dns-transport/src/error.rs is correct

Add shell completion tests to validate completions/dog.{bash,fish,zsh,ps1}

The repo ships with shell completions for bash, fish, zsh, and PowerShell in the completions/ directory, but there are no tests validating these completions are syntactically correct or functionally complete. A new test suite could parse and validate completion files match the CLI interface defined in src/main.rs, catching issues before release.

• [ ] Create tests/shell_completions.rs to validate completion file syntax
• [ ] Parse completions/dog.bash, completions/dog.fish, completions/dog.zsh for correctness
• [ ] Verify all CLI flags from getopts parsing appear in completion definitions
• [ ] Add a test to validate PowerShell completion syntax in completions/dog.ps1

Add feature-gated unit tests for IDNA, TLS, and HTTPS modules

The Cargo.toml defines multiple optional features (with_idna, with_tls, with_https, with_nativetls, with_rustls), but the dns/src/record/ and dns-transport/src/ modules likely lack feature-gated tests. This makes it hard to verify each feature works in isolation. Adding targeted tests for each feature would catch build breakage when features are disabled.

• [ ] Add unit tests in dns/src/ for with_idna feature (IDNA domain parsing)
• [ ] Add unit tests in dns-transport/src/tls.rs for with_tls feature
• [ ] Add unit tests in dns-transport/src/https.rs for with_https feature
• [ ] Create a test matrix in .travis.yml or GitHub Actions to test all feature combinations

• Add support for DNSSEC validation (RRSIG/DNSKEY record parsing exists in dns/src/record/others.rs but no validation logic; implement dnssec-proto integration in dns/src/lib.rs)
• Implement colored output for EDNS OPT records (currently rendered plainly; follow ansi_term color patterns from src/main.rs to highlight EDNS flags and options)
• Add integration tests for DNS-over-HTTPS against real resolvers (dns-transport/src/https.rs works but has no end-to-end tests; create tests/ directory with fixtures for Cloudflare/Quad9 DoH endpoints)

• High · Outdated Base Image in Dockerfile — Dockerfile. The Dockerfile uses 'debian:buster-slim' which is an outdated Debian release (Debian 10, released 2019). This image may contain unpatched security vulnerabilities. Buster reached end-of-life in June 2024. Fix: Update to a current stable Debian release such as 'debian:bookworm-slim' or 'debian:12-slim' to ensure security patches are available.
• High · Outdated OpenSSL Version in Docker Runtime — Dockerfile. The Dockerfile installs 'libssl1.1' which is from OpenSSL 1.1.x series. OpenSSL 1.1 reached end-of-life on September 11, 2023, and no longer receives security updates. This creates a security gap for TLS/HTTPS operations. Fix: Update to 'libssl3' (OpenSSL 3.x) or rely on the base image's default SSL libraries. Verify compatibility with the application's TLS requirements.
• Medium · Missing SBOM and Dependency Pinning — Cargo.toml, Cargo.lock. The Cargo.toml uses loose version specifications (e.g., 'log = "0.4"', 'rand = "0.8"') without exact pinning. While Cargo.lock exists, this allows for automatic patch updates that could introduce breaking changes or vulnerabilities. No SBOM or dependency vulnerability scanning is evident. Fix: Consider using cargo-audit in CI/CD pipeline for automated vulnerability scanning. Review and test dependency updates regularly. Consider implementing stricter version pinning for critical dependencies in production builds.
• Medium · Broad Feature Flags with Weak Default Selection — Cargo.toml (features section). The default features include 'with_nativetls' which may use the system's native TLS implementation. The feature 'with_nativetls_vendored' suggests potential vendoring of TLS libraries, which can complicate security updates and vulnerability tracking. Fix: Document which TLS backend is recommended for production use. Consider making rustls (memory-safe implementation) the default instead of native TLS. Avoid vendoring when possible to leverage OS-level security patches.
• Medium · No Input Validation Framework Visible — dns/src/wire.rs, src/main.rs. As a DNS client handling user input and DNS responses, the codebase should include robust input validation. While DNS parsing logic exists in 'dns/src/wire.rs', no evidence of comprehensive validation framework is visible in the file structure. Fix: Ensure all DNS wire format parsing includes bounds checking and validates RFC compliance. Consider using fuzzing results (present in 'dns/fuzz/') to drive security improvements. Validate command-line arguments thoroughly in src/options.rs.
• Low · Travis CI Configuration Present — .travis.yml. The repository contains '.travis.yml' which is an older CI/CD configuration. While not a direct security vulnerability, it may indicate the project uses outdated CI infrastructure which could lack modern security scanning features. Fix: Migrate to GitHub Actions (which integrates natively) or another modern CI/CD platform with built-in security scanning, SAST, and dependency checking capabilities.
• Low · Limited TLS Certificate Validation Configuration — Dockerfile, dns-transport/src/https.rs, dns-transport/src/tls.rs. The Dockerfile includes 'ca-certificates' package, which is good for certificate validation. However, there's no visible configuration for certificate pinning or strict validation modes, which could be relevant for a DNS-over-HTTPS client. Fix: Review TLS certificate validation in dns-transport module. Ensure certificate verification is enforced by default. Consider implementing HPKP or certificate pinning for DNS-over-HTTPS endpoints.
• Low · Debug Information Disabled but LTO Enabled — Cargo.toml (profile.release). While debug symbols are stripped in dev builds (good), release builds use LTO with overflow checks. This is reasonable, but panic='abort' might mask some error conditions that should be gracefully handled, especially in a network client. Fix: Review critical error paths to ensure they handle panics grac

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ogham/dog shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ogham/dog repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ogham/dog.

What it runs against: a local clone of ogham/dog — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ogham/dog | Confirms the artifact applies here, not a fork | | 2 | License is still EUPL-1.2 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 745 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ogham/dog. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ogham/dog.git
#   cd dog
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ogham/dog and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ogham/dog(\\.git)?\\b" \\
  && ok "origin remote is ogham/dog" \\
  || miss "origin remote is not ogham/dog (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(EUPL-1\\.2)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"EUPL-1\\.2\"" package.json 2>/dev/null) \\
  && ok "license is EUPL-1.2" \\
  || miss "license drift — was EUPL-1.2 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "dns/src/lib.rs" \\
  && ok "dns/src/lib.rs" \\
  || miss "missing critical file: dns/src/lib.rs"
test -f "dns-transport/src/lib.rs" \\
  && ok "dns-transport/src/lib.rs" \\
  || miss "missing critical file: dns-transport/src/lib.rs"
test -f "src/options.rs" \\
  && ok "src/options.rs" \\
  || miss "missing critical file: src/options.rs"
test -f "src/output.rs" \\
  && ok "src/output.rs" \\
  || miss "missing critical file: src/output.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 745 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~715d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ogham/dog"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.