API Documentation

Iris Investigate

Overview

The Iris Investigate API is ideally suited for investigate and orchestrate use cases at human scale.

These are typically triggered on-demand by an analyst seeking additional context on a single indicator, with the best results available for investigations that begin with one or more domain names.

Key characteristics of the Iris Investigate API include:

Dozens of domain name attributes on every result, including:
- Domain risk scores from proximity and threat profile algorithms
- Whois, IP, active DNS, website & SSL data
- Counts of connected domains on most attributes
Unified API endpoint for both domain profiles & pivot searches
- Support for batch processing and pagination
- Search by identity, IP, name server, mail server, SSL certificate, & more
Offered with interactive Iris web app

Get Started with the Iris Investigate API

API Endpoint:

https://api.domaintools.com/v1/iris-investigate/

API Authentication:

The Iris Investigate API uses the same authentication mechanism as all DomainTools APIs, with one important distinction: query limits are derived from, and shared with, queries allocated to the Iris Investigate UI.

That means the API username must be connected with a DomainTools Enterprise account which is authorized to access Iris Investigate. Normally, this happens during account setup by the DomainTools Enterprise Support team. Be sure to use the correct API username and API key that was issued to your organization by your DomainTools point-of-contact.

Care must be taken during development and testing to ensure interactive queries are not inadvertently exhausted due to scripting errors. Consider starting with the no-charge sample queries during the testing phase of your project.

No-Charge Sample Queries:
These queries are available for testing the API and will not count against query limits:

https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com

https://api.domaintools.com/v1/iris-investigate/?ip=199.30.228.112

Domain Name Profiles with the Iris Investigate API

The Iris Investigate API enables the domain profile use case with a single parameter (in addition to the authentication tokens). Simply pass a domain name in the domain parameter to retrieve all the information available in Iris on that domain.

For example:

https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com

You can also pass in a comma-separated list of up to 100 domain names in a single batch. The API considers a batch request as a single query for accounting and rate limiting purposes, so batches are encouraged anytime you have more than a single domain name to profile.

For example:

https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com,domaintools.net,dailychanges.com

For best results, especially with long lists of domain names, consider using the HTTP POST method instead of GET parameters.

The Iris Investigate API will return a record for each domain name found in the Iris dataset. If you submitted a list of domains in a batch, be sure to compare the list of domains returned in the API response to your own list so you can detect when a domain name you requested was not found in the Iris dataset. Use the “domain” attribute in the Iris record to make the match.

Guided Pivots with the Iris Investigate API

One of the most powerful features in the interactive Iris Investigate product are the Guided Pivots that help users quickly identify which attributes of a domain name are connected with a relatively small number of other domain names. The smaller the count, the more likely the domains are to be related.

The Iris Investigate API delivers these counts for nearly every attribute in a domain response, on every domain record, even when processing a batch of domain names.

These counts are included in the API response as a property of the attribute, adjacent to the attribute value, to make it easier to leverage them in your integration. This also explains why the value of a field is one level deeper than you may expect. For example:

ip: 
  [
    {
      address: 
        { value: "199.30.228.112", count: 3 },
      asn: 
        [
          { value: 17318, count: 101 }
		],
      country_code: { value: "us", count: 239988363 },
      isp: { value: "Domaintools LLC", count: 108 }
    }
  ]

Here, we identify the IP address “199.30.228.112”, ASN “17318” and ISP “Domaintools LLC” as potential pivot points, or at the very least, as meaningful analytics to help profile the domain name. For example, IP addresses with very few other domains pointed to them often represent dedicated hosting controlled by the same entity.

In the Iris Investigate UI, we use a default threshold of 500 connections to decide which attributes to draw the user’s attention to. Consider starting with a similar threshold for your integration, but provide the user the option to choose a different threshold to match their use case.

Note that empty data elements will have a count of 0.

Search & Pivot with the Iris Investigate API

The Iris investigate API can also be used in a search mode. Instead of a domain name, you can provide one or more search fields to the API, such as IP address, SSL hash, email, or more, and Iris will return any domain name with a record that matches those parameters. This enables “reverse” searching on one or more fields with a single API endpoint.

For example:

https://api.domaintools.com/v1/iris-investigate/?ip=199.30.228.112

Queries across multiple parameters are interpreted as a logical AND query, meaning multiple parameters will narrow a search to a smaller result set. The Iris Investigate API does not currently support logical OR queries; instead, submit separate queries for each parameter and combine the result set in your own code.

Domain records returned in the result set are identical to records returned from a query for one or more domain names, which provides a rich resultset ready for display to end users and well-suited for further pivoting. For example, consider using the guided pivot counts to surface new ways to expand the result set. Or, you could sort on the risk score (highest to lowest) to show the results to the end user with riskiest domains listed first.

