Skip to main content
Glama
README.md
# dnsposture

Before you trust a domain — yours or anyone else's — it helps to read what it publishes about itself. dnsposture is a small local bridge to the hosted domainposture MCP service: you hand it a domain, and it brings back a dossier assembled from that domain's public DNS records, mail authentication policies, TLS certificate, HTTP behaviour and well-known files.

Nothing is stored or computed on your own machine. This package answers `tools/list` locally from the captured tool definitions and forwards every `tools/call` to the hosted service over a streamable-HTTP JSON-RPC session, returning whatever the service sends back unchanged.

The full captured surface is built: all 22 tools. (The registry record's description mentions 19 tools; the live capture enumerates 22, and the capture governs.)

## The tools

Nineteen `dossier_*` checks each take a required `domain`:

- **`dossier_dns`** — the full DNS profile: A, AAAA, NS, SOA, CAA and TXT records in parallel.
- **`dossier_mx`** — MX records sorted ascending by priority.
- **`dossier_spf`** — the SPF record decomposed into mechanisms and qualifiers, with the lookup count.
- **`dossier_dmarc`** — the DMARC policy from `_dmarc.<domain>`, parsed tag by tag.
- **`dossier_dkim`** — DKIM public keys probed per selector; pass `selectors` to choose which, or omit it to probe the common set.
- **`dossier_tls`** — the TLS certificate on port 443: issuer, validity, SANs, fingerprint.
- **`dossier_redirects`** — the HTTP redirect chain from `https://<domain>/`, up to 10 hops.
- **`dossier_headers`** — response headers with an audit of missing or misconfigured security headers.
- **`dossier_cors`** — a CORS preflight probe; optional `origin` and `method` refine the simulated request.
- **`dossier_web_surface`** — robots.txt, sitemap.xml and the home page's `<head>` metadata.
- **`dossier_dnssec`** — DNSSEC chain-of-trust: DS, DNSKEY and the AD flag.
- **`dossier_mta_sts`** — the MTA-STS policy: mode, mx list, max_age and policy id.
- **`dossier_tlsrpt`** — the TLS-RPT reporting policy from `_smtp._tls.<domain>`.
- **`dossier_whois`** — registrar, creation date, expiry date and registry statuses.
- **`dossier_ct_log`** — subdomains visible in Certificate Transparency logs.
- **`dossier_ai_crawlers`** — whether robots.txt allows, blocks or ignores the six major AI crawlers.
- **`dossier_llms_txt`** — whether the domain publishes an llms.txt index for AI agents.
- **`dossier_security_txt`** — the RFC 9116 security.txt disclosure channel, if present.
- **`dossier_full`** — all ten core dossier checks in parallel, in one response.

And three context lookups:

- **`ip_lookup`** — an IP address (required `ip`) resolved to geolocation, ASN, org and timezone.
- **`dns_lookup`** — one record type for one name (required `name` and `type`): A, AAAA, MX, TXT, NS or CNAME.
- **`user_agent_parse`** — a User-Agent string (required `ua`) parsed into browser, OS, device and engine, entirely locally upstream.

## Install and run

As an MCP server via npm:

```bash
npx -y @reneturcios/dnsposture mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "dnsposture": {
      "command": "npx",
      "args": ["-y", "@reneturcios/dnsposture", "mcp"]
    }
  }
}
```

As a container:

```bash
docker run -i ghcr.io/cloudcorprecords/dnsposture
docker run --rm ghcr.io/cloudcorprecords/dnsposture dossier_spf '{"domain":"example.com"}'
```

## CLI

One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:

```bash
dnsposture dossier_dmarc '{"domain":"example.com"}'
dnsposture dns_lookup '{"name":"example.com","type":"MX"}'
dnsposture ip_lookup '{"ip":"1.2.3.4"}'
dnsposture --version
```

Exit codes: `0` when the forwarded call succeeds, `1` when the upstream result is an error, and `2` for usage problems such as an unknown subcommand or a malformed JSON argument.

## Configuration

- `DOMAINPOSTURE_MCP_URL` — Overrides the upstream endpoint. The default is the pinned hosted endpoint, `https://www.domainposture.com/mcp/mcp`. (The override variable is a reconstruction added by this rebuild.)

No authentication header is ever sent: the registry record declares no auth headers for the upstream, and the tool surface was captured keyless.

Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with `dnsposture error:`.

## How forwarding works

`tools/list` is answered locally from the captured definitions, served exactly as captured (name, description and inputSchema; the capture carries no `title` key, so none is served). A `tools/call` opens a streamable-HTTP JSON-RPC session upstream — `initialize` (protocolVersion `2025-03-26`), then `notifications/initialized`, then the `tools/call` itself — and the `Mcp-Session-Id` header is carried on later requests when the upstream issues one. Replies may be plain JSON or SSE-framed; both are understood. The upstream result is handed back verbatim, `isError` flag and any extra fields included.

## Licence

MIT. See `LICENSE`.