IBM X-Force Exchange

LAST UPDATED: OCT 31, 2024

Overview

IBM X-Force Exchange (XFE) threat intelligence sharing platform enabling research on security threats, aggregation of intelligence, and collaboration with peers.

D3 SOAR is providing REST operations to function with IBM X-Force Exchange.

IBM X-Force Exchange is available for use in:

D3 SOAR	V12.7.129.0+
Category	Threat Intelligence
Deployment Options	Option II, Option IV

Connection

To connect to IBM X-Force Exchange from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The URL of the IBM X-Force Exchange server.	https://api.xforce.ibmcloud.com
API Key	The API key to authenticate the API connection.	*----**
API Password	The API password to authenticate the API connection.	*----**

Configuring IBM X-Force Exchange to Work with D3 SOAR

To generate an API Key and API Password, follow the steps in the X-Force Exchange API Docs.

Configuring D3 SOAR to Work with IBM X-Force Exchange

Log in to D3 SOAR.
Find the IBM X-Force Exchange integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type IBM X-Force Exchange in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to IBM X-Force Exchange.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System Reputation Check: Checking one or more reputation check tick boxes will run the corresponding check reputation command(s) under this integration connection to enrich the corresponding artifacts with reputation details.
  For example, we are configuring an integration connection named “ConnectionA” with the site “Sandbox”. All IP artifacts from the “Sandbox” site will go through a reputation check using the Check IP Reputation command from that integration. The return data output from running the command will then be used to update the risk level of the artifacts which may affect the risk level of incoming events.
10. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input your domain level Server URL. Default value is https://api.xforce.ibmcloud.com.
  2. Input your API Key. See Configuring IBM X-Force Exchange to work with D3 SOAR.
  3. Input your API Password. See Configuring IBM X-Force Exchange to work with D3 SOAR.
11. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
12. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection

Commands

IBM X-Force Exchange includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the IBM X-Force Exchange API, please refer to the IBM X-Force Exchange API reference.

Check File Reputation

Checks the risk level of file hashes.

Input

Input Parameter	Required/Optional	Description	Example
File Hashes	Required	The list of file hashes to check risk levels.	["8B***A","f2*21","6C***D"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "malware": {
            "origins": {
                "external": {
                    "source": "reversingLabs",
                    "firstSeen": "2014-09-25T17:30:04Z",
                    "lastSeen": "2021-08-03T16:39:32Z",
                    "malwareType": "Trojan",
                    "platform": "Win32",
                    "detectionCoverage": 83,
                    "family": [
                        "zeus"
                    ]
                }
            },
            "type": "sha256",
            "sha256": "*****",
            "hash": "*****",
            "risk": "high"
        },
        "tags": []
    },
    {
        "malware": {
            "origins": {
                "emails": {
                    "rows": [
                        {
                            "type": "SPM",
                            "md5": "*****",
                            "domain": "dhl.com",
                            "firstseen": "2018-08-13T07:15:00Z",
                            "lastseen": "2018-08-13T07:15:00Z",
                            "ip": "2.2.2.2",
                            "count": 1,
                            "filepath": "Case File *****.zip",
                            "origin": "SPM",
                            "uri": "Case File *****.zip"
                        }
                    ],
                    "count": 1
                },
                "CnCServers": {},
                "downloadServers": {},
                "subjects": {
                    "rows": [
                        {
                            "type": "email",
                            "md5": "*****",
                            "subject": "Court Order",
                            "firstseen": "2018-08-13T07:15:00Z",
                            "lastseen": "2018-08-13T07:15:00Z",
                            "count": 1,
                            "ips": [
                                "2.2.2.2"
                            ],
                            "origin": "email"
                        }
                    ],
                    "count": 1
                },
                "external": {
                    "source": "reversingLabs",
                    "firstSeen": "2018-08-13T07:48:30Z",
                    "lastSeen": "2021-09-19T05:02:43Z",
                    "malwareType": "Trojan",
                    "platform": "ByteCode",
                    "subPlatform": "JAVA",
                    "detectionCoverage": 34,
                    "family": [
                        "adwind"
                    ]
                }
            },
            "type": "md5",
            "md5": "******",
            "hash": "*****",
            "created": "2018-08-13T07:15:00Z",
            "family": [
                "Spam Zero-Day"
            ],
            "mimetype": "archive/zip",
            "familyMembers": {
                "Spam Zero-Day": {
                    "count": 5136705
                }
            },
            "risk": "high"
        },
        "tags": []
    },
    {
        "malware": {
            "origins": {
                "external": {
                    "source": "reversingLabs",
                    "firstSeen": "2019-11-03T02:29:24Z",
                    "lastSeen": "2021-07-25T12:11:37Z",
                    "malwareType": "Trojan",
                    "platform": "Linux",
                    "detectionCoverage": 48,
                    "family": [
                        "qsnatch"
                    ]
                }
            },
            "type": "sha1",
            "sha1": "*****",
            "hash": "*****",
            "risk": "high"
        },
        "tags": []
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

Context Data stores information that can be derived for Return Data.
In check reputation commands, data within the Context Data are risk scores converted into D3-defined risk levels from the raw data. There are 5 possible values of a D3 risk level: High, Medium, Low, Default, or ZeroRisk.

D3 also customizes the Context Data by extracting the "fieldHash", "type" and "riskLevel" fields in the API-returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "fileHash": "*****",
        "type": "sha256",
        "riskLevel": "high"
    },
    {
        "fileHash": "*****",
        "type": "md5",
        "riskLevel": "high"
    },
    {
        "fileHash": "*****",
        "type": "sha1",
        "riskLevel": "high"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "FileHashes": [
        "*****",
        "*****",
        "*****"
    ],
    "RiskLevels": [
        "high",
        "high",
        "high"
    ]
}

Return Data

In check reputation commands, Return Data converts the risk score from the raw data into D3-defined risk levels as a numerical value (1-5). This will be used to enrich artifacts with reputation information.

SAMPLE DATA

CODE

[
    {
        "fileHash": "*****",
        "riskLevel": "1"
    },
    {
        "fileHash": "*****",
        "riskLevel": "1"
    },
    {
        "fileHash": "*****",
        "riskLevel": "1"
    }
]

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

FILEHASH	TYPE	RISKLEVEL
0******A	sha256	high
0******1	md5	high
0*****D	sha1	high

D3-defined Risk Levels

The table below lists the possible output risk levels with the corresponding return context data:

Return Data	Context Data
1	High
2	Medium
3	Low
4	Default
5	ZeroRisk

Error Handling

If the Return Data is Error, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Check File Reputation failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the IBM X-Force Exchange portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid input.

Error Sample Data

Check File Reputation failed.

Status Code: 400.

Message: Invalid input.

Check IP Reputation

Checks the risk level of IP addresses.

Input

Input Parameter	Required/Optional	Description	Example
IP Addresses	Required	The list of IP addresses (IPv4 or IPv6) to check risk levels.	["8.8.8.8","2*0:1:::**"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "ip": "8.8.8.8",
        "history": [
            {
                "created": "2012-03-22T07:26:00Z",
                "reason": "Regional Internet Registry",
                "geo": {
                    "country": "United States",
                    "countrycode": "US"
                },
                "ip": "8.0.0.0/8",
                "categoryDescriptions": {},
                "reasonDescription": "One of the five RIRs announced a (new) location mapping of the IP.",
                "score": 1,
                "cats": {}
            }
        ],
        "subnets": [
            {
                "created": "2018-04-24T06:22:00Z",
                "reason": "Regional Internet Registry",
                "reason_removed": true,
                "asns": {
                    "3356": {
                        "removed": true,
                        "cidr": 8
                    }
                },
                "ip": "8.0.0.0",
                "categoryDescriptions": {},
                "reasonDescription": "One of the five RIRs announced a (new) location mapping of the IP.",
                "score": 1,
                "cats": {},
                "subnet": "8.0.0.0/8"
            }
        ],
        "cats": {},
        "geo": {
            "country": "United States",
            "countrycode": "US"
        },
        "score": 1,
        "reason": "Regional Internet Registry",
        "reasonDescription": "One of the five RIRs announced a (new) location mapping of the IP.",
        "categoryDescriptions": {},
        "tags": [
            {
                "type": "tag",
                "tag": "dhqj",
                "entityType": "report",
                "entityId": "ip-8.8.8.8",
                "commentId": "*****",
                "user": "http://www.ibm.com/550005YMQ9",
                "date": "2021-01-09T21:59:29.22Z",
                "displayName": "David Phillips"
            }
        ]
    },
    {
        "ip": "****:****:****:0000:0000:0000:0000:0035",
        "history": [
            {
                "created": "2014-04-12T06:27:00Z",
                "reason": "Regional Internet Registry",
                "geo": {
                    "country": "United States",
                    "countrycode": "US"
                },
                "ip": "****:****:0000:0000:0000:0000:0000:0000/40",
                "categoryDescriptions": {},
                "reasonDescription": "One of the five RIRs announced a (new) location mapping of the IP.",
                "score": 1,
                "cats": {}
            }
        ],
        "subnets": [
            {
                "created": "2014-04-12T06:27:00Z",
                "reason": "Regional Internet Registry",
                "geo": {
                    "country": "United States",
                    "countrycode": "US"
                },
                "ip": "****:****:0000:0000:0000:0000:0000:0000",
                "categoryDescriptions": {},
                "reasonDescription": "One of the five RIRs announced a (new) location mapping of the IP.",
                "score": 1,
                "cats": {},
                "subnet": "****:****:0000:0000:0000:0000:0000:0000/40"
            }
        ],
        "cats": {},
        "geo": {
            "country": "United States",
            "countrycode": "US"
        },
        "score": 1,
        "reason": "Regional Internet Registry",
        "reasonDescription": "One of the five RIRs announced a (new) location mapping of the IP.",
        "categoryDescriptions": {},
        "tags": []
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

Context Data stores information that can be derived for Return Data.
In check reputation commands, data within the Context Data are risk scores converted into D3-defined risk levels from the raw data. There are 5 possible values of a D3 risk level: High, Medium, Low, Default, or ZeroRisk.

D3 also customizes the Context Data by extracting the "ipAddress", "riskScore" and "riskLevel" fields in the API-returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "ipAddress": "8.8.8.8",
        "riskScore": 1,
        "riskLevel": "Low"
    },
    {
        "ipAddress": "****:****:****:0000:0000:0000:0000:0035",
        "riskScore": 1,
        "riskLevel": "Low"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Ips": [
        "8.8.8.8",
        "****:****:****:0000:0000:0000:0000:0035"
    ],
    "RiskScores": [
        1,
        1
    ],
    "RiskLevels": [
        "Low",
        "Low"
    ]
}

Return Data

In check reputation commands, Return Data converts the risk score from the raw data into D3-defined risk levels as a numerical value (1-5). This will be used to enrich artifacts with reputation information.

SAMPLE DATA

CODE

[
    {
        "ipAddress": "8.8.8.8",
        "riskScore": 1,
        "riskLevel": "3"
    },
    {
        "ipAddress": "****:****:****:0000:0000:0000:0000:0035",
        "riskScore": 1,
        "riskLevel": "3"
    }
]

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

IPADDRESS	RISKSCORE	RISKLEVEL
8.8.8.8	1	Low
**::**:0000:0000:0000:0000:0035	1	Low

D3-defined Risk Levels

The table below lists the possible output risk levels with the corresponding return context data:

Return Data	Context Data
1	High
2	Medium
3	Low
4	Default
5	ZeroRisk

Error Handling

If the Return Data is Error, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Check IP Reputation failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the IBM X-Force Exchange portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid input.

Error Sample Data

Check IP Reputation failed.

Status Code: 400.

Message: Invalid input.

Check URL Reputation

Checks the risk level of URLs.

Input

Input Parameter	Required/Optional	Description	Example
URLs	Required	The list of URLs to check risk levels.	["xmr.pool.minergate.com"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "result": {
            "url": "minergate.com",
            "cats": {
                "Cryptocurrency Mining": true
            },
            "score": 4,
            "categoryDescriptions": {
                "Cryptocurrency Mining": "This category contains websites that are involved in cryptocurrency mining, e.g. mining pools and websites running cryptocurrency mining scripts."
            }
        },
        "tags": []
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

Context Data stores information that can be derived for Return Data.
In check reputation commands, data within the Context Data are risk scores converted into D3-defined risk levels from the raw data. There are 5 possible values of a D3 risk level: High, Medium, Low, Default, or ZeroRisk.

D3 also customizes the Context Data by extracting the "url", "riskScore" and "riskLevel" fields in the API-returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "url": "minergate.com",
        "riskScore": 4,
        "riskLevel": "Medium"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "URLs": [
        "minergate.com"
    ],
    "RiskScores": [
        4
    ],
    "RiskLevels": [
        "Medium"
    ]
}

Return Data

In check reputation commands, Return Data converts the risk score from the raw data into D3-defined risk levels as a numerical value (1-5). This will be used to enrich artifacts with reputation information.

SAMPLE DATA

CODE

[
    {
        "url": "minergate.com",
        "riskScore": 4,
        "riskLevel": "2"
    }
]

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

URL	RISKSCORE	RISKLEVEL
minergate.com	4	Medium

D3-defined Risk Levels

The table below lists the possible output risk levels with the corresponding return context data:

Return Data	Context Data
1	High
2	Medium
3	Low
4	Default
5	ZeroRisk

Error Handling

If the Return Data is Error, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Check URL Reputation failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the IBM X-Force Exchange portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid input.

Error Sample Data

Check URL Reputation failed.

Status Code: 400.

Message: Invalid input.

Check Vulnerabilities

Checks the risk level of vulnerabilities.

Input

Input Parameter	Required/Optional	Description	Example
CVE IDs	Required	The list of CVE IDs of the vulnerabilities to check risk levels.	["CVE***","cve","CVE-2020-","CVE-2020-**"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "CVE2020*****": {
        "type": "vulnerability",
        "xfdbid": *****,
        "updateid": *****,
        "updated": true,
        "variant": "single",
        "title": "Apple iTunes for Window code execution",
        "description": "Apple iTunes for Windows could allow a remote attacker to execute arbitrary code on the system, caused by a use-after-free in the WebKit component. By persuading a victim to visit a specially-crafted Web site, a remote attacker could exploit this vulnerability to execute arbitrary code on the system.",
        "risk_level": 8.8,
        "cvss": {
            "version": "3.0",
            "privilegesrequired": "None",
            "userinteraction": "Required",
            "scope": "Unchanged",
            "access_vector": "Network",
            "access_complexity": "Low",
            "confidentiality_impact": "High",
            "integrity_impact": "High",
            "availability_impact": "High",
            "remediation_level": "Official Fix"
        },
        "temporal_score": 7.7,
        "remedy": "Refer to Apple security document *****for patch, upgrade or suggested workaround information. See References.",
        "remedy_fmt": "Refer to Apple security document *****for patch, upgrade or suggested workaround information. See References.",
        "reported": "2020-11-13T00:00:00Z",
        "tagname": "apple-itunes-*****-code-exec",
        "stdcode": [
            "CVE-2020-9947"
        ],
        "platforms_affected": [
            "Apple iTunes for Windows 12.10.8",
            "Apple iCloud for Windows 11.4"
        ],
        "exploitability": "Unproven",
        "consequences": "Gain Access",
        "references": [
            {
                "link_target": "https://support.apple.com/en-us/*****",
                "link_name": "Apple security document *****",
                "description": "About the security content of iTunes 12.10.9 for Windows"
            },
            {
                "link_target": "https://support.apple.com/en-us/******",
                "link_name": "Apple security document *****",
                "description": "About the security content of iCloud for Windows 11.5"
            },
            {
                "link_target": "https://www.zerodayinitiative.com/advisories/ZDI-20-*****/",
                "link_name": "ZDI-20-*****",
                "description": "Apple Safari RenderObject Use-After-Free Remote Code Execution Vulnerability"
            },
            {
                "link_target": "http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-*****",
                "link_name": "CVE-2020-*****",
                "description": "A use after free issue was addressed with improved memory management. This issue is fixed in watchOS 7.0, iOS 14.0 and iPadOS 14.0, iTunes for Windows 12.10.9, iCloud for Windows 11.5, tvOS 14.0, Safari 14.0. Processing maliciously crafted web content may lead to arbitrary code execution."
            }
        ],
        "report_confidence": "Confirmed"
    }
}

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