Supported parameters

Parameter	Functionality	Compare To
ip	IPv4 address the registered domain was last known to point to during an active DNS check	Reverse IP
email	Email address from the most recently available Whois record, DNS SOA record or SSL certificate	Reverse Whois
email_domain	Only the domain portion of a Whois or DNS SOA email address	Reverse Whois
nameserver_host	Fully-qualified host name of the name server (ns1.domaintools.net)	–
nameserver_domain	Registered domain portion of the name server (domaintools.net)	Reverse Nameserver
nameserver_ip	IP address of the name server	–
registrar	Exact match to the Whois registrar field	Reverse Whois
registrant	Substring search on the Whois registrant field	Reverse Whois
registrant_org	Substring search on the Whois registrant org field	Reverse Whois
mailserver_host	Fully-qualified host name of the mail server (mx.domaintools.net)	Reverse MX
tagged_with_any	Domains which have been tagged with ‘a specific’ Domain Tag/ ‘one-of-the’ Tags in the Iris Investigation platform	–
tagged_with_all	tagged_with_all	–
mailserver_domain	Only the registered domain portion of the mail server (domaintools.net)	–
mailserver_ip	IP address of the mail server	–
redirect_domain	Find domains observed to redirect to another domain name	–
ssl_hash	SSL certificate SHA-1 hash	–
ssl_org	Exact match to the organization name on the SSL certificate	–
ssl_subject	Subject field from the SSL certificate	–
ssl_email	Email address from the SSL certificate	–
google_analytics	Domains with a Google Analytics tracking code	–
adsense	Domains with a Google AdSense tracking code	–
search_hash	Encoded search from the Iris UI	–

Domain Tags as a Search Parameter

Iris Investigate API supports the ability to retrieve domains which have already been tagged within the Iris Investigate UI. Currently, all Tags created within your instance of the Iris Investigate UI are accessible via the API.

The below table summarizes the functionalities when using the search parameter:

Scenario	Sample Parameter	Expected Result
Retrieve Domains matching one of the specified Tags	?tagged_with_any=watch,monitor	All Domains which have been tagged as ‘watch’ OR ‘monitor’
Retrieve Domains matching a list of Tags	?tagged_with_all=block,dangerous,evil	All Domains which have been tagged with all 3 tags – ‘block’ and ‘dangerous’ and ‘evil’

Query Limits & Pagination

Certain queries in the Iris Investigate API have the potential to match a very large set of domains. Ideally, implementations will leverage the counts returned in Iris for a domain name query to programatically select reasonable pivots, but this is only practical when an investigation begins with a domain name. For cases where a search begins with one of the parameters listed above, it becomes essential to check the Iris results to see whether a search has exceeded limits or has been paginated.

For example, consider this query:

https://api.domaintools.com/v1/iris-investigate/?nameserver_domain=markmonitor.zone

The Iris Investigate API returns this response fragment:

