Skip to main content

Domain Verification

Domain verification is the foundational security mechanism of RedactedWorld. No scanning activity can occur until a user proves they own or control the target domain. This is enforced at every level -- from the API Gateway to the scan-service.

Verification Flow​

The verification process uses DNS TXT records, similar to how Google Search Console and AWS SES verify domain ownership.

Step-by-Step Process​

  1. Register Domain -- The user submits a domain name through the UI. The domain-service generates a unique verification token (e.g., rw-verify=a8f3b2c1d4e5).

  2. Add DNS TXT Record -- The user is instructed to create a TXT record at _redactedworld.<domain> with the token value. For example:

    _redactedworld.example.com.  IN  TXT  "rw-verify=a8f3b2c1d4e5"

  3. Trigger Verification -- The user clicks "Verify Now" in the UI. The domain-service performs a DNS TXT lookup against public resolvers.

  4. Token Comparison -- If the TXT record value matches the stored token, the domain is marked as verified. A SpiceDB relationship is written linking the domain to the organization.

  5. Scanning Unlocked -- With the domain verified, members of the owning organization can now launch scans against it.

Security Rules​

Authorized Domains Only​

Scans can only target domains that have been verified through the DNS TXT process. The scan-service checks SpiceDB.CheckPermission(user, scan, domain) before creating any Kubernetes Job.

No Direct IP Scanning​

The platform does not accept raw IP addresses as scan targets. All targets must be domain names that resolve through DNS. This prevents the platform from being used to scan arbitrary infrastructure.

Subdomain Inheritance​

When a root domain (e.g., example.com) is verified, its subdomains (e.g., www.example.com, api.example.com) are automatically authorized for scanning. The domain-service maintains a subdomain registry using DNS enumeration results.

Weekly Re-Verification​

Verified domains are re-checked every 7 days. If the TXT record has been removed, the domain status reverts to unverified and all scheduled scans are paused. This ensures ongoing authorization and prevents scanning of domains that have changed ownership.

Edge Cases​

ScenarioBehavior
DNS propagation delayUser can retry verification. The domain stays in pending state for up to 72 hours before expiring.
Wildcard domainsNot supported. Each domain must be verified individually.
Domain transferIf DNS TXT record is removed during weekly re-verification, the domain reverts to unverified. The new owner must re-register and verify.
Multiple organizationsThe same domain can only be verified by one organization at a time. Attempting to register an already-verified domain returns an error.