Skip to main content
Version: 0.18

Domain Checker

The Domain Checker discovers publicly known subdomains for a root domain using passive discovery: it queries public data sources (certificate transparency logs, DNS datasets) via the open-source subfinder tool, without ever probing your servers. You then review the results and bulk-import selected hostnames as SSL certificate tokens, optionally creating endpoint monitors at the same time.

It does not scan private DNS or internal network records. Only publicly known subdomains are discovered.

To track internal or private endpoints, add them individually via Endpoint & SSL monitoring. Self-hosted TokenTimer can reach hosts on your own network.

How it works​

  1. Open Endpoint & SSL monitor on the dashboard and switch to the Domain Checker.
  2. Enter a root domain (for example example.com) and run a lookup. TokenTimer queries subfinder's passive discovery sources and returns the publicly known subdomains it found. If only some discovery sources respond, the result is marked partial.
  3. Review the results and select the hostnames you want to track.
  4. Import the selection. Each hostname's live SSL certificate is fetched and imported as an ssl_cert token. Hostnames are skipped when they are duplicates, do not resolve in DNS, or fail validation; the import summary shows counts per skip reason.
  5. Optionally enable create monitors during the import to also create endpoint monitors for the imported hostnames, with a check interval, health checking, an "alert after failures" value, and a contact group.

Requirements​

The API runs subfinder on the API host. The official API container image bundles it. An API that runs directly on a host needs subfinder on PATH, or its full path in SUBFINDER_BIN. Without it, a lookup fails with 503 DOMAIN_CHECKER_TOOL_MISSING ("Domain discovery tools are not available in this deployment."). Passive discovery of a real domain can take a few minutes (one test run took about three). The lookup gives up after DOMAIN_CHECKER_OVERALL_TIMEOUT_MS (5 minutes by default). Output from one discovery tool is capped at 1 MB; a larger result is cut off and marked partial. See Configuration for the DOMAIN_CHECKER_* variables.

Discovery results​

Found websites are listed 50 per page with a name filter, and Select all picks every match up to the batch limit of 50. The list says "The list was cut at N websites, so some are not shown." when the result hit the maximum, and "Some sources did not answer, so there may be more." when only some sources replied. The setup wizard uses the same lookup. The one-lookup-per-minute rate limit below applies per workspace, and a refused lookup is worded "Too many searches. Try again in about Ns."

Rate limits​

Lookups are rate limited per workspace and per user to keep discovery sources healthy. By default one lookup is allowed per minute (DOMAIN_CHECKER_LOOKUP_RATE_LIMIT_MAX and DOMAIN_CHECKER_LOOKUP_RATE_LIMIT_WINDOW_MS); beyond that the API answers 429 DOMAIN_CHECKER_RATE_LIMITED with a Retry-After header. A second lookup for the same domain while one is running answers 409 DOMAIN_CHECKER_BUSY. If you hit a limit, wait and retry.

Audit trail​

Lookups and imports are recorded as DOMAIN_CHECKER_LOOKUP and DOMAIN_CHECKER_IMPORT audit events, including result counts and skip reasons. See Domain Checker events.