IBM Resilient: Iris SOAR app user guide

The DomainTools Resilient App brings DomainTools Iris intelligence and analytics into IBM Resilient so you can automate incident response. Automate playbooks end to end, or run ad-hoc actions on domain artifacts for inline context. The app uses the Iris Investigate API to enrich data inside IBM Resilient.

Key benefits

• Automate incident handling with Resilient rules and workflows that identify dangerous domain artifacts.
• Enrich domain artifacts on demand with DomainTools intelligence.
• Preserve DomainTools enrichment data in a data table within an incident, so you avoid context switching.
• Automate incident handling with DomainTools risk score analytics.
• Use DomainTools Iris tags to identify malicious domain artifacts.
• Discover unknown infrastructure by automating connected-infrastructure discovery with DomainTools pivot analytics.

Deployment guide

Prerequisites

• An active DomainTools Iris API key.
• IBM Resilient v33.0.5112 or later.
• Python 2.7.
• An integrations server running resilient-circuits v31.0.0 or later.
• The DomainTools Resilient App installed from the App Exchange.

Installation steps

1. Copy fn_domaintools-1.*.*.zip to the integrations server and SSH into it.

2. Unzip the package:

   unzip fn_domaintools-1.x.x.zip

3. Install the package:

   pip install fn_domaintools-1.x.x.tar.gz

4. Export to the server:

   resilient-circuits customize

5. Import the configurations into your app.config file:

   resilient-circuits config -u

6. Open the config file, scroll to the bottom, and add your DomainTools API keys:

   nano ~/.resilient/app.config

   Config	Required	Description
   dt_api_user_name	Yes	The DomainTools API username.
   dt_api_key	Yes	The DomainTools API key.

7. Save and close the app.config file.

8. Run resilient-circuits:

   resilient-circuits run

9. Log in to the Resilient appliance and go to Customization Settings → Layouts → Incident Tabs. To persist and view DomainTools enrichment data, store the result in a Resilient data table:

   1. Create a new incident tab named DomainTools.
   2. Drag DomainTools Result from the Data Tables column to the middle of the page.
   3. Click Save.

   

10. Verify the setup. The DomainTools App contains 5 functions, 4 workflows, 4 rules, and 1 data table. Log in to the Resilient appliance and confirm these exist:

    • Data table: the DomainTools results table.
    • Artifacts: a DNS Name artifact type. If it doesn’t exist, create one.
    • Message destination: the DomainTools message queue.
    • Functions, workflows, and scripts: the components listed below.

Customizing the DomainTools App

App config settings

[fn_domaintools]
dt_api_user_name=<API Username>
dt_api_key=<API Key>

Functions

The app ships five functions. The sections below describe each function’s inputs, outputs, and the pre- and post-process scripts that wire it into a workflow.

DomainTools: Profile Domain with Iris

Uses the Iris Investigate API, with a domain as the parameter, to retrieve domain intelligence data inside Resilient.

Inputs:

Input name	Type	Required	Description
dt_domain_name	String	Yes	Domain artifact of type DNS Name.

Outputs:

Output name	Type	Required	Description
dt_iris_data	JSON String	No	JSON string of the DomainTools Iris result set.

Pre-process script:

inputs.dt_domain_name = artifact.value

Post-process script:

incident.addNote('Performed DomainTools Iris profile of {0}'.format(results['domain']))
incident.properties.domaintoolsdata = True

DomainTools: Format Iris Investigate Data

Formats the results from an Iris Investigate API query for downstream processing, and writes the data into the DomainTools data table inside Resilient through the post-processing script.

Inputs:

Input name	Type	Required	Description
incident_id	Number	Yes	Resilient incident ID.
dt_format_options	LOV	Yes	One of: Analytics, Identity, Registration, Hosting.
dt_format_type	LOV	Yes	Defaults to JSON.
dt_iris_data_in	JSON String	Yes	JSON string containing the Iris result set.

Pre-process script:

inputs.incident_id = incident.id
inputs.dt_iris_data_in = workflow.properties.dt_iris_data['dt_iris_data']

Post-process script: the script adds a row to the domaintools_results data table and maps Iris result fields onto the row’s columns — domain name, retrieval date, age, the overall/proximity/threat-profile risk scores, website response code, IP country code, Alexa rank, the registrant/admin/technical/billing contacts and related email fields, registrar and status fields, create and expiration dates, hosting fields (IP addresses, mail servers, SPF record, name servers, SSL certificate, redirects), and the Google AdSense and Analytics tracking codes. It then adds a note:

incident.addNote('Added {0} to DomainTools Table'.format(results["Domain Name"]))

If no domain intelligence is available for the artifact, the alternative script runs instead:

incident.addNote('Domain Not Found')

DomainTools: Discover Actionable Pivots

Discovers the available pivots (discovery points) for a domain artifact, based on a configurable guided-pivot value.

Inputs:

Input name	Type	Required	Description
dt_iris_data_in	JSON String	No	JSON string of the DomainTools Iris result set.
dt_pivot_count	Number	Yes	Defaults to 300. Threshold for the DomainTools guided pivot, the analytic that discovers connected infrastructure.

Outputs:

Output name	Type	Required	Description
dt_pivot_data	Number	Yes	List of available pivots for the domain.

Pre-process script:

inputs.dt_iris_data_in = workflow.properties.dt_iris_data['dt_iris_data']

DomainTools: Execute Pivots

Takes the pivot data from the Discover Actionable Pivots function and performs a reverse lookup to identify associated domains, so you can discover connected infrastructure.

Inputs:

Input name	Type	Required	Description
dt_pivot_value	String	Yes	The JSON attribute holding the domain attribute field.
dt_pivot_type	LOV	Yes	One of: ip, email, email_domain, nameserver_host, nameserver_domain, nameserver_ip, registrar, registrant, registrant_org, mailserver_host, mailserver_domain, mailserver_ip, redirect_domain, ssl_dhash, ssl_subject, ssl_email, ssl_org, google_analytics, adsense.
dt_data_updated_after	Date	No	Filters the lookup by “updated after” date.
dt_created_date	Date	No	Filters the lookup by created date.

Post-process script:

incident.addNote('New Domains discovered from SSL Hash - Iris Pivot Function')
for k, domain in enumerate(results['pivots']):
    incident.addNote('DNS Name, {0}, pivot from Iris'.format(domain))

The templated workflow pivots on the SSL hash, IP address, and email fields as an example. You can extend it to pivot on any of the attributes listed under dt_pivot_type.

DomainTools App functionalities

The app delivers these functions and workflows as pre-packaged Resilient components. The steps below run the workflows once the app is configured. Customize the workflows to fit your organization’s incident response processes.

Domain enrichment for artifacts

Run ad-hoc enrichment of a domain artifact in an incident with core DomainTools Iris data — WHOIS, analytics such as risk score and threat profiles, and associated artifacts such as SSL and ASN information.

Workflow name: DomainTools: Profile Domain with Iris

To run the workflow:

1. In IBM Resilient, select an incident to investigate.
2. Select the Artifacts tab to view the incident’s artifacts.
3. If a DNS Name artifact doesn’t exist, add one to the incident.
4. Click the hamburger menu for the artifact and select DT: Profile Domain with Iris.
5. Check the Notes section for the enrichment results.

Persist enrichment data in a data table

Persist enrichment data in data tables inside an incident so you can review it over the life of the incident and correlate multiple domain artifacts that share common traits. The DomainTools table shows the complete DomainTools intelligence across all artifacts for the incident.

To access the DomainTools tab:

1. Enrich an artifact with DT: Profile Domain with Iris, as described above.
2. Select the DomainTools tab to view the domain intelligence for the artifact.

Workflow to identify high-risk domains

A pre-built workflow that pivots on the DomainTools risk score to evaluate whether a domain is risky. The template lets you configure the risk threshold, which defaults to 90. If an artifact is deemed risky, the workflow appends a note to the incident with the risk score and domain artifact.

Workflow name: DomainTools: Check Domain Risk Score

To run the workflow:

1. Locate a DNS Name artifact, as described above.
2. Click the hamburger menu for the artifact and select DT: Domain Risk Score.
3. Check the Notes section for the results.

Workflow to discover malicious infrastructure

This workflow uses DomainTools guided pivots within an investigation. The template lets you configure a threshold for connected pivots, which defaults to 300 domains. It looks up associated IPs, SSL hashes, and registrant email addresses, then reverses on those artifacts to retrieve associated domains. Extend it with more decision steps to pivot on additional attributes. By default the workflow adds findings to the incident note; you can route findings to custom workflows or downstream systems.

Workflow name: DomainTools: Auto Pivot with Iris

To run the workflow:

1. Locate a DNS Name artifact, as described above.
2. Click the hamburger menu for the artifact and select DT: Auto Pivot with Iris.
3. Check the Notes section for the results.

Workflow to pivot on tagged domains

This workflow template detects whether a domain artifact has been tagged in Iris with a specific tag, and lets the incident response team take adaptive action based on the tag value. Customize it to process a list of tags and take different actions per tag; see the IBM Resilient workflow guide to customize the scripts and actions.

Workflow name: DomainTools: Check Domain Tags Template

To run the workflow:

1. Locate a DNS Name artifact, as described above.
2. Click the hamburger menu for the artifact and select DT: Check for Tagged-Domains.
3. Check the Notes section for the results.