shohei

日本語 | 中文

shohei — Rust library for infrastructure diagnostics: DNS, DNSSEC, TLS certificates, email security, DNS propagation, and DANE/TLSA validation. MCP-integrated for AI agent automation. Built on hickory-dns with structured async APIs and a CLI for manual inspection.

• DNSSEC chain tree — see every DS, DNSKEY, and trust step from . to your domain; per-zone validation runs in parallel; add -v for key tags and algorithm names
• Iterative resolution trace — watch queries travel from root servers to TLD to authoritative NS
• Authority + Additional sections — see NS referrals and glue records when querying authoritative servers directly
• N-way server comparison — diff any number of resolvers simultaneously with --compare
• DoH, DoT, and DoQ — DNS-over-HTTPS, DNS-over-TLS, and DNS-over-QUIC built in
• Zone transfer (AXFR) — dump an entire zone from an authoritative server with --axfr
• Multiple record types — --type a --type aaaa --type mx queries all types concurrently in a single invocation
• Reverse DNS — -x 1.2.3.4 resolves PTR records for IPv4 and IPv6
• Stdin and file batch mode — pipe a list of domains or use -f domains.txt
• Human-readable TTL — 300 displayed as 5m, 3600 as 1h
• JSON output — pipe-friendly for scripting and automation
• Watch mode — auto-refresh at a set interval with --watch
• Short output — data values only, one per line, with --short
• Interactive TUI — browse records, DNSSEC chain, and trace in a single terminal window (--features tui)

Why shohei?

Most DNS tools are CLI-only and manual. shohei is different:

• Library-first design: Import into your Rust projects, CI/CD pipelines, or automation
• Structured output: JSON + serde types for agents and automation (not just colored tables)
• Trust chain validation: The only open-source library that validates DNS → DNSSEC → TLS → HTTP in one call
• Built for agents: MCP server integration lets Claude and other AI agents run automated infrastructure diagnostics
• Modern protocols: DoH, DoT, DoQ, DNSSEC, DANE/TLSA all built in
• Automation-friendly: Concurrent queries, batching, multi-resolver checks, and programmatic APIs

Compared to CLI-only alternatives (dog, drill, dig), shohei is composable—use it in tests, monitoring, CI/CD, or hand it to agents for automated diagnosis.

dig = BIND utils 9.16+; q = natesales/q; delv = BIND DNSSEC-validating resolver; drill = ldns-based

Demo

Iterative Resolution Trace

Watch Mode

Interactive TUI

Installation

As a library (Rust projects)

Add to your Cargo.toml:

[dependencies]
shohei = "0.4"

Then import and use:

use shohei::resolver::standard::query;

#[tokio::main]
async fn main() {
    let result = query("example.com", "A").await;
    println!("{:?}", result);
}

For full API documentation: cargo doc --open or docs.rs/shohei.

As a CLI (manual diagnosis)

cargo install shohei

Or download a pre-built binary from the releases page.

For the interactive TUI mode:

cargo install shohei --features tui

Library Examples

shohei is designed to be imported and composed in Rust projects. See the examples/ directory:

• propagation_check.rs — Check if a domain is propagated globally
• tls_chain_verify.rs — Validate TLS certificate chains (Phase 2)
• email_security.rs — Check email security records (Phase 1)

Run examples:

cargo run --example propagation_check -- example.com
cargo run --example tls_chain_verify -- example.com
cargo run --example email_security -- example.com

CLI Usage

The CLI is a convenient wrapper around the library for manual inspection and testing.

DNS record query

shohei google.com              # A records (default)
shohei google.com --type AAAA  # AAAA records
shohei google.com --type NS    # Nameservers
shohei gmail.com  --type MX    # Mail exchangers

# Multiple record types in one command
shohei google.com --type a --type aaaa --type mx

# Security / DNSSEC-related record types
shohei google.com --type caa       # Certificate Authority Authorization
shohei github.com --type sshfp     # SSH fingerprints
shohei _443._tcp.example.com --type tlsa  # DANE TLSA

Reverse DNS

Resolve the PTR record for an IP address. IPv4 and IPv6 are both supported.

shohei -x 1.1.1.1              # → one.one.one.one
shohei -x 2606:4700:4700::1111 # IPv6 reverse lookup

DNSSEC chain of trust

