Skip to main content
Infra search maps what a domain exposes to the internet. You give it acme.com. It collects the hosts under that domain from DNS records, certificate logs and internet-wide scan data, resolves each one to an IPv4 address, and attaches the open ports, known CVEs and network owner of that address. The scan is passive. It reads public datasets and live DNS, and never connects to services on your hosts. In the dashboard the same scan is Exposure → Attack Surface Discovery, and scans started in either place share one history and one allowance. The flow is asynchronous: start a scan, poll it until it ends, then read the hosts and the summary.

​
How it differs from other searches

Infra search is not quick search. Pick by what you need back.

​
Availability and cost

Availability: Attack Surface Mapping, included in every edition. Cost: 1 unit of your monthly Attack Surface Mapping allowance for each scan you start. The unit is taken before the scan is created and refunded if create_infra_search_request returns an error. Polling, reading hosts, statistics and deletes use no scan units. A scan that ends failed keeps its unit, and so does a scan you delete. Without the feature, or when your license is not active, the four scan endpoints (create_, list_, get_ and delete_infra_search_request) return 403:
The host and statistics endpoints have no plan or license check and keep serving existing results. When the month’s allowance is spent, create_infra_search_request returns 429 and no scan is created:
limit is your monthly scan allowance. A 429 whose body reads "message": "Rate limit exceeded" is the request rate limit, not the scan allowance. Retry after retry_after_seconds.

​
What a scan collects

The scan runs four sources in this order. Each host name and IP pair it keeps becomes one result, and the result’s type names the source that found it. Four rules decide what comes back:
  • Only the domain and its subdomains. acme.com and vpn.acme.com are kept. acme-login.com is not.
  • IPv4 only. Certificate names are resolved to their first A record. A name that does not resolve is dropped.
  • Each source adds new addresses. A source skips any IP an earlier source already reported.
  • Enrichment comes from datasets, not probes. Every IP is looked up in Shodan’s InternetDB for open ports and CVEs. CrtSH, KaduuLeakCenter and ZoomEye hosts also get reverse DNS and network registration (ASN, provider, country). DNSDumpster hosts carry DNSDumpster’s own network data.

​
Run a scan

1

Start the scan

create_infra_search_request takes one field, search_term: required, 1 to 255 characters.
Send the bare root domain. Use acme.com, not https://www.acme.com. Every source keeps only the term itself and the names under it, so a URL, a keyword or an IP address returns no hosts. The API does not check the term: any of these is accepted, uses a unit and finds nothing.
The call returns 201 with the scan:
Keep the id. A scan you start here runs once. is_monitoring, alert_cycle and is_email are monitoring settings this endpoint does not set. is_reporting and report_id are filled only on scans that a report started.
2

Poll until it ends

Fetch the scan with get_infra_search_request, passing its id in the path, until status is no longer in_progress.
status takes three values:
  • in_progress — still running.
  • finished — done. Read the hosts.
  • failed — done, with an error. This is final: the platform does not retry it. It can still hold the hosts found before the failure. Start a new scan to try again, which uses another unit.
Poll every 10 seconds or slower. Each source saves its hosts as soon as it finishes, so the host list grows while the scan is in_progress.
Every scan ends. A scan stops itself 50 minutes after it starts, keeps the hosts found so far, and ends finished. The response does not mark a scan that hit this cap. A scan that stalls is set to failed 65 to 75 minutes after it starts. A scan that never starts is set to failed within 10 minutes of turning 24 hours old.
3

Read the hosts

list_infra_search_result returns the hosts of one scan. Pass the scan id as searchrequest.
  • searchrequest is required and must be a UUID. Without it the call returns 400.
  • page is 1-based. page_size defaults to 100, max 1000.
  • There is no other filter, no sort parameter and no guaranteed order. Page through the list after status leaves in_progress: paging a running scan can skip or repeat hosts.
  • Page by raising page until next is null. The next and previous URLs point at the internal scanning service, not at client-api.leak.center, so don’t call them.

​
What each host gives you

  • domain — the host name found.
  • ipv4 — the IPv4 address it resolves to. Can be empty.
  • type — the source that found it. See What a scan collects.
  • shodan_data — the Shodan InternetDB record for the IP: open ports, known vulns as CVE IDs, cpes, hostnames and tags. These are what Shodan last observed, not a live check. It is {} when Shodan has no record for the IP or the lookup failed.
  • metadata — network details for the IP: reverse_dns, as (the AS number and range on DNSDumpster hosts, the AS description on other hosts), provider (the network owner) and country. metadata.type is the DNS record kind on DNSDumpster hosts: dns for an A record, mx for a mail server, host for a name server. On other hosts it is dns when the network lookup ran and empty when it was skipped, for example for a private IP. header is always empty.
  • date_created — the day the host was saved.
  • id — the result ID, for the single-host and delete calls.
  • searchrequest — the scan the host belongs to.
To fetch one host again, call get_infra_search_result with its result id, not the scan id.

​
Summary statistics

get_infra_search_stats returns three counts for one scan. Pass the scan id as searchrequest.
  • servers_with_unusual_ports — hosts with at least one open port other than 25, 53, 80, 443, 465 and 587.
  • servers_with_reported_vulns — hosts whose shodan_data lists at least one CVE.
  • servers_with_unusual_names — hosts whose name contains a fragment that hints at admin, dev or test, database, internal, repository, monitoring or other sensitive use, such as admin, staging, db, vpn, intranet, repo or zabbix.
Counts are per result row, so one IP behind three host names counts three times and a host name with two IPs counts twice. Name matching is a case-insensitive substring match on the whole host name, your domain included. Short fragments such as ci, db, server and static also match inside longer words. If your domain itself contains a fragment, for example ci inside financial, every host counts. A scan with no hosts returns 404 with {"message": "No search results found for the given search request ID"}, whether it is still running or finished with nothing found. Read it as all three counts being zero.

​
List past scans

list_infra_search_request returns your organization’s scans, newest first, including the ones started from Attack Surface Discovery in the dashboard.
  • page is 1-based. page_size defaults to 20, max 100.
  • ordering takes create_date, -create_date, update_date or -update_date. The default is -create_date.
  • Page the same way as the host list: raise page until next is null.
A scan with is_reporting: true was started by a report and did not use your Attack Surface Mapping allowance.

​
Clean up

Both deletes are permanent and return 204. Delete a scan only after it leaves in_progress. A scan deleted while running keeps running and is saved again when it ends, so it reappears in the scan list as failed or finished with no hosts.

​
Errors

​
Endpoints