Domainposture

Context lookup: Resolve an IPv4 or IPv6 address to its geolocation, ASN, org name, and city/country. Use when you need network or location context for a raw IP address; prefer dns_lookup or dossier_dns for hostname resolution. Queries ipinfo.io with a server-side token — the token is never exposed to callers. Returns a JSON object with fields ip, city, region, country, org, loc, and timezone. On failure, returns an error string describing what went wrong.

Context lookup: Resolve a single DNS record type (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, or SRV) and return the raw answers. Use for quick, targeted lookups of one record type; prefer dossier_dns for a full multi-type DNS audit in parallel, or dossier_full for a complete domain health check. Queries Cloudflare DoH (1.1.1.1/dns-query) over HTTPS, follows CNAME chains, 5 s timeout. Returns a JSON array of answer objects with name, type, and data fields. On error, returns a string describing the DNS failure.

Core dossier check: Fetch a domain's full DNS profile — A, AAAA, NS, SOA, CAA, and TXT records — all in parallel. Use as the first step of a domain audit or when you need a comprehensive DNS snapshot in one call; prefer dns_lookup for a single record type, or dossier_full for all 10 dossier checks at once. Fires six Cloudflare DoH (1.1.1.1) queries concurrently, each with a 5 s timeout. Returns a CheckResult discriminated union: on success, {status:"ok", records:{a, aaaa, ns, soa, caa, txt}}; on failure, {status:"error", reason}.

Core dossier check: Look up a domain's MX (mail exchanger) records and return them sorted ascending by priority. Use when verifying inbound-mail routing or as a precursor to SPF or DMARC checks; prefer dns_lookup with type=MX if you only need the raw DNS answer without the ranked view. Queries Cloudflare DoH (1.1.1.1), follows CNAME aliases, 5 s timeout. Returns a CheckResult discriminated union: on success, {status:"ok", records:[{exchange, priority},...]} sorted by priority; on failure, {status:"error", reason}.

Core dossier check: Retrieve and parse a domain's SPF record, decomposing it into mechanisms and qualifiers. Use to verify email sender policy, debug delivery failures, or check the 10-lookup limit; pair with dossier_dmarc for full email-auth coverage, or use dns_lookup with type=TXT for the raw record only. Fetches TXT records via Cloudflare DoH (1.1.1.1), 5 s timeout, locates the v=spf1 record and parses all mechanisms. Returns a CheckResult: on success, {status:"ok", raw, mechanisms:[{type, value, qualifier},...], lookupCount}; on failure, {status:"error", reason}.

Core dossier check: Retrieve and parse a domain's DMARC policy from its _dmarc.<domain> TXT record, returning all tags. Use to audit email authentication policy, verify the p (policy) and rua (reporting) settings, or confirm alignment mode; pair with dossier_spf and dossier_dkim for complete email-auth coverage. Queries _dmarc.<domain> via Cloudflare DoH (1.1.1.1), 5 s timeout; parses each tag=value pair. Returns a CheckResult: on success, {status:"ok", raw, tags:{p, rua, ruf, adkim, aspf,...}}; on failure, {status:"error", reason}.

Core dossier check: Probe a domain's DKIM public keys by querying <selector>._domainkey.<domain> for each selector. Use to verify signing configuration or discover active selectors; supply selectors when you know the ESP's selector, or omit to probe six common selectors (default, google, k1, selector1, selector2, mxvault). Issues parallel Cloudflare DoH (1.1.1.1) TXT queries per selector, 5 s timeout each. Returns a CheckResult: {status:"ok", found:[{selector, publicKey, raw},...], notFound:[...]} or {status:"error", reason}.

Core dossier check: Fetch and inspect the TLS certificate presented by a domain on port 443, returning chain details and validity period. Use to verify certificate expiry, issuer, Subject Alternative Names, or detect mismatched or self-signed certs; not a full cipher-suite scanner. Performs a TLS handshake from the server edge, 5 s timeout; extracts the leaf certificate. Returns a CheckResult: on success, {status:"ok", subject, issuer, validFrom, validTo, daysRemaining, sans, fingerprint}; on failure, {status:"error", reason}.

Core dossier check: Trace the full HTTP redirect chain starting from https://<domain>/, recording each hop's status code and destination URL. Use to debug redirect loops, verify HTTP→HTTPS upgrades, or audit link shorteners; stops at 10 hops to prevent infinite loops. Follows Location headers with fetch (no auto-redirect), 5 s per hop. Returns a CheckResult: on success, {status:"ok", hops:[{url, statusCode, redirectsTo},...], final}; on failure, {status:"error", reason}.

Core dossier check: Fetch https://<domain>/ and return all HTTP response headers, with an audit highlighting missing or misconfigured security headers. Use to review CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy; for redirect tracing use dossier_redirects instead. Single GET via fetch, 5 s timeout, captures raw response headers before any redirect is followed. Returns a CheckResult: on success, {status:"ok", headers:{...}, securityAudit:[{header, present, value},...]}; on failure, {status:"error", reason}.

Core dossier check: Send a CORS preflight OPTIONS request to https://<domain>/ and return the access-control-* response headers. Use to verify CORS policy for a specific origin-method pair, or to check whether a domain allows cross-origin requests; provide origin and method to simulate a precise preflight, or omit to use defaults (origin: https://domainposture.com, method: GET). Single OPTIONS request via fetch, 5 s timeout. Returns a CheckResult: on success, {status:"ok", headers:{access-control-allow-origin,...}}; on failure, {status:"error", reason}.

Core dossier check: Snapshot a domain's public web surface: robots.txt, sitemap.xml, and the home-page <head> metadata (title, description, OpenGraph, Twitter cards). Use for SEO audits, content discovery, or verifying metadata before sharing; for HTTP headers use dossier_headers, for redirect behavior use dossier_redirects. Fetches /, /robots.txt, and /sitemap.xml concurrently via HTTPS, 5 s each; parses <head> with a lightweight HTML parser. Returns a composite CheckResult: {status:"ok", meta:{title, description, og, twitter}, robots, sitemapPresent} or {status:"error", reason}.

Context lookup: Parse a User-Agent header string into structured browser, OS, device type, and rendering-engine components. Use to identify client capabilities from a raw UA string, e.g. when analysing server logs or request headers; does not perform any network lookups — entirely local parsing. Runs synchronously using the ua-parser-js library with no external calls. Returns a JSON object with browser.name, browser.version, os.name, os.version, device.type, device.vendor, and engine.name fields; unknown fields are empty strings.

Core dossier check: Verify DNSSEC chain-of-trust for a domain (DS, DNSKEY, AD flag). Use to confirm the zone is signed and resolvers accept the chain; prefer dossier_dns for raw record types or dossier_full for the complete audit. Fires Cloudflare DoH DS and DNSKEY queries with DO=1; 8s timeout. Returns a CheckResult discriminated union with { dnssecEnabled, adFlag, ds[], dnskey[] } on success.

Core dossier check: Fetch and validate a domain's MTA-STS policy (mode, mx, max_age, policy id). Use to confirm inbound SMTP is locked to TLS for this domain. Resolves the _mta-sts TXT record, then fetches the policy from mta-sts.<domain>/.well-known/mta-sts.txt; 10s timeout. Returns a CheckResult; not_applicable when no MTA-STS TXT is published.

Core dossier check: Look up a domain's TLS-RPT (SMTP TLS Reporting) policy. Use to confirm the domain receives reports of SMTP-TLS failures. Resolves _smtp._tls.<domain> TXT via Cloudflare DoH; 5s timeout. Returns a CheckResult; not_applicable when no record is published.

Core dossier check: Look up the registrar, creation date, expiry date, and registry statuses for a domain. Use for ownership/expiry audit. Queries WHOIS over TCP/43 via the `whoiser` library; 15s timeout. Returns a CheckResult; not_applicable when the registry refuses or redacts the query (common on cloud IPs).

Core dossier check: Discover subdomains visible in Certificate Transparency logs. Use for attack-surface mapping; prefer dossier_full when running a complete audit. Queries crt.sh first, falls back to certspotter; capped at 100 unique subdomains; 10s timeout. Returns a CheckResult with { subdomains[], wildcards[], certCount, source }.

Core dossier check: Report a domain's AI-crawler policy — whether robots.txt allows, blocks, or is silent on the six major AI agents (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot, meta-externalagent). Use to answer "does this site let AI models train on / retrieve its content?" in a posture audit. Fetches https://<domain>/robots.txt, follows redirects (off-site redirect = no policy), 10s timeout; parses robots groups. Returns a CheckResult; on success { hasRobots, agents: { <agent>: 'allowed' | 'blocked' | 'unspecified' } }. A missing robots.txt is data, not an error (every agent unspecified).

Core dossier check: Detect whether a domain publishes an llms.txt at its root — the emerging convention that gives AI agents a curated markdown index of a site's content. Use in a content-posture audit to confirm a site guides (rather than ignores) AI agents. Fetches https://<domain>/llms.txt, 10s timeout; requires a non-HTML content type and a leading markdown H1 (a catch-all SPA answering 200 with HTML is NOT an llms.txt). Returns a CheckResult; on success { bytes, firstLine }; not_applicable when absent.

Core dossier check: Verify a domain publishes a security.txt (RFC 9116) at /.well-known/security.txt — the standard machine-readable channel for reporting vulnerabilities. Use in a security audit to confirm researchers have a published disclosure route; its absence is a genuine (minor) audit flag. Fetches https://<domain>/.well-known/security.txt, 10s timeout; requires a non-HTML content type and a Contact: field. Returns a CheckResult; on success { contact[], expires, raw }; not_applicable when absent.

Aggregate dossier check: Run all 10 Domain Dossier checks — dns, mx, spf, dmarc, dkim, tls, redirects, headers, cors, web-surface — in parallel and return all results in a single response. Use when you need a comprehensive domain health snapshot in one call; counts as ONE paywall call regardless of how many checks run. For a single focused check, prefer the individual dossier_* tools to minimise latency. Fires all 10 checks concurrently via Cloudflare DoH or direct HTTPS, 5 s per-check timeout. Returns a JSON object keyed by check id (dns, mx, etc.), each value a CheckResult discriminated union ({status:"ok",...} or {status:"error", reason}).