Skip to content

DomainTools App for Microsoft Sentinel

Overview

Microsoft Sentinel is Microsoft’s Security Information and Event Management (SIEM) product. It includes integrated playbooks to help you develop your Security Orchestration, Automation and Response (SOAR) applications.

DomainTools offers 3 Logic Apps for Microsoft Sentinel that are designed to work independently or together:

  • Iris Investigate: Quickly and efficiently investigate indicators of interest using Iris Investigate, providing whois, DNS, SSL and related infrastructure. Pivots add connected infrastructure to an incident.
  • Iris Enrich: High-volume enrichment, up to 6,000 domains/minute with optional batching. This allows you to add immediate Internet-wide risk context to threat indicators.
  • Farsight DNSDB: Enables lookups of DNS infrastructure against Domain and IP indicators. The integration includes several actions and 4 reference playbooks to allow Sentinel users to leverage Farsight pDNS data in their investigations.

Installation

Requirements

Requirements for DomainTools Iris Investigate

  • A Microsoft Power Apps or Power Automate plan with custom connector feature
  • An Azure subscription
  • A DomainTools API Key Provisioned for Iris Investigate
  • A DomainTools API Key Provisioned for Iris Enrich (optional, for enrichment actions or playbook)
  • A Farsight DNSDB API Key (optional, for Farsight co-enrichment playbook)

Requirements for Farsight DNSDB

  • A Microsoft Power Apps or Power Automate plan with custom connector feature
  • An Azure subscription
  • A Farsight DNSDB API Key

Installing Iris Investigate

Install following the guided steps provided by Microsoft. No special configuration is needed for DomainTools apps at this stage.

Playbook Installation

Reference playbooks are available. The most straightforward one to begin with is the “Domain Risk Score” playbook. For each playbook, navigate to Automation → Playbook templates, search for DomainTools, select create playbook, and follow the installation steps.

Note: you can ignore the UserName field at this point. We will configure it later.

Note: If installing the URL playbook, you must instal the Azure Functions app to parse URLs to domains. Navigate to Sentinel → Automation, select the URL Enrichment Playbook, and select the link in the description to deploy the Azure function app to azure.

After installing the URL Enrichment function app, Sentinel also needs to be informed that it’s a Python 3.8 function and restart the app. Navigate to function app → configuration → general settings, and select Python 3.8. Save the changes, and select overview → restart.

API Connection

After installation, each Logic App needs to be configured with a DomainTools API key. The general instructions are as follows.

  1. Open each playbook in Logic App designer. Please note that due to the size of the app, the Domain Enrichment - DomainTools Iris Investigate logic app loading time can reach several minutes.
  2. On first use, select Change Connection then Add new. This is where you will put in their DT API username and key, dashes included.
  3. Select Create then Save
  4. On subsequent Logic App connections, simply select the existing connection.
  5. For the DomainTools_Iris_Investigate-With_Farsight_pDNS_Playbook an additional step to add the Farsight DNSDB key is needed.
  6. Expand the check if results exist section, then scroll to RData lookup with RRType, expanding that.
  7. Select Create connection and enter the Farsight DNSDB credentials.
  8. Select Create then Save the Logic App.

Permissions

Each Logic App then needs permission to add comments to incidents.

  1. From the Sentinel environment, go to Settings -> Workspace Settings → IAM → Add role assignment → Microsoft Sentinel Responder. If it reports disabled, an administrator may need to assist, or elevate your permissions to allow managing role assignments as outlined in the Azure technical documentation.
  2. On the next screen, assign access to Managed identity → Select Members → Logic App and select each playbook you just added. Select Review + assign.
  3. Select Microsoft Sentinel Responder under the role assignment.
  4. Select Managed identity, filter for the Logic Apps, and select each of the playbooks you just added.
  5. In case of any existing apps with permissions, a failure notice for the duplicate may appear that can be ignored.
  6. The app is now configured. Repeat for any remaining playbooks you wish to install, or install the DNSDB app.

Installing Farsight DNSDB

  1. Go to the Marketplace link, and select Get It Now. It is also available from the Content Hub within Sentinel.

  2. Follow the guided steps during installation. For each playbook, the installation process for DNSDB is nearly identical to the DomainTools installation. Paste your DNSDB API key in each playbook as outlined in the section above, remembering to provide Microsoft Sentinel Responder permissions to the Logic App. Any usage is counted against your daily or block quota.

Iris Investigate & Enrich Playbooks

These playbooks are available in the Azure repository on GitHub.

Playbook Description
DomainTools Iris Investigate Domain Playbook Given a domain or set of domains associated with an incident, return whois, mail server, DNS, SSL and related indicators from Iris Investigate, highlighting fields where fewer than 500 (configurable) domains share an attribute.
DomainTools Iris Investigate Domain Risk Score Playbook Given a domain or set of domains associated with an incident, return the risk scores and adjust the severity of the incident if a high risk domain is observed. Add the risk scoring details in the comments of the incident.
DomainTools Iris Investigate Guided Pivots Playbook Given a domain, return whois, mail server, DNS, SSL and related indicators from Iris Investigate, highlighting, and automatically querying for related domains sharing an attribute with the one in the incident.
DomainTools Iris Investigate Malicious Tags Playbook Track the activities of malicious actors using the Iris Investigate UI, tagging domains of interest. Given a domain or set of domains associated with an incident, query Iris Investigate for information on those domains, and if a specified set of tags is observed, mark the incident as “severe” in Sentinel and add a comment.
DomainTools Iris Investigate URL Playbook Given a URL or set of URLs associated with an incident, return all DomainTools Iris Investigate data for the extracted domains from the URL as comments in the incident.
DomainTools Iris Investigate With Farsight pDNS Playbook Given a domain or set of domains associated with an incident, enrich the domain using the DomainTools Iris Investigate API, returning whois and infrastructure details. Subsequently retrieve associated subdomains from passive DNS information seen in Farsight’s DNSDB. Farsight DNSDB API subscription is required.
DomainTools Iris Enrich Domain Playbook Given a domain or set of domains associated with an incident, return whois, mail server, DNS, SSL and related indicators from Iris Enrich. Iris Enrich supports up to 60 calls per minute (compared to 20 on Iris Investigate) and requires separate account provisioning.

Available Actions for Iris Investigate

Action Description
Investigate Domain Retrieves the infrastructure and whois data associated with a domain or comma-separated list of up to 100 domains. The Iris Investigate endpoint supports up to 20 requests per minute.
Pivot by MX IP Returns up to 500 domains served by a given mail server IP. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Pivot by Nameserver IP Address Returns up to 500 domains served by a provided nameserver IP. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Pivot by Registrant Name Returns up to 500 domains exactly matching the provided whois registrant field. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Pivot by Registrant Organization Returns up to 500 domains exactly matching the provided whois registrant organization field. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Pivot by SSL Hash Returns up to 500 domains with an SSL certificate matching a provided SHA-1 hash. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Pivot MX Host Returns up to 500 domains with a mail server on a provided domain name. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Pivot Nameserver Host Returns up to 500 domains served by a provided nameserver host. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Pivot SSL Email Returns up to 500 domains with a given email address on the SSL certificate. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Retrieve Account Information Information on the active API endpoints, rate limits and usage for an account.
Return Domains from Search Hash Import up to 500 domains from Iris Investigate into the Sentinel platform. From an active search, open Advanced→Import/Export Search and copy the hash. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Return Tagged With All Retrieves up to 500 domains tagged within the Iris Investigate UI. Given a comma-separated list of tags, returns domains that are tagged with ALL of the tags. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Return Tagged With Any Retrieve up to 500 domains tagged within the Iris Investigate UI. Given a comma-separated list of tags, returns domains that are tagged with ANY of the tags. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Reverse Email Returns up to 500 domains with an email address on the most recently available whois record, DNS SOA record or SSL certificate. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Reverse Email Domain Returns up to 500 domains with the domain portion of an email address on the most recently available whois or DNS SOA record. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.
Reverse IP Returns up to 500 domains that last resolved to a given IPv4 address on an active DNS check. Use the optional 'active' and 'date updated after' parameters to pre-filter the result set.

Available Actions for Iris Enrich

Action Description
Enrich Domain Retrieves the infrastructure and whois data associated with a domain or comma-separated list of up to 100 domains. The Iris Enrich endpoint supports up to 60 requests per minute.
Retrieve Account Information Information of the active API endpoints, rate limits and usage for an account.

Farsight DNSDB Playbooks

Playbook Description
DNSDB_Historical_Hosts This playbook uses the Farsight DNSDB connector to automatically enrich IP addresses found in the Sentinel incidents. This use case describes the desire to identify all hosts that resolved to a given address based on a time window from a starting and stopping point in time.
DNSDB_Historical_Address This playbook uses the Farsight DNSDB connector to automatically enrich domains found in the Sentinel incidents. This use case describes the desire to identify all addresses used as DNS A records for a given host based on a time window from a starting and stopping point in time.
DNSDB_Co_Located_IP_Address This playbook uses the Farsight DNSDB connector to automatically enrich IP addresses found in the Sentinel incidents. This lookup will identify all the IPs that are co-located (based on Domain) based on the input of an IP Address. This would be a set of IPs that also shared the same Domain as the originating IP address.
DNSDB_Co_Located_Hosts This playbook uses the Farsight DNSDB connector to automatically enrich Domains found in the Sentinel incidents. This use case describes the desire to easily identify Hosts that are co-located (based on Address) based on the input of a host and a given point in time. The response would be a set of domains that also shared the same IP address as the originating domain name at the given point in time.

Available Actions for DNSDB

Actions Description
Flexible Search Flexible Search adds both Regular Expressions and Globbing support to the DNSDB API to expand the types of search queries and add more control to searches.
Ping This request is for end to end connectivity tests to the DNSDB API endpoint, letting you know that there are no firewall blockages. This request does not require an API key. It returns just a JSON object {'ping': 'ok'}.
RData Lookup The RData lookup queries DNSDB's RData index, which supports inverse lookups based on RData record values.
RData Lookup with RRType The RData lookup queries DNSDB's RData index, which supports inverse lookups based on RData record values.
RRSet Lookup The RRSet lookup queries DNSDB's RRset index, which supports forward lookups based on the owner name of an RRset.
RRSet Lookup with RRType The RRSet lookup queries DNSDB's RRset index, which supports forward lookups based on the owner name of an RRset.
RRSet Lookup with RRType and Bailiwick The RRSet lookup queries DNSDB's RRset index, which supports forward lookups based on the owner name of an RRset.
Service Limits Retrieve service limits

Using the DomainTools Apps with Microsoft Sentinel

Once the playbooks are installed, in Sentinel, you can trigger them using the Automated Response section of Analytic rules. Verify that the incident contains items mapped as a host to get started. To modify the host-based playbooks to run on DNS Domain Names, see the Using the Domain Playbooks with DNS Domain Names section later in this guide.

The URL Enrichment playbook can also take entities with URL types. Farsight DNSDB also supports the enrichment of IP-based indicators.

After an incident is created (or as a shortcut for testing, you may right-click an existing incident with the appropriate entity type and re-run the automation). If run successfully, the output then appears as a comment on the ticket.

Using the Domain Playbooks with DNS Domain Names

Referencing https://learn.microsoft.com/en-us/azure/sentinel/entities-reference, the provided domain playbooks expect input type host.

They can be modified to use a DNS Domain name type. Starting with the logic app open in code view:

  1. Find and replace _Get_Hosts with _Get_DNS (3 occurrences)
  2. Find and replace /entities/host with /entities/dnsresolution (1 occurrence, under Entities_-_Get_DNS)
  3. Find and replace @body('Entities_-_Get_DNS')?['Hosts'] with @body('Entities_-_Get_DNS')?['Dnsresolutions'] (1 occurrence)
  4. This step varies per playbook:
  5. For DomainTools_Iris_Investigate-Domain_Risk_Score_Playbook and DomainTools_Iris_Investigate-Malicious_Tags_Playbook:
    1. Find and replace @variables('host_name') with @items('For_each')?['DomainName'] (1 occurrence)
    2. Find and replace @{variables('host_name')}.@{variables('dns_name')} with @items('For_each')?['DomainName'] (1 occurrence)
  6. For DomainTools_Iris_Investigate-Domain_Playbook, DomainTools_Iris_Investigate-With_Farsight_pDNS_Playbook and DomainTools_Iris_Enrich-Domain_Playbook:
    1. Find and replace @variables('host_name') with @items('For_each_Host')?['DomainName'] (1 occurrence)
    2. Find and replace @{variables('host_name')}.@{variables('dns_name')} with @items('For_each_Host')?['DomainName'] (1 occurrence)
  7. For DomainTools_Iris_Investigate-Guided_Pivots_Playbook:
    1. Find and replace @variables('host_name') with @items('For_each_Host_')?['DomainName'] (1 occurrence)
    2. Find and replace @{variables('host_name')}.@{variables('dns_name')} with @items('For_each_Host_')?['DomainName'] (1 occurrence)

Troubleshooting

Issue Resolution
Logic App fails with a “Forbidden” error Permissions issue with the Logic App and/or Function App. Provision each playbook and the function app if installed with subscription “Microsoft Sentinel Responder” access. See the permissions section above.
The Iris Investigate URL playbook doesn’t run Make sure the additional Azure Function App is installed. This is needed to run the python code needed to parse a URL to a domain: See the additional “If installing the URL playbook…” section above. Make sure to also give the function app “Microsoft Sentinel Responder” permissions (see the permissions section above).
Nothing is getting enriched. Open the Logic App view. In the overview pane, the status should show succeeded or running. Select the most recent run for details to help diagnosis. If the run is successful, but nothing got enriched, check to make sure the entity is mapped correctly: the playbooks expect host,URL (in the case of the URL playbook), or can be modified, as shown above, to use DNS domain name. Farsight DNSDB playbooks also support IP.

Additional Resources