Validate the full DNSSEC chain from the root trust anchor down to the target domain. Each zone's DS and DNSKEY records are checked individually.

shohei cloudflare.com --dnssec

# Verbose: show key tags, algorithm names, and KSK/ZSK roles
shohei cloudflare.com --dnssec --verbose

Iterative resolution trace

Step through the full resolution path — root servers → TLD nameservers → authoritative nameservers.

shohei google.com --trace

Modern transports

# DNS-over-HTTPS
shohei google.com --doh https://dns.google/dns-query

# DNS-over-TLS
shohei google.com --dot 1.1.1.1:853

# DNS-over-QUIC
shohei google.com --doq 8.8.8.8

# Custom resolver
shohei google.com --server 8.8.8.8

Authority and Additional sections

When querying an authoritative server directly, shohei displays the Authority Section (NS referrals) and Additional Section (glue A/AAAA records) — matching dig's default behavior.

# Query the .com TLD nameserver for google.com — shows NS referral + glue records
shohei google.com -s 192.5.6.30 --no-recurse

# Query an authoritative nameserver directly
shohei example.com -s 199.43.135.53 --no-recurse --type ns

Force TCP

Force DNS queries over TCP instead of UDP. Useful for large responses that get truncated (TC bit set) or environments that block UDP/53.

shohei example.com -s 8.8.8.8 --tcp

Short output

Strip all decoration and return just the record data — one value per line. Ideal for shell scripting.

shohei gmail.com --type MX --short

Compare resolvers

Query the same domain from multiple DNS servers simultaneously and diff the results. Useful for detecting CDN anycast differences or verifying a new resolver. Repeat --compare for N-way comparison.

# Show that both servers return the same NS records
shohei cloudflare.com --type NS --server 8.8.8.8 --compare 1.1.1.1

# Reveal CDN-induced A record differences
shohei google.com --server 8.8.8.8 --compare 1.1.1.1

# N-way comparison across three resolvers
shohei google.com --server 8.8.8.8 --compare 1.1.1.1 --compare 9.9.9.9

Zone transfer (AXFR)

Fetch the complete zone from an authoritative server. Requires -s to specify the authoritative nameserver.

shohei zonetransfer.me --axfr -s 81.4.108.41

Batch / stdin mode

Pipe a newline-separated list of domains and shohei queries each one in sequence. Lines starting with # are ignored as comments. You can also read targets from a file with -f.

echo -e "google.com\nexample.com\ncloudflare.com" | shohei
cat domains.txt | shohei --type mx --short
shohei -f domains.txt --type mx --short

Watch mode

Repeat the query every N seconds and auto-refresh the display. Press Ctrl+C to stop.

shohei google.com --watch 5         # refresh every 5 seconds
shohei google.com --type A --watch 10

Output formats

shohei google.com --output json   # JSON for scripting
shohei google.com --output plain  # No colors (CI-friendly)

Interactive TUI (requires --features tui)

Pre-loads records, DNSSEC chain, and trace in parallel, then presents all three as navigable views.

shohei google.com --tui

 shohei — google.com
┌─ Records ──────────────────────────────────────────────────────────┐
│ Query: google.com (A IN)                                           │
│                                                                    │
│ NAME                                    TTL   TYPE   DATA          │
│ ────────────────────────────────────────────────────────────────── │
│ google.com.                             120   A      142.250.x.x   │
│ ...                                                                │
└────────────────────────────────────────────────────────────────────┘
 [r] Records  [d] DNSSEC  [t] Trace  [↑↓/jk] Scroll  [q] Quit

Options

Trust States

Integrations & AI Agents

Current (v0.4.0+)

• Library: Rust projects via use shohei;
• CLI: Manual diagnosis via terminal
• JSON output: Scripting and tooling

Planned (v0.5.0+)

• MCP Server: AI agents (Claude, etc.) can call shohei diagnostics
• GitHub Actions: Automated DNS/TLS checks in CI/CD workflows
• Terraform Module: Infrastructure validation
• Ansible Module: Playbook integration

See docs/INTEGRATIONS.md for full details.

Built with

• hickory-dns — DNSSEC, DoH, DoT support
• clap — CLI argument parsing
• ratatui — TUI framework (optional tui feature)
• owo-colors — Terminal colors
• comfy-table — Record table rendering

License

MIT — see LICENSE