{
    "CVE2020****": {
        "type": "vulnerability",
        "xfdbid": *****,
        "updateid": *****,
        "updated": true,
        "variant": "single",
        "title": "Apple iTunes for Window code execution",
        "description": "Apple iTunes for Windows could allow a remote attacker to execute arbitrary code on the system, caused by a use-after-free in the WebKit component. By persuading a victim to visit a specially-crafted Web site, a remote attacker could exploit this vulnerability to execute arbitrary code on the system.",
        "risk_level": 8.8,
        "cvss": {
            "version": "3.0",
            "privilegesrequired": "None",
            "userinteraction": "Required",
            "scope": "Unchanged",
            "access_vector": "Network",
            "access_complexity": "Low",
            "confidentiality_impact": "High",
            "integrity_impact": "High",
            "availability_impact": "High",
            "remediation_level": "Official Fix"
        },
        "temporal_score": 7.7,
        "remedy": "Refer to Apple security document *****for patch, upgrade or suggested workaround information. See References.",
        "remedy_fmt": "Refer to Apple security document *****for patch, upgrade or suggested workaround information. See References.",
        "reported": "2020-11-13T00:00:00Z",
        "tagname": "apple-itunes-*****-code-exec",
        "stdcode": [
            "CVE-2020-9947"
        ],
        "platforms_affected": [
            "Apple iTunes for Windows 12.10.8",
            "Apple iCloud for Windows 11.4"
        ],
        "exploitability": "Unproven",
        "consequences": "Gain Access",
        "references": [
            {
                "link_target": "https://support.apple.com/en-us/*****",
                "link_name": "Apple security document *****",
                "description": "About the security content of iTunes 12.10.9 for Windows"
            },
            {
                "link_target": "https://support.apple.com/en-us/******",
                "link_name": "Apple security document *****",
                "description": "About the security content of iCloud for Windows 11.5"
            },
            {
                "link_target": "https://www.zerodayinitiative.com/advisories/ZDI-20-*****/",
                "link_name": "ZDI-20-*****",
                "description": "Apple Safari RenderObject Use-After-Free Remote Code Execution Vulnerability"
            },
            {
                "link_target": "http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-*****",
                "link_name": "CVE-2020-*****",
                "description": "A use after free issue was addressed with improved memory management. This issue is fixed in watchOS 7.0, iOS 14.0 and iPadOS 14.0, iTunes for Windows 12.10.9, iCloud for Windows 11.5, tvOS 14.0, Safari 14.0. Processing maliciously crafted web content may lead to arbitrary code execution."
            }
        ],
        "report_confidence": "Confirmed"
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "CVEIDs": [
        "CVE2020*****",
        "cve2020*****",
        "CVE-2020-*****",
        "CVE-2020-*****"
    ],
    "RiskLevels": [
        8.8,
        7.8,
        8.8,
        6.3
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CVE2020*****

{'type': 'vulnerability', 'xfdbid': *****, 'updateid': *****, 'updated': True, 'variant': 'single', 'title': 'Apple iTunes for Window code execution', 'description': 'Apple iTunes for Windows could allow a remote attacker to execute arbitrary code on the system, caused by a use-after-free in the WebKit component. By persuading a victim to visit a specially-crafted Web site, a remote attacker could exploit this vulnerability to execute arbitrary code on the system.', 'risk_level': 8.8, 'cvss': {'version': '3.0', 'privilegesrequired': 'None', 'userinteraction': 'Required', 'scope': 'Unchanged', 'access_vector': 'Network', 'access_complexity': 'Low', 'confidentiality_impact': 'High', 'integrity_impact': 'High', 'availability_impact': 'High', 'remediation_level': 'Official Fix'}, 'temporal_score': 7.7, 'remedy': 'Refer to Apple security document ******for patch, upgrade or suggested workaround information. See References.', 'remedy_fmt': '

Refer to Apple security document HT211952 for patch, upgrade or suggested workaround information. See References.

', 'reported': '2020-11-13T00:00:00Z', 'tagname': 'apple-itunes-cve2020*****-code-exec', 'stdcode': ['CVE-2020-*****'], 'platforms_affected': ['Apple iTunes for Windows 12.10.8', 'Apple iCloud for Windows 11.4'], 'exploitability': 'Unproven', 'consequences': 'Gain Access', 'references': [{'link_target': 'https://support.apple.com/en-us/*****', 'link_name': 'Apple security document *****', 'description': 'About the security content of iTunes 12.10.9 for Windows'}, {'link_target': 'https://support.apple.com/en-us/*****', 'link_name': 'Apple security document *****', 'description': 'About the security content of iCloud for Windows 11.5'}, {'link_target': 'https://www.zerodayinitiative.com/advisories/ZDI-20-*****/', 'link_name': 'ZDI-20-*****', 'description': 'Apple Safari RenderObject Use-After-Free Remote Code Execution Vulnerability'}, {'link_target': 'http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-*****', 'link_name': 'CVE-2020-*****', 'description': 'A use after free issue was addressed with improved memory management. This issue is fixed in watchOS 7.0, iOS 14.0 and iPadOS 14.0, iTunes for Windows 12.10.9, iCloud for Windows 11.5, tvOS 14.0, Safari 14.0. Processing maliciously crafted web content may lead to arbitrary code execution.'}], 'report_confidence': 'Confirmed'}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Check Vulnerabilities failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the IBM X-Force Exchange portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid input.

Error Sample Data

Check Vulnerabilities failed.

Status Code: 400.

Message: Invalid input.

Get Whois

Retrieves information about host addresses.

Input

Input Parameter	Required/Optional	Description	Example
Hosts	Required	The list of IPs, URLs or domains to retrieve host information.	["https://www.ibm.com/ca-en","ibm.com"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "createdDate": "1986-03-19T00:00:00Z",
        "updatedDate": "2021-03-16T01:12:58Z",
        "expiresDate": "2022-03-20T04:00:00Z",
        "contactEmail": "test@example.ibm.com",
        "registrarName": "CSC CORPORATE DOMAINS, INC.",
        "contact": [
            {
                "type": "registrant",
                "name": "IBM DNS Admin",
                "organization": "International Business Machines Corporation",
                "country": "United States"
            }
        ],
        "extended": {
            "createdDate": "1986-03-19T00:00:00Z",
            "updatedDate": "2021-03-16T01:12:58Z",
            "expiresDate": "2022-03-20T04:00:00Z",
            "contactEmail": "test@example.ibm.com",
            "registrarName": "CSC CORPORATE DOMAINS, INC.",
            "contact": [
                {
                    "type": "registrant",
                    "name": "IBM DNS Admin",
                    "organization": "International Business Machines Corporation",
                    "country": "United States"
                }
            ]
        }
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "createdDate": "1986-03-19T00:00:00Z",
        "updatedDate": "2021-03-16T01:12:58Z",
        "expiresDate": "2022-03-20T04:00:00Z",
        "contactEmail": "test@example.ibm.com",
        "registrarName": "CSC CORPORATE DOMAINS, INC.",
        "contact": [
            {
                "type": "registrant",
                "name": "IBM DNS Admin",
                "organization": "International Business Machines Corporation",
                "country": "United States"
            }
        ],
        "extended": {
            "createdDate": "1986-03-19T00:00:00Z",
            "updatedDate": "2021-03-16T01:12:58Z",
            "expiresDate": "2022-03-20T04:00:00Z",
            "contactEmail": "test@example.ibm.com",
            "registrarName": "CSC CORPORATE DOMAINS, INC.",
            "contact": [
                {
                    "type": "registrant",
                    "name": "IBM DNS Admin",
                    "organization": "International Business Machines Corporation",
                    "country": "United States"
                }
            ]
        }
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "ContactEmails": [
        "test@example.ibm.com",
        "test@example.ibm.com"
    ],
    "RegistrarNames": [
        "CSC CORPORATE DOMAINS, INC.",
        "CSC CORPORATE DOMAINS, INC."
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CREATEDDATE	UPDATEDDATE	EXPIRESDATE	CONTACTEMAIL	REGISTRARNAME	CONTACT	EXTENDED
1986-03-19T00:00:00.000Z	2021-03-16T01:12:58.000Z	2022-03-20T04:00:00.000Z	test@example.ibm.com	CSC *****DOMAINS, INC.	[{'type': 'registrant', 'name': 'IBM DNS Admin', 'organization': 'International Business Machines Corporation', 'country': 'United States'}]	{'createdDate': '1986-03-19T00:00:00.000Z', 'updatedDate': '2021-03-16T01:12:58.000Z', 'expiresDate': '2022-03-20T04:00:00.000Z', 'contactEmail': 'test@example.ibm.com', 'registrarName': 'CSC CORPORATE DOMAINS, INC.', 'contact': [{'type': 'registrant', 'name': 'IBM DNS Admin', 'organization': 'International Business Machines Corporation', 'country': 'United States'}]}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Whois failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the IBM X-Force Exchange portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid input.

Error Sample Data

Get Whois failed.

Status Code: 400.

Message: Invalid input.

Search Vulnerabilities

Searches for vulnerabilities based on the input conditions.

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Input

Input Parameter	Required/Optional	Description	Example
Start Date	Required	The start of the date range to search in UTC time.	2023-05-03 00:00
End Date	Optional	The end of the date range to search in UTC time. If this parameter is not defined, the query will return the newest vulnerabilities.	2023-05-08 00:00
Order	Optional	The order of returned vulnerabilities according to the reported date. The default value is descending.	descending
Limit	Optional	The number of vulnerabilities to search for.	10
Skip	Optional	The number of vulnerabilities to skip during the search operation.	8

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "rows": [
        {
            "type": "vulnerability",
            "xfdbid": *****,
            "updateid": *****,
            "updated": true,
            "variant": "single",
            "title": "SAP HANA DB IMPORT statement code execution",
            "description": "SAP HANA DB could allow a remote attacker to execute arbitrary code on the system, caused by a process termination error in an IMPORT statement. An attacker could exploit this vulnerability to execute arbitrary code on the system or cause the system to crash.",
            "risk_level": 7.3,
            "cvss": {
                "version": "3.0",
                "privilegesrequired": "None",
                "userinteraction": "None",
                "scope": "Unchanged",
                "access_vector": "Network",
                "access_complexity": "Low",
                "confidentiality_impact": "Low",
                "integrity_impact": "Low",
                "availability_impact": "Low",
                "remediation_level": "Official Fix"
            },
            "temporal_score": 6.4,
            "remedy": "Current SAP customers should refer to SAP note *****for patch information, available from the SAP Web site (login required). See References.",
            "remedy_fmt": "Current SAP customers should refer to SAP note *****for patch information, available from the SAP Web site (login required). See References.",
            "reported": "2016-01-01T00:00:00Z",
            "tagname": "sap-hanadb-******-code-exec",
            "stdcode": [
                "BID-*****",
                "CVE-2016-*****"
            ],
            "platforms_affected": [
                "SAP HANA DB 1.00.73.00.389160"
            ],
            "exploitability": "Unproven",
            "consequences": "Gain Access",
            "references": [
                {
                    "link_target": "https://layersevensecurity.com/wp-content/uploads/2016/02/Layer-Seven-Security_SAP-Security-Notes_January-2016.pdf",
                    "link_name": "Layer Seven Security Web site",
                    "description": "SAP Security Notes"
                }
            ],
            "report_confidence": "Confirmed",
            "uuid": "*****"
        }
    ],
    "previousPage": "/vulnerabilities?startDate=2016-01-01T00:00:00Z&endDate=2016-01-01T00:00:00Z&limit=10&descending=true&skip=0",
    "nextPage": ""
}

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.rows in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
        {
            "type": "vulnerability",
            "xfdbid": *****,
            "updateid": *****,
            "updated": true,
            "variant": "single",
            "title": "SAP HANA DB IMPORT statement code execution",
            "description": "SAP HANA DB could allow a remote attacker to execute arbitrary code on the system, caused by a process termination error in an IMPORT statement. An attacker could exploit this vulnerability to execute arbitrary code on the system or cause the system to crash.",
            "risk_level": 7.3,
            "cvss": {
                "version": "3.0",
                "privilegesrequired": "None",
                "userinteraction": "None",
                "scope": "Unchanged",
                "access_vector": "Network",
                "access_complexity": "Low",
                "confidentiality_impact": "Low",
                "integrity_impact": "Low",
                "availability_impact": "Low",
                "remediation_level": "Official Fix"
            },
            "temporal_score": 6.4,
            "remedy": "Current SAP customers should refer to SAP note *****for patch information, available from the SAP Web site (login required). See References.",
            "remedy_fmt": "Current SAP customers should refer to SAP note *****for patch information, available from the SAP Web site (login required). See References.",
            "reported": "2016-01-01T00:00:00Z",
            "tagname": "sap-hanadb-******-code-exec",
            "stdcode": [
                "BID-*****",
                "CVE-2016-*****"
            ],
            "platforms_affected": [
                "SAP HANA DB 1.00.73.00.389160"
            ],
            "exploitability": "Unproven",
            "consequences": "Gain Access",
            "references": [
                {
                    "link_target": "https://layersevensecurity.com/wp-content/uploads/2016/02/Layer-Seven-Security_SAP-Security-Notes_January-2016.pdf",
                    "link_name": "Layer Seven Security Web site",
                    "description": "SAP Security Notes"
                }
            ],
            "report_confidence": "Confirmed",
            "uuid": "*****"
        }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "CVEID": [
        "CVE-2016-****",
        "CVE-2016-****"
    ],
    "RiskLevels": [
        7.3,
        5.3
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

TYPE	XFDBID	UPDATEID	UPDATED	VARIANT	TITLE	DESCRIPTION	RISK_LEVEL	CVSS	TEMPORAL_SCORE	REMEDY	REMEDY_FMT	REPORTED	TAGNAME	STDCODE	PLATFORMS_AFFECTED	EXPLOITABILITY	CONSEQUENCES	REFERENCES	REPORT_CONFIDENCE	UUID
vulnerability	***	18480	True	single	SAP HANA DB IMPORT statement code execution	SAP HANA DB could allow a remote attacker to execute arbitrary code on the system, caused by a process termination error in an IMPORT statement. An attacker could exploit this vulnerability to execute arbitrary code on the system or cause the system to crash.	7.3	{'version': '3.0', 'privilegesrequired': 'None', 'userinteraction': 'None', 'scope': 'Unchanged', 'access_vector': 'Network', 'access_complexity': 'Low', 'confidentiality_impact': 'Low', 'integrity_impact': 'Low', 'availability_impact': 'Low', 'remediation_level': 'Official Fix'}	6.4	Current SAP customers should refer to SAP note *****for patch information, available from the SAP Web site (login required). See References.	Current SAP customers should refer to SAP note *****for patch information, available from the SAP Web site (login required). See References.	2016-01-01T00:00:00Z	sap-hanadb-****-code-exec	['BID-***', 'CVE-2016-***']	['SAP HANA DB ****8']	Unproven	Gain Access		Confirmed	**

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search Vulnerabilities failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the IBM X-Force Exchange portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The value for parameter (Skip) is invalid.

Error Sample Data

Search Vulnerabilities failed.

Status Code: 400.

Message: The value for parameter (Skip) is invalid.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the IBM X-Force Exchange portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Not authorized.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: Not authorized.