response: {
	limit_exceeded: false,
	has_more_results: true,
	message: "There is more data for you to enjoy.",
	results_count: 500,
	total_count: 3735,
	position: "2c056abadfb64b67ba18896af2c5b900",
	results: [
		{ domain: "1000miglia.watch",
		...

The “limit_exceeded” value of “false” tells us our search is within the capabilities of Iris and our contracted service level, so it is possible for us to retrieve a complete result set from Iris.

The “has_more_results” value of “true” indicates our response does not include all of the domain names that matched our search. We can see precisely how many are included in the “results_count” field, and how many are available in the “total_count” field.

To retrieve the complete result set, submit the query again with the same query parameters but with the addition of the “position” parameter set to the position value in the response.

For example:

https://api.domaintools.com/v1/iris-investigate/?nameserver_domain=markmonitor.zone&position=2c056abadfb64b67ba18896af2c5b900

Repeat this pattern with the new position value in each result set until the has_more_results value in a response is set to “false”.

Iris Search Filters

It can be useful, even essential in some cases, to limit an Iris result set by additional filters. These parameters can be added to any search in the Iris Investigate API, although they cannot be used on their own.

active	Set to “true” to only return domains that have either an entry in the global DNS system, OR are listed as registered by the registry. Set to “false” to only return domains that do not have an entry in the global DNS system AND are not listed as registered by the registry. Exclude the filter entirely to find domains in any of these states.
tld	Limit results to only include domains in a specific top-level domain (i.e. “tld=com” or “tld=ru”)
create_date	Only include domains created on a specific date, in YYYY-MM-DD format
first_seen_since	Matches domains with a first seen on or after an ISO8601-compliant date/time (including a timezone)
first_seen_within	Matches domains with a first seen within a specific number of seconds from when the request is made
server_type	The web server identified when gathering content.
website_title	The value of the website’s title tag.
expiration_date	Only include domains expiring on a specific date, in YYYY-MM-DD format
tagged_with_any	Only include domains which are tagged with ‘a specific’ tag/ ‘one-of-the’ tags in the Iris Investigation platform
tagged_with_all	Only include domains which are tagged with all the tags specified in the filter criteria
not_tagged_with_any	Exclude all domains which are tagged with ‘a specific’ tag/ ‘one-of-the’ tags in the Iris Investigation platform
not_tagged_with_all	Exclude all domains which are tagged with ‘a list of tags’ in the Iris Investigation platform

Domain ‘Tags’ as a Filter Parameter

Iris Investigate API supports the ability to further limit result sets by filtering domains, which have already been tagged as part of an investigation within the Iris Investigate UI. Currently, all tags created within your instance of the Iris Investigate UI are accessible via the API.

The table below summarizes the functionalities when using the search parameter:

Scenario	Sample Parameter	Expected Result
Filter result sets by only displaying Domains matching one of the specified ‘Tags’	?nameserver_domain=markmonitor.zone&tagged_with_any=watch,monitor	Only list Domains which are tagged as ‘watch’ OR ‘monitor’
Filter result sets by only displaying Domains matching a List of ‘Tags’	?nameserver_domain=markmonitor.zone&tagged_with_all=block,dangerous,evil	Only list Domains which are tagged with all 3 tags – ‘watch’ and ‘dangerous’ and ‘evil’
Filter result sets by excluding domains matching one of the specified ‘Tags’	?nameserver_domain=markmonitor.zone¬_tagged_with_any=watch,monitor	Only list Domains which are not tagged with ‘watch’ or ‘monitor’
Filter result sets by excluding domains	?nameserver_domain=markmonitor.zone¬_tagged_with_all=zerolisted,safe,trusted	Only list Domains which are not tagged as ‘zerolisted’ and ‘safe’ and ‘trusted’
matching a List of ‘Tags’	–	–

Monitoring newly active domains with the Iris Investigate API

The Iris Investigate API can be used as a powerful monitoring tool to detect newly active domains pointed to certain IPs, hosted on target name servers, redirecting to specific sites, and any other criteria that can be framed in an Iris API query.

This can be accomplished by adding either first_seen_since or first_seen_within to the API query (see details above for those parameters). The first seen is the date/time (in UTC) that DomainTools discovers a domain as newly active. A potential implementation may follow a pattern similar to this:

Craft a search query in Iris that defines the attributes you want to monitor.
Submit the query to Iris to obtain a baseline. Store the data in your own system.
Periodically re-submit the same query, but with the addition of the appropriate first_seen parameter based on when you last queried.

Then:

Compare to the stored baseline to find domains added or removed
Iterate through domains that were already present in the baseline snapshot but were since updated in some way. Compare to their base records and note the differences.
Store the additions, deletions, or updates as a new baseline, possibly preserving the previous values for historical tracking

This capability makes the Iris Investigate API a compelling replacement for DomainTools Enterprise API monitors that currently only return a single domain in their result: Name Server Monitor and IP Monitor. It also extends monitoring well beyond those endpoints to include monitoring on SSL attributes, tracking codes, registrar and more, with the additional option to narrow to specific TLDs with the tld= filter.

Integrating the Iris Investigate UI and the Iris Investigate API

The Iris Investigate Platform offers a rich UI to search and pivot through domain name data. Nearly all the data in the Iris Investigate “Pivot Engine” pane is accessible in the Iris Investigate API, and the most common research patterns can be easily accomplished with that API.

However, even with these capabilities in the API, there remains a number of scenarios where users can only meet their goals with the complete set of tools and resources offered in the Iris Investigate UI. These scenarios include:

“OR” searches, or nested “AND” and “OR” searches across multiple fields and values.
Ad-hoc investigations into a single domain’s hosting, whois, or screenshot history
Graph visualization and graph-initiated pivoting
Passive DNS queries on IPs and hostnames

That means users may start their investigation in the Iris Investigate UI, but then expect to bring the results of their investigation into a third-party product. The search_hash parameter in the API makes this possible. Here’s how it works.

First, a user conducts an investigation in the Iris Investigate UI, potentially building a complex query to find all the connected infrastructure for a given domain name or threat actor. They access the Advanced Search in Iris Investigate and export the encoded representation of their search.

Next, the user provides this encoded string to your solution, and you craft an Iris Investigate API search with that string in the search_hash parameter. No other search parameters are required or supported (except the essential authorization parameters that should always be present). The Iris API “unpacks” the encoded search, runs the same query again, and returns the most up-to-date complete result set.