# dug

> Live domain and network diagnostics. Every answer is a fresh lookup: nothing
> is precomputed and nothing is stored between requests, so there is no history
> to query and no dataset to page through.

Every endpoint is a GET, needs no key and no signup, and answers in three
representations of the same data:

- text/plain  the default for curl and other terminal clients
- application/json  send Accept: application/json, or ?format=json
- text/html  the browser app at /

Ask for text explicitly with ?format=text. Responses carry
Vary: Accept, User-Agent, and a Cache-Control whose lifetime is derived from
the answer itself, floored at 30 seconds.

## Calling

    curl https://$HOST/tls/github.com
    curl https://$HOST/dig/example.com/MX
    curl -H 'Accept: application/json' https://$HOST/mail/github.com

The query form is equivalent and is what the browser app uses:

    curl 'https://$HOST/api/tls?command=TLS&target=github.com'

## Commands

### resolution

- `GET /dig/{target}` — every record type, or just one
  - `target` (required): a domain name
  - `type` (optional): a single record type to ask for, such as MX, for example `MX`
- `GET /prop/{target}` — agreement across the fixed resolver list
  - `target` (required): a domain name
- `GET /ttl/{target}` — remaining lifetime per record
  - `target` (required): a domain name

### delegation

- `GET /ns/{target}` — root to tld to authoritative walk
  - `target` (required): a domain name
- `GET /dnssec/{target}` — chain of trust, ds and dnskey
  - `target` (required): a domain name

### registration

- `GET /rdap/{target}` — registration data with status codes decoded
  - `target` (required): a domain name
- `GET /watch/{target}` — domain and certificate expiry, computed now
  - `target` (required): a domain name

### transport

- `GET /tls/{target}` — chain, validity spans, protocols
  - `target` (required): a hostname
- `GET /http/{target}` — headers, redirect chain, security headers
  - `target` (required): a hostname
- `GET /trace/{target}` — dns, tcp, tls and ttfb timing
  - `target` (required): a hostname

### mail

- `GET /mail/{target}` — mx, spf, dkim, dmarc and alignment policy
  - `target` (required): a domain name
- `GET /spf/{target}` — include tree, against the ten lookup limit
  - `target` (required): a domain name

### addressing

- `GET /ip/{target}` — reverse dns, asn, prefix, neighbours
  - `target` (required): an ip address
- `GET /asn/{target}` — prefixes and address space
  - `target` (required): an as number, with or without the AS prefix
- `GET /net/{target}/{bits}` — address space grid, a /24 or smaller
  - `target` (required): a network in cidr form, a /24 or smaller

### reachability

- `GET /ping/{target}` — icmp echo, round trip time and packet loss
  - `target` (required): a hostname or an ip address
  - `count` (optional): how many echoes to send, 1 to 10, for example `8`
- `GET /route/{target}` — the hops between here and there, with reverse dns
  - `target` (required): a hostname or an ip address
- `GET /ports/{target}` — which tcp ports are open, closed or filtered
  - `target` (required): a hostname or an ip address
  - `ports` (optional): ports to try, comma separated, ranges allowed, for example `22,80,443`

### meta

- `GET /vs/{target}/{other}` — two domains side by side
  - `target` (required): a domain name, compared against `other`
  - `other` (required): the second domain name, for example `github.com`
- `GET /src` — resolver list, cache ceilings, upstream health

## Response shape

Every command returns the same envelope, whatever it asked upstream:

    command           the verb that ran
    target            what it ran against, normalised
    verdict           {state: ok|warn|none, headline, detail} — the answer, in a sentence
    blocks            the evidence, each naming a display component and its props
    notes             provenance and limits
    degraded          upstreams that failed, when the rest of the answer still stands
    ttl               seconds this answer stays valid
    elapsed_ms        wall time
    upstream_queries  how many lookups it cost

An upstream failure is not an HTTP error. The status stays 200, the failure is
named in "degraded", and the parts that did answer are still returned. Read
"degraded" before trusting a screen to be complete.

## Machine-readable

    /llms.txt      this file
    /openapi.json  OpenAPI 3.1 for every command above
    /api/mcp       MCP server, Streamable HTTP, one tool per command

The browser app also registers the same commands as WebMCP tools on
navigator.modelContext, so an in-page agent can call them without leaving the
page.

## Limits

- at most 64 upstream queries per request
- resolvers are a fixed list of 6 and cannot be pointed elsewhere: Cloudflare (1.1.1.1), Google (8.8.8.8), Quad9 (9.9.9.9), OpenDNS (208.67.222.222), AdGuard (94.140.14.14), Control D (76.76.2.0)
- outbound ports are an allowlist: 43, 53, 80, 443. PORTS waives it, and only it
- every destination is validated immediately before connect, so private, loopback, link-local and reserved space is unreachable through this tool
- PORTS completes a TCP handshake, so it appears in the target's logs as a connection from this deployment

## Deliberately not here

- monitoring and alerts — nothing is stored between queries
- registrant lookup — redacted at source, and there is an official channel
- reaching private space — every destination is validated, on every command