iDig API — Concepts & Implementation

DNS Resolution & the Core Lookup

The Concept

The Domain Name System (DNS) is the Internet's address book. When a user types example.com into a browser, a DNS resolver translates that human-readable name into an IP address (e.g. 93.184.216.34) that routers can use to deliver packets. DNS stores many types of records beyond simple addresses:

Additionally, a query may request reverse DNS (PTR record for an IP), WHOIS data (registrar metadata), and Quad-A (AAAA / IPv6) records.

How the API Implements It

The root endpoint performs the equivalent of the Unix dig command. Given a domain d and a record type rr (defaulting to a; can be all for every type), it:

1. Resolves the domain to its IP address, country, and reverse DNS name.
2. Fetches the requested resource record set(s).
3. Returns structured nameserver info (name, IP, country) and SOA details (primary NS, admin contact, serial, timing parameters).
4. Optionally includes DNSSEC key data (dnssec=yes), WHOIS summary (whois=yes), Quad-A records (quadA=yes), and reverse DNS (reverse=yes).

The response is the foundational data that all other endpoints build upon.

DNSSEC — Chain-of-Trust Validation

The Concept

DNSSEC (Domain Name System Security Extensions) adds cryptographic signatures to DNS records, allowing resolvers to verify that answers haven't been tampered with. It works as a chain of trust:

Root Zone (.)  →  TLD (.com)  →  Domain (example.com)
    DS → DNSKEY      DS → DNSKEY      DS → DNSKEY + RRSIG

Each zone signs its records with a Zone Signing Key (ZSK) and publishes a Key Signing Key (KSK) whose hash (the DS record) is placed in the parent zone. A validating resolver walks this chain from the root to verify every link.

Possible outcomes:

• Secure — Chain validates from root to domain; records are authentic.
• Insecure — Domain is unsigned (no DS at parent). Not an error, just no DNSSEC.
• Bogus — Domain is signed but the chain is broken — expired signatures, missing DS, algorithm mismatch. This causes resolution failures for validating resolvers.
• Indeterminate — Validation couldn't be completed (timeouts, upstream issues).

How the API Implements It

The endpoint runs the equivalent of delv (DNSSEC lookup and validation utility) against a local Unbound recursive resolver:

1. Queries the domain for the requested record type (default A).
2. Walks the full chain of trust from the root.
3. Returns status, validated (boolean), reason_codes, and remediation (fix suggestions).
4. Optionally includes the full output trace showing each fetch step in the chain (when trace=yes).
5. Reports warnings for non-fatal diagnostics that can usually be ignored when status is secure.

DNSSEC Key & Signature Health

The Concept

Even when DNSSEC validates today, operational issues can break it tomorrow:

• Signature expiry — RRSIGs have a finite lifetime (often 7–30 days). If a zone operator forgets to re-sign, resolvers will reject the zone.
• Algorithm weakness — Older algorithms (RSA-1024, DSA) are considered deprecated; modern best practice is ECDSAP256SHA256 or Ed25519.
• Key rollover — Rotating KSKs and ZSKs without breaking the chain requires careful coordination between the zone and the parent's DS records.
• DS mismatch — If the parent zone has a DS record that doesn't match any current DNSKEY, validation fails.

How the API Implements It

This endpoint builds a comprehensive operational report:

1. Key inventory — Lists all DNSKEYs with type (KSK/ZSK), algorithm, and key tag.
2. Signature analysis — Lists all RRSIGs with expiry date, days remaining, whether expired, and age in days. Identifies the earliest expiry.
3. Algorithm assessment — Rates each algorithm as recommended / good / legacy / deprecated with migration advice.
4. DS at parent — Fetches DS records from the parent zone and checks they match published DNSKEYs.
5. Rollover readiness — Counts KSKs and ZSKs, checks which KSK tags have DS records at the parent, and assesses rollover state.
6. Warnings & recommendations — Flags expired signatures, missing DS records, weak algorithms, and provides actionable remediation steps.

DNS Resolution Diagnostics

The Concept

When a domain "doesn't work," the cause could be many things: the domain doesn't exist (NXDOMAIN), the nameserver refuses queries (REFUSED), there's no data for the requested type (NODATA), or the nameserver itself is failing (SERVFAIL). A structured resolution check disambiguates these by testing multiple record types against the authoritative nameservers.

How the API Implements It

1. Discovers authoritative nameservers for the domain.
2. Queries for A, AAAA, SOA, and MX records.
3. For each record type, reports: rcode (NOERROR, NXDOMAIN, SERVFAIL, etc.), records found, TTL, and query time.
4. Classifies overall status: ok, nxdomain, nodata, servfail, refused, timeout, or degraded.
5. Returns human-readable errors explaining what's wrong.

Automated Diagnosis

The Concept

Most DNS problems fall into a small number of categories. An automated diagnostic engine can aggregate resolution and DNSSEC checks to answer three questions that cover the vast majority of support tickets:

1. Are there any errors with domain resolution?
2. Is this a DNSSEC-validated domain?
3. If DNSSEC is broken, how can I fix it?

How the API Implements It

1. Internally calls /resolve/check and /dnssec/validate.
2. Produces direct_answers — plain-language answers to the three key questions, each with an ok flag, a summary answer, and optional details or fixes.
3. Returns an overall summary, confidence level, and the full underlying resolution and DNSSEC data for drill-down.

DNS Propagation

The Concept

When a DNS record is changed (e.g. migrating a website to a new IP), the change doesn't take effect instantly worldwide. Each resolver caches records for the duration of their TTL. Different resolvers in different geographies may return different answers for a period — this is DNS propagation.

Operators need to know: "Has my DNS change reached all major resolvers yet?"

How the API Implements It

1. Queries 16 public DNS resolvers worldwide in parallel: Google (8.8.8.8), Cloudflare (1.1.1.1), Quad9 (9.9.9.9), OpenDNS, AdGuard, DNSPod (China), AliDNS (China), KT (South Korea), Yandex (Russia), Neustar, and more.
2. For each resolver, reports: name, IP, location, status (ok/error), records returned, TTL, and query time in milliseconds.
3. Compares all answers: summary.consistent is true only if every resolver returns the same answer set.
4. When inconsistent, summary.variants shows which resolvers returned which answers — making it easy to see which regions are still serving stale data.

Zone Consistency

The Concept

A domain's authoritative nameservers should all serve identical data. Inconsistencies arise from:

• Partial zone transfers — one NS updated but others haven't received the new zone yet.
• Lame delegation — a nameserver listed in the parent zone doesn't actually serve the domain.
• Configuration drift — manually managed NS servers with different zone files.

How the API Implements It

1. Discovers all authoritative nameservers for the domain.
2. Queries each nameserver individually for A, AAAA, MX, NS, SOA, and TXT records.
3. Compares answers across all nameservers for each record type.
4. Flags inconsistencies (different answers from different NS), lame delegation (NS doesn't respond), and single-NS setups (no redundancy).
5. Returns a per-type breakdown with per-NS results, plus overall consistent boolean.

TTL Advisory & Migration Readiness

The Concept

Time to Live (TTL) is how long (in seconds) a resolver may cache a DNS record before re-querying. High TTLs (e.g. 86400 = 24 hours) are efficient for stable records but disastrous during migrations: if you change your A record but resolvers have the old IP cached for 24 hours, users will hit the old server for up to a day.

Best practice before a migration:

1. Lower TTLs to 300s (5 min) at least 48 hours in advance.
2. Make the change.
3. Wait for propagation.
4. Restore normal TTLs.

How the API Implements It

1. Queries TTLs for A, AAAA, CNAME, MX, TXT, NS, and SOA records.
2. Classifies each as ok, elevated, or high.
3. Provides ttl_human (e.g. "24.0h") for readability.
4. Computes migration_ready — false if any TTL is dangerously high.
5. Returns step-by-step recommendations for pre-migration TTL lowering.

Email Authentication (SPF, DKIM, DMARC, BIMI)

The Concept

Email spoofing is trivially easy without authentication. Four complementary DNS-based mechanisms protect against it and build sender trust:

SPF (Sender Policy Framework) — A TXT record listing which IPs/servers are authorized to send mail for the domain. Receiving servers check the sending IP against this list. Key concerns:

• The all qualifier: -all (hard fail) vs ~all (soft fail) vs ?all (neutral).
• DNS lookup limit: SPF evaluation must not exceed 10 DNS lookups (includes include:, redirect, a, mx mechanisms).

DKIM (DomainKeys Identified Mail) — The sending server signs each message with a private key; the public key is published in DNS as a TXT record at <selector>._domainkey.<domain>. Receiving servers verify the signature. Key concerns:

• Key strength: RSA-1024 is weak; 2048-bit is recommended.
• Selector management: different providers use different selectors (Google: google, Microsoft: selector1/selector2, SendGrid: smtpapi).

DMARC (Domain-based Message Authentication, Reporting & Conformance) — A policy record that tells receiving servers what to do when SPF and DKIM fail: none (monitor), quarantine (spam folder), or reject (drop). Also specifies where to send aggregate reports (rua) and forensic reports (ruf).

BIMI (Brand Indicators for Message Identification) — A TXT record at default._bimi.<domain> that specifies a brand logo (SVG) and an optional Verified Mark Certificate (VMC). When DMARC enforcement is in place, email clients like Gmail can display the brand's logo next to messages — a visual trust signal for recipients. Key requirements:

• DMARC policy must be quarantine or reject (not none).
• Logo must be an HTTPS SVG in Tiny PS format.
• A VMC (from DigiCert or Entrust) is required for Gmail logo display.

How the API Implements It

1. SPF — Fetches the TXT record, validates syntax, checks the all qualifier, counts DNS lookups against the 10-lookup limit, and rates as pass/warn/fail.
2. DKIM — Probes common selectors plus any custom selectors passed via dkim_selectors. Provider inference: detects the MX provider (Google Workspace, Microsoft 365, SendGrid, Mailchimp, Postmark, Mailgun, Zoho, FastMail, Mimecast, SparkPost, Brevo, HubSpot, etc.) and automatically adds provider-specific selectors. Returns providers_detected and provider_selectors_added. For each found key, reports type, approximate bit size, status, and testing mode.
3. DMARC — Fetches _dmarc.<domain> TXT record, parses policy, subdomain policy, pct, alignment modes, and reporting addresses.
4. BIMI — Checks default._bimi.<domain> for a BIMI record, validates the logo URL (must be HTTPS SVG), and detects presence of a VMC. BIMI can provide a small bonus to borderline email security grades. Recommendations are only shown when SPF/DKIM/DMARC are already solid.
5. Overall grade — A–F letter grade with description, plus prioritized recommendations.

MX Record Health & Mail Provider Detection

The Concept

MX (Mail Exchange) records tell the world where to deliver email for a domain. Proper configuration requires:

• At least two MX hosts at different priorities for redundancy.
• Each MX hostname must resolve to A/AAAA addresses (not point to an IP directly, which violates RFC).
• MX hostnames should not be CNAMEs (RFC 2181, RFC 5321).
• Equal-priority records should be intentional (round-robin) not accidental.

How the API Implements It

1. Fetches MX records and sorts by priority.
2. Resolves each MX hostname to its A/AAAA addresses.
3. Provider detection — Matches MX hostnames against 35+ known mail providers (Google Workspace, Microsoft 365, Proofpoint, Mimecast, Zoho, Fastmail, etc.).
4. Validates RFC compliance: flags MX-to-IP, MX-to-CNAME, single-MX, and equal-priority issues.
5. Rates as pass/warn/fail with detailed issues and warnings.

IP Blacklist / DNSBL Check

The Concept

DNS-based Blackhole Lists (DNSBLs, also called RBLs — Real-time Blackhole Lists) are databases of IP addresses known to send spam or host malware. Email servers worldwide query these lists in real time: if the sending IP is listed, the message is rejected or flagged.

The lookup mechanism is elegant: to check if IP 1.2.3.4 is on blacklist bl.example.com, query 4.3.2.1.bl.example.com for an A record. If it resolves (typically to 127.0.0.x), the IP is listed; the specific x value and any accompanying TXT record indicate the reason.

Being blacklisted can silently destroy email deliverability. Operators often don't know until recipients stop receiving their mail.

How the API Implements It

1. Resolves the domain's A records and MX host IPs.
2. Queries 12 major DNSBL servers in parallel: Spamhaus ZEN (combines SBL, XBL, PBL), Barracuda, SpamCop, SORBS, CBL, UCEPROTECT, PSBL, SpamRATS, S5H.net.
3. For each listing, reports: the IP, which blacklist, the DNS zone queried, the response code, reason text (from TXT record), and a delist URL where the operator can request removal.
4. Summarizes clean_ips vs listed_ips.
5. Rates as pass (no listings) or fail (one or more listings).

Domain Registrar Status (EPP Codes)

The Concept

The Extensible Provisioning Protocol (EPP) is the standard protocol between domain registrars and registries. Each domain has a set of EPP status codes that control what operations are permitted:

Domains without transfer locks are vulnerable to unauthorized transfers (domain hijacking).

How the API Implements It

1. Performs a WHOIS lookup and extracts EPP status codes.
2. Decodes each code into plain-English description and category.
3. Checks for transfer, delete, and update locks.
4. Extracts registrar name and expiry date.
5. Rates as pass / good / warn / critical.
6. Returns security recommendations (e.g. "enable transfer lock").

Parsed WHOIS Data

The Concept

WHOIS is a protocol (RFC 3912) for querying databases that store information about registered domain names. The data includes:

• Registrar — which company manages the domain registration.
• Lifecycle dates — creation, last update, expiration.
• Nameservers — as recorded by the registrar (may differ from live DNS).
• EPP status codes — same codes as the Domain Status endpoint.
• Registrant — organization, country, contact details (often redacted for GDPR privacy).
• DNSSEC — whether DNSSEC is enabled according to the registrar.

WHOIS data is notoriously inconsistent in format across registrars and TLDs. Parsing it reliably requires handling hundreds of variations.

How the API Implements It

1. Performs a WHOIS query for the domain, following referrals to the authoritative WHOIS server.
2. Parses the raw text into structured fields: registrar, dates, nameservers, status codes, registrant info, DNSSEC status.
3. Computes domain_age_days and days_until_expiry.
4. Generates issues with warnings for: domains expiring within 30 or 90 days, already-expired domains, missing critical fields.
5. Handles privacy-redacted fields gracefully (returns them as-is or null).

SSL/TLS Certificate Inspection

The Concept

SSL/TLS (Secure Sockets Layer / Transport Layer Security) encrypts communication between browsers and servers. The server presents a certificate that:

• Identifies the server (subject, SANs — Subject Alternative Names).
• Is signed by a trusted Certificate Authority (issuer).
• Has a validity period (notBefore / notAfter).
• Must match the domain being accessed.

Certificate problems are one of the two most common causes of "site down" reports (the other being DNS). An expired certificate or a domain mismatch produces a browser warning that blocks access.

How the API Implements It

1. Connects to port 443 of the domain and performs a TLS handshake.
2. Extracts: subject, issuer (name + CN), SANs, validity dates, days remaining, serial number, version.
3. Checks domain_match — does the cert cover this specific domain (exact match or wildcard)?
4. Reports valid — trusted, not expired, and domain matches.
5. issues: expired cert, domain mismatch, verification failures, untrusted issuer.
6. warnings: upcoming expiry at 7 / 30 / 90 day thresholds.

HTTP/HTTPS Reachability

The Concept

Even when DNS resolves correctly and the SSL certificate is valid, the web server itself might not respond. Additionally, modern security best practices require:

• HTTPS availability — the site should be reachable over TLS.
• HTTP → HTTPS redirect — plain HTTP requests should redirect (301/302) to HTTPS.
• Security headers — Strict-Transport-Security (HSTS), X-Frame-Options, Content-Security-Policy (CSP) protect against downgrade attacks, clickjacking, and XSS.
• No redirect loops — a misconfigured server can create infinite redirect chains.

How the API Implements It

1. Tests HTTPS independently: connects to https://<domain>, records reachability, status code, response time, and response headers.
2. Tests HTTP independently: connects to http://<domain>, checks whether it redirects to HTTPS.
3. Follows the full redirect chain from https://<domain> (up to 10 hops) with loop detection, recording each hop's URL, status code, and response time.
4. Reports the final_url — where the chain ultimately lands.
5. Security header audit — checks for HSTS, X-Frame-Options, CSP in the response headers.
6. Rates as pass (HTTPS works and HTTP redirects to HTTPS), warn (partial), or fail (HTTPS down or no redirect).

IP Geolocation

The Concept

Every IP address is assigned to an organization and can be approximately mapped to a physical location. Geolocation databases correlate IP ranges with:

• Country, region, city, postal code.
• Latitude/longitude coordinates.
• ISP (Internet Service Provider) and organization.
• ASN (Autonomous System Number) — the BGP routing entity.
• Whether the IP belongs to a hosting/data-center provider.

This is useful for verifying where a domain's infrastructure is physically hosted.

How the API Implements It

1. Resolves the domain to all A and AAAA addresses.
2. Batch-geolocates all IPs using the ip-api.com API.
3. For each IP, returns: country (name + code), region, city, zip, lat/long, timezone, ISP, organization, AS number + name, and hosting flag.
4. Reports issues for any IPs that couldn't be geolocated.

Subdomain Discovery

The Concept

A domain's attack surface extends beyond the apex domain. Subdomains like admin.example.com, staging.example.com, db.example.com, or vpn.example.com often expose internal infrastructure, development environments, or forgotten services. Subdomain enumeration is a standard step in security audits and penetration testing.

How the API Implements It

1. Probes ~70 common subdomain names in parallel: www, mail, ftp, smtp, api, app, dev, staging, test, admin, portal, ns1–ns4, vpn, cdn, static, blog, shop, docs, git, db, grafana, auth, sso, status, autodiscover, _dmarc, and more.
2. Queries crt.sh Certificate Transparency logs to discover additional subdomains beyond the wordlist — any subdomain that has ever had a certificate issued will appear.
3. For each name that resolves, returns: subdomain name, FQDN, IP addresses, and CNAME (if aliased).
4. Summary: total checked, total found, list of discovered names.

DANE / TLSA Validation

The Concept

DANE (DNS-based Authentication of Named Entities) uses DNSSEC-signed TLSA records to pin TLS certificates to DNS, removing or reducing dependency on the public Certificate Authority system. A TLSA record at _443._tcp.example.com declares which certificate (or public key) the server should present.

TLSA records specify four parameters:

DANE validation requires both DNSSEC (to trust the TLSA records) and access to the live certificate (to compare). Neither /ssl/check nor a TLSA lookup alone can validate DANE — you need both sides.

How the API Implements It

1. Fetches TLSA records at _<port>._tcp.<domain> (default port 443).
2. Connects to the server and retrieves the DER-encoded certificate.
3. Computes SHA-256 and SHA-512 hashes of both the full certificate and the SubjectPublicKeyInfo.
4. Compares each TLSA record against the computed hashes.
5. Returns per-record match results with explanations.
6. Rates as pass (at least one TLSA record matches) or fail.

Supports all four TLSA usage types (PKIX-TA, PKIX-EE, DANE-TA, DANE-EE). A natural companion to /ssl/check and /dnssec/validate.

Zone Transfer (AXFR) Vulnerability Check

The Concept

AXFR (Authoritative Zone Transfer) is a DNS mechanism that allows a secondary nameserver to request a complete copy of a zone from the primary. When properly configured, AXFR is restricted to authorized secondary nameservers. When misconfigured, anyone can download the entire zone file — exposing every subdomain, mail server, internal hostname, TXT record, and service record.

An open zone transfer is a critical security misconfiguration. It gives attackers a complete map of the domain's DNS infrastructure, revealing:

• Internal hostnames and IP addresses.
• Development and staging subdomains.
• Mail server configurations and SPF/DKIM details.
• Service records (SRV) revealing protocols and ports.

How the API Implements It

1. Discovers all authoritative nameservers for the domain.
2. Attempts dig AXFR @ns domain against each nameserver.
3. Reports per-NS results: whether the transfer was allowed, record count, and sample records.
4. vulnerable: true if any NS allows public zone transfer.
5. Rates as pass (all refused) or critical (at least one allowed).
6. Returns detailed issues for each vulnerable nameserver.

A natural companion to /zone/consistency — run both for a complete zone audit.

Batch Multi-Domain Checks

The Concept

Organizations managing portfolios of domains (registrars, hosting providers, security teams) need to audit many domains at once. Running individual checks domain-by-domain is slow and inefficient. A batch API allows submitting a list of domains with a set of checks and retrieving all results asynchronously.

How the API Implements It

Submit a batch of domains for one or more checks. Returns a job_id immediately; checks run asynchronously in a background worker (up to 15 minutes).

Request body (JSON):

{"domains": ["example.com", "example.org"], "checks": ["dns", "ssl", "mx"]}

Available checks: dns, ssl, mx, email, geo, ttl, whois, blacklist, http, subdomains, dane, dnssec_validate, dnssec_health, zone_consistency, axfr, propagation, domain_status, resolve, diagnose.

Quota cost: 1 request per domain × check (deducted at submission). Free-tier tokens cannot use batch.

Poll for results. Returns:

1. status: queued, processing, complete, or failed.
2. completed / total: progress counter.
3. results: per-domain check results (populated as they complete).

Results are available for 24 hours after job creation.

How the Endpoints Work Together

The iDig API is designed as a composable diagnostic toolkit. While each endpoint stands alone, they combine to answer progressively deeper questions: