fn_whois_rdap

Table of Contents

Release Notes

Version

Date

Comment

1.0.6

9/2024

Refresh app for v51.0.0

1.0.5

4/2022

Bug fixes

1.0.4

6/2021

Bug fix ipwhois version pin

1.0.3

8/2020

Updated examples, proxy support added

1.0.2

4/2020

Bug fixes

1.0.1

4/2020

Support for App Host

1.0.0

12/2019

Initial release

Overview

Retrieve registry information for IP, URL or DNS Artifacts

screenshot: main

This integration retrieves registry information (via legacy WHOIS or new RDAP protocol) for IP, URL or DNS Artifacts that provides enrichment and threat intelligence on suspicious address. The information is added directly to artifact description and can include dns-zone, asn, and asn description & other useful metadata.

Key Features

  • Retrieves Registry information for IP’s, DNS or URL’s

  • Either the RDAP or WHOIS format of data can be returned

  • Information is sent directly to the Artifact Description

Requirements

This app supports the IBM Security QRadar SOAR Platform and the IBM Security QRadar SOAR for IBM Cloud Pak for Security.

SOAR platform

The SOAR platform supports two app deployment mechanisms, Edge Gateway (also known as App Host) and integration server.

If deploying to a SOAR platform with an App Host, the requirements are:

  • SOAR platform >= 51.0.0.0.9340.

  • The app is in a container-based format (available from the AppExchange as a zip file).

If deploying to a SOAR platform with an integration server, the requirements are:

  • SOAR platform >= 51.0.0.0.9340.

  • The app is in the older integration format (available from the AppExchange as a zip file which contains a tar.gz file).

  • Integration server is running resilient_circuits>=44.1.0.

  • If using an API key account, make sure the account provides the following minimum permissions:

    Name

    Permissions

    Org Data

    Read

    Function

    Read

The following SOAR platform guides provide additional information:

  • Edge Gateway Deployment Guide or App Host Deployment Guide: provides installation, configuration, and troubleshooting information, including proxy server settings.

  • Integration Server Guide: provides installation, configuration, and troubleshooting information, including proxy server settings.

  • System Administrator Guide: provides the procedure to install, configure and deploy apps.

The above guides are available on the IBM Documentation website at ibm.biz/soar-docs. On this web page, select your SOAR platform version. On the follow-on page, you can find the Edge Gateway Deployment Guide, App Host Deployment Guide, or Integration Server Guide by expanding Apps in the Table of Contents pane. The System Administrator Guide is available by expanding System Administrator.

Cloud Pak for Security

If you are deploying to IBM Cloud Pak for Security, the requirements are:

  • IBM Cloud Pak for Security >= 1.10.15.

  • Cloud Pak is configured with an Edge Gateway.

  • The app is in a container-based format (available from the AppExchange as a zip file).

The following Cloud Pak guides provide additional information:

  • Edge Gateway Deployment Guide or App Host Deployment Guide: provides installation, configuration, and troubleshooting information, including proxy server settings. From the Table of Contents, select Case Management and Orchestration & Automation > Orchestration and Automation Apps.

  • System Administrator Guide: provides information to install, configure, and deploy apps. From the IBM Cloud Pak for Security IBM Documentation table of contents, select Case Management and Orchestration & Automation > System administrator.

These guides are available on the IBM Documentation website at ibm.biz/cp4s-docs. From this web page, select your IBM Cloud Pak for Security version. From the version-specific IBM Documentation page, select Case Management and Orchestration & Automation.

Proxy Server

The app does support a proxy server.

Python Environment

Python 3.9, 3.11, and 3.12 are officially supported. When deployed as an app, the app runs on Python 3.11. Additional package dependencies may exist for each of these packages:

  • future~=0.18

  • ipwhois==1.1.0

  • requests-file==1.5.1; python_version<=’3.6’

  • resilient_circuits>=44.1.0

  • tldextract~=2.2; python_version<”3.0”

  • tldextract~=3.0; python_version>=”3.0”

Installation

Install

  • To install or uninstall an App or Integration on the SOAR platform, see the documentation at ibm.biz/soar-docs.

  • To install or uninstall an App on IBM Cloud Pak for Security, see the documentation at ibm.biz/cp4s-docs and follow the instructions above to navigate to Orchestration and Automation.

App Configuration

The following table provides the settings you need to configure the app. These settings are made in the app.config file. See the documentation discussed in the Requirements section for the procedure.

Config

Required

Example

Description

http_proxy

No

http://

HTTP proxy, if used

https_proxy

No

https://

HTTPS proxy, if used

Function - RDAP: Query

Using ipwhois library to make general queries in RDAP format

screenshot: fn-rdap-query

Inputs:

Name

Type

Required

Example

Tooltip

rdap_depth

number

Yes

0

Can be 0, 1 or 2

rdap_query

text

Yes

ibm.com

IP, URL or DNS Artifact

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "asn": "8075",
    "asn_cidr": "172.200.0.0/13",
    "asn_country_code": "GB",
    "asn_date": "2002-02-13",
    "asn_description": "MICROSOFT-CORP-MSN-AS-BLOCK, US",
    "asn_registry": "ripencc",
    "display_content": "{ \"dns_zone\":\"25.147.206.172.origin.asn.cymru.com\" }",
    "dns_zone": "25.147.206.172.origin.asn.cymru.com",
    "entities": [
      "DH5439-RIPE",
      "MICROSOFT-MAINT",
      "MRPA3-RIPE",
      "ORG-MA42-RIPE",
      "RIPE-NCC-HM-MNT",
      "MAC274-RIPE"
    ],
    "network": {
      "cidr": "172.128.0.0/10, 172.192.0.0/12, 172.208.0.0/13",
      "country": "GB",
      "end_address": "172.215.255.255",
      "events": [
        {
          "action": "registration",
          "actor": null,
          "timestamp": "2024-05-16T09:38:13Z"
        },
        {
          "action": "last changed",
          "actor": null,
          "timestamp": "2024-05-16T09:38:13Z"
        }
      ],
      "handle": "172.128.0.0 - 172.215.255.255",
      "ip_version": "v4",
      "links": [
        "https://rdap.db.ripe.net/ip/172.206.147.25",
        "http://www.ripe.net/data-tools/support/documentation/terms"
      ],
      "name": "UK-MICROSOFT-20000324",
      "notices": [
        {
          "description": "This output has been filtered.",
          "links": null,
          "title": "Filtered"
        },
        {
          "description": "If you see inaccuracies in the results, please visit:",
          "links": [
            "https://www.ripe.net/contact-form?topic=ripe_dbm\u0026show_form=true"
          ],
          "title": "Whois Inaccuracy Reporting"
        },
        {
          "description": "Objects returned came from source\nRIPE",
          "links": null,
          "title": "Source"
        },
        {
          "description": "This is the RIPE Database query service. The objects are in RDAP format.",
          "links": [
            "http://www.ripe.net/db/support/db-terms-conditions.pdf"
          ],
          "title": "Terms and Conditions"
        }
      ],
      "parent_handle": "0.0.0.0 - 255.255.255.255",
      "raw": null,
      "remarks": null,
      "start_address": "172.128.0.0",
      "status": [
        "active"
      ],
      "type": "ALLOCATED PA"
    },
    "nir": null,
    "objects": {
      "DH5439-RIPE": {
        "contact": {
          "address": [
            {
              "type": null,
              "value": "One Microsoft Way\nRedmond, WA 98052"
            }
          ],
          "email": null,
          "kind": "individual",
          "name": "Divya Quamara",
          "phone": [
            {
              "type": "voice",
              "value": "+1-425-882-8080"
            }
          ],
          "role": null,
          "title": null
        },
        "entities": null,
        "events": null,
        "events_actor": null,
        "handle": "DH5439-RIPE",
        "links": [
          "https://rdap.db.ripe.net/entity/DH5439-RIPE",
          "http://www.ripe.net/data-tools/support/documentation/terms"
        ],
        "notices": null,
        "raw": null,
        "remarks": null,
        "roles": [
          "administrative"
        ],
        "status": null
      },
      "MAC274-RIPE": {
        "contact": {
          "address": [
            {
              "type": null,
              "value": "One Microsoft Way\nRedmond, WA 98052"
            }
          ],
          "email": [
            {
              "type": "abuse",
              "value": "abuse@microsoft.com"
            }
          ],
          "kind": "group",
          "name": "Microsoft Abuse Contact",
          "phone": null,
          "role": null,
          "title": null
        },
        "entities": [
          "MICROSOFT-MAINT"
        ],
        "events": null,
        "events_actor": null,
        "handle": "MAC274-RIPE",
        "links": null,
        "notices": null,
        "raw": null,
        "remarks": null,
        "roles": [
          "abuse"
        ],
        "status": null
      },
      "MICROSOFT-MAINT": {
        "contact": {
          "address": null,
          "email": null,
          "kind": "individual",
          "name": "MICROSOFT-MAINT",
          "phone": null,
          "role": null,
          "title": null
        },
        "entities": null,
        "events": null,
        "events_actor": null,
        "handle": "MICROSOFT-MAINT",
        "links": [
          "https://rdap.db.ripe.net/entity/MICROSOFT-MAINT",
          "http://www.ripe.net/data-tools/support/documentation/terms"
        ],
        "notices": null,
        "raw": null,
        "remarks": null,
        "roles": [
          "registrant"
        ],
        "status": null
      },
      "MRPA3-RIPE": {
        "contact": {
          "address": [
            {
              "type": null,
              "value": "One Microsoft Way\nRedmond, WA 98052"
            }
          ],
          "email": null,
          "kind": "group",
          "name": "Microsoft Routing, Peering, and DNS",
          "phone": null,
          "role": null,
          "title": null
        },
        "entities": null,
        "events": null,
        "events_actor": null,
        "handle": "MRPA3-RIPE",
        "links": [
          "https://rdap.db.ripe.net/entity/MRPA3-RIPE",
          "http://www.ripe.net/data-tools/support/documentation/terms"
        ],
        "notices": null,
        "raw": null,
        "remarks": null,
        "roles": [
          "technical"
        ],
        "status": null
      },
      "ORG-MA42-RIPE": {
        "contact": {
          "address": [
            {
              "type": null,
              "value": "One Microsoft Way\nWA 98052\nRedmond\nUNITED STATES"
            }
          ],
          "email": null,
          "kind": "org",
          "name": "Microsoft Limited",
          "phone": [
            {
              "type": "voice",
              "value": "+1 425 882 8080"
            },
            {
              "type": "fax",
              "value": "+1 425 936 7329"
            }
          ],
          "role": null,
          "title": null
        },
        "entities": null,
        "events": null,
        "events_actor": null,
        "handle": "ORG-MA42-RIPE",
        "links": [
          "https://rdap.db.ripe.net/entity/ORG-MA42-RIPE",
          "http://www.ripe.net/data-tools/support/documentation/terms"
        ],
        "notices": null,
        "raw": null,
        "remarks": null,
        "roles": [
          "registrant"
        ],
        "status": null
      },
      "RIPE-NCC-HM-MNT": {
        "contact": {
          "address": null,
          "email": null,
          "kind": "individual",
          "name": "RIPE-NCC-HM-MNT",
          "phone": null,
          "role": null,
          "title": null
        },
        "entities": null,
        "events": null,
        "events_actor": null,
        "handle": "RIPE-NCC-HM-MNT",
        "links": [
          "https://rdap.db.ripe.net/entity/RIPE-NCC-HM-MNT",
          "http://www.ripe.net/data-tools/support/documentation/terms"
        ],
        "notices": null,
        "raw": null,
        "remarks": null,
        "roles": [
          "registrant"
        ],
        "status": null
      }
    },
    "query": "172.206.147.25",
    "raw": null
  },
  "inputs": {
    "rdap_depth": 0,
    "rdap_query": "172.206.147.25"
  },
  "metrics": {
    "execution_time_ms": 1470,
    "host": "my.app.host",
    "package": "fn-whois-rdap",
    "package_version": "1.0.5",
    "timestamp": "2024-09-24 13:56:32",
    "version": "1.0"
  },
  "raw": "",
  "reason": null,
  "success": true,
  "version": "1.0"
}

Example Function Input Script: 

inputs.rdap_query = artifact.value
inputs.rdap_depth = 0

Example Function Post Process Script: 

def format_link(item):
  if item and ("https://" in item or "http://" in item):
    return "<a target='blank' href='{0}'>{0}</a>".format(item)
  else:
    return item

def expand_list(list_value, separator="<br>"):
  if not isinstance(list_value, list):
    return format_link(list_value)
  else:
    try:
      items = []
      for item in list_value:
        if isinstance(item, dict):
          items.append("<div style='padding:10px'>{}</div>".format(walk_dict(item)))
        else:
          items.append(format_link(item))
      return separator.join(items)
    except:
        pass
    
def walk_dict(sub_dict):
  notes = []
  for key, value in sub_dict.items():
    if key not in ['display_content']:
      if isinstance(value, dict):
        notes.append(u"<b>{}</b>: <div style='padding:10px'>{}</div>".format(key, walk_dict(value)))
      else:
        notes.append(u"<b>{}</b>: {}".format(key, expand_list(value)))
      
  return u"<br>".join(notes)
    

note = u"RDAP Whois for artifact: {}<br><br>".format(artifact.value)
if results["success"]:
  note = note + walk_dict(results["content"])
else:
  note = note + u"This Artifact has no ans accessible registry information"

incident.addNote(helper.createRichText(note))

Function - WHOIS: query

Using ipwhois library to make general queries in whois format

screenshot: fn-whois-query

Inputs:

Name

Type

Required

Example

Tooltip

whois_query

text

Yes

ibm.com

IP, URL or DNS Artifact

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "asn": "8075",
    "asn_cidr": "172.200.0.0/13",
    "asn_country_code": "GB",
    "asn_date": "2002-02-13",
    "asn_description": "MICROSOFT-CORP-MSN-AS-BLOCK, US",
    "asn_registry": "ripencc",
    "display_content": "{ \"dns_zone\":\"25.147.206.172.origin.asn.cymru.com\" }",
    "dns_zone": "25.147.206.172.origin.asn.cymru.com",
    "nets": [
      {
        "address": "One Microsoft Way\nWA 98052\nRedmond\nUNITED STATES",
        "cidr": "172.128.0.0/10, 172.192.0.0/12, 172.208.0.0/13",
        "city": null,
        "country": "GB",
        "created": "2024-05-16T09:38:13Z",
        "description": "Microsoft Corporation AS8075\nTo report suspected security issues specific to\ntraffic emanating from Microsoft online services,\nincluding the distribution of malicious content\nor other illicit or illegal material through a\nMicrosoft online service, please submit reports\nto:\n* https://cert.microsoft.com\nFor SPAM and other abuse issues, such as Microsoft\nAccounts, please contact:\n* abuse@microsoft.com\nTo report security vulnerabilities in Microsoft\nproducts and services, please contact:\n* secure@microsoft.com\nFor legal and law enforcement-related requests,\nplease contact:\n* msndcc@microsoft.com\nFor routing, peering or DNS issues, please\ncontact:\n* IOC@microsoft.com",
        "emails": [
          "abuse@microsoft.com",
          "secure@microsoft.com",
          "msndcc@microsoft.com",
          "IOC@microsoft.com"
        ],
        "handle": "MRPA3-RIPE",
        "name": "UK-MICROSOFT-20000324",
        "postal_code": null,
        "range": "172.128.0.0 - 172.215.255.255",
        "state": null,
        "updated": "2024-05-16T09:38:13Z"
      },
      {
        "address": null,
        "cidr": "172.200.0.0/13",
        "city": null,
        "country": null,
        "created": "2022-07-08T19:11:00Z",
        "description": "Microsoft",
        "emails": null,
        "handle": null,
        "name": null,
        "postal_code": null,
        "range": "172.200.0.0 - 172.207.255.255",
        "state": null,
        "updated": "2022-07-08T19:11:00Z"
      }
    ],
    "nir": null,
    "query": "172.206.147.25",
    "raw": null,
    "raw_referral": null,
    "referral": null
  },
  "inputs": {
    "whois_query": "172.206.147.25"
  },
  "metrics": {
    "execution_time_ms": 1307,
    "host": "my.app.host",
    "package": "fn-whois-rdap",
    "package_version": "1.0.5",
    "timestamp": "2024-09-24 13:57:53",
    "version": "1.0"
  },
  "raw": "",
  "reason": null,
  "success": true,
  "version": "1.0"
}

Example Function Input Script: 

inputs.whois_query = artifact.value

Example Function Post Process Script: 

def format_link(item):
  if item and ("https://" in item or "http://" in item):
    return "<a target='blank' href='{0}'>{0}</a>".format(item)
  else:
    return item

def expand_list(list_value, separator="<br>"):
  if not isinstance(list_value, list):
    return format_link(list_value)
  else:
    try:
      items = []
      for item in list_value:
        if isinstance(item, dict):
          items.append("<div style='padding:10px'>{}</div>".format(walk_dict(item)))
        else:
          items.append(format_link(item))
      return separator.join(items)
    except:
        pass
    
def walk_dict(sub_dict):
  notes = []
  for key, value in sub_dict.items():
    if key not in ['display_content']:
      if isinstance(value, dict):
        notes.append(u"<b>{}</b>: <div style='padding:10px'>{}</div>".format(key, walk_dict(value)))
      else:
        notes.append(u"<b>{}</b>: {}".format(key, expand_list(value)))
      
  return u"<br>".join(notes)
    

note = u"Whois for artifact: {}<br><br>".format(artifact.value)
if results["success"]:
  note = note + walk_dict(results["content"])
else:
  note = note + u"This Artifact has no whois information"

incident.addNote(helper.createRichText(note))

Rules

Rule Name

Object

Workflow Triggered

Condition

Run rdap query against Artifact

artifact

example_rdap_query

artifact.type in ['IP Address', 'DNS Name', 'URL']

Run whois query against Artifact (RDAP)

artifact

example_whois_query

artifact.type in ['IP Address', 'DNS Name', 'URL']

Troubleshooting & Support

Refer to the documentation listed in the Requirements section for troubleshooting information.

For Support

This is a IBM Community provided app. Please search the Community ibm.biz/soarcommunity for assistance.