Fortinet Document Library

Version:


Table of Contents

1.0.1
Copy Link

About the connector

IBM X-Force is a cloud-based threat intelligence platform that allows you to consume, share, and act on threat intelligence. It enables you to rapidly research the latest global security threats, aggregate actionable intelligence, consult with experts, and collaborate with peers. IBM X-Force, supported by human- and machine-generated intelligence, leverages the scale of IBM X-Force to help users stay ahead of emerging threats.

This document provides information about the XForce connector, which facilitates automated interactions, with an IBM XForce server using FortiSOAR™ playbooks. Add the xforce connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving reputation of an IP address that you have specified or searching for a signature of a term or XPU.

 

Version information

Connector Version: 1.0.1

Compatibility with FortiSOAR™ Versions: 4.9.0.0-708 and later

Compatibility with IBM X Force build Number: 22700 and later

 

Release Notes for version 1.0.1

Following enhancements have been made to the XForce Connector in version 1.0.1:

  • Renamed the following operations and associated playbooks to make it more user-friendly:
    Get IP Malware Content renamed to Get IP Behavior
    Get Report for URL renamed to Get URL Report
    Get Malware for URL renamed to Get URL Behavior
    Get Malware By Family to Get Relative Malware
    Get Malware for File Hash renamed to Get File Reputation using FileHash
    Identify IP Owner to Get IP Registrant
    Get Live and Passive DNS Record to Get DNS Record
    Search Vulnerability by XFID renamed to Get Vulnerability from XFID
    Search Vulnerability by STDCode renamed to Get Vulnerability from STDCODE
    Search Vulnerability renamed to Get Vulnerability
  • Updated the API Key field, which is part of the configuration parameters, to a text field instead of a password field for readability purposes.
  • Added a default value to the Host Name field in the api.xforce.ibmcloud.com format.
  • Renamed the connector from XForce to IBM XForce.

Important: When you upgrade the IBM XForce connector from version 1.0.0 to 1.0.1, connector configuration is lost. This impacts the functioning of the playbook(s) using this connector. To solve this issue, you must recreate the connector configuration and update the playbook(s) to use the new configuration.

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

  • You must have the URL of xforce REST endpoint to which you will connect and perform the automated operations and the credentials to access that endpoint.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

 

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the XForce connector and click Configure to configure the following parameters:

 

Parameter Description
Host Name Host name of the IBM XForce API endpoint to which you will connect and perform the automated operations.
The Host Name is added by default and it is in the api.xforce.ibmcloud.com format.
API Key API key configured for your account for using the API endpoint.
API Password API Password to access the XForce API endpoint.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
Defaults to True.

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Get IP Reputation Retrieves the reputation, along with the score and other details, of the specified IP address. ip_reputation
Investigation
Get IP Behavior Retrieves the behavioral analysis for the specified IP address. malware_content
Investigation
Get IP Report Retrieves a report for the specified IP address get_report
Investigation
Get URL Report Retrieves a report for the specified URL address. get_report
Investigation
Get URL Behavior Retrieves the behavioral analysis for the specified URL address. malware_content
Investigation
Get Relative Malware Retrieves all active malware related to the malware family name that you have specified. malware_content
Investigation
Get File Reputation using FileHash Retrieves a report of a provided file from the specified file hash. file_reputation
Investigation
Get IP Registrant Retrieves the details of the registrant based on the Host details that you have specified. whois_info
Investigation
Search Signature Retrieves a list of signatures based on the search term that you have specified. search_signature
Investigation
Search Signature by XPU Retrieves a list of signatures based on the XPU that you have specified. search_signature
Investigation
Search Signature by PAMID Retrieves a list of signatures based on the PAMID that you have specified. search_signature
Investigation
Get DNS Record Retrieves DNS information based on the IP address, Domain or URL that you have specified. dns_details
Investigation
Get Vulnerability from XFID Retrieves a list of vulnerabilities based on the XFID number that you have specified. search_vulnerability
Investigation
Get Vulnerability from STDCODE Retrieves a list of vulnerabilities based on the STDCODE number that you have specified. search_vulnerability
Investigation
Get Vulnerability Retrieves a list of vulnerabilities based on the search term that you have specified. search_vulnerability
Investigation

 

operation: Get IP Reputation

Input parameters

 

Parameter Description
IP IP address of the system for which you want to retrieve reputation information.

 

Output

The JSON output contains the reputation with the score and other details of the specified IP address.

Following image displays a sample output:

 

Sample output of the Get IP Reputation operation

 

operation: Get IP Behavior

Input parameters

 

Parameter Description
IP IP address of the system for which you want to retrieve behavioral information.

 

Output

The JSON output contains the behavioral analysis of the specified IP address.

Following image displays a sample output:

 

Sample output of the Get IP Behavior operation

 

operation: Get IP Report

Input parameters

 

Parameter Description
IP IP address of the system for which you want to generate the report.

 

Output

The JSON output contains the report of the specified IP address.

Following image displays a sample output:

 

Sample output of the Get IP Report operation

 

operation: Get URL Report

Input parameters

 

Parameter Description
URL URL of the system for which you want to generate the report.

 

Output

The JSON output contains the report of the specified URL.

Following image displays a sample output:

 

Sample output of the Get URL Report operation

 

operation: Get URL Behavior

Input parameters

 

Parameter Description
URL URL of the system for which you want to retrieve behavioral information.

 

Output

The JSON output contains the behavioral analysis of the specified URL.

Following image displays a sample output:

 

Sample output of the Get URL Behavior operation

 

operation: Get Relative Malware

Input parameters

 

Parameter Description
Family Name of the family based on which you want to retrieve all related active malware.

 

Output

The JSON output contains the all related active malware of the specified family.

Following image displays a sample output:

 

Sample output of the Get Relative Malware operation

 

operation: Get File Reputation using FileHash

Input parameters

 

Parameter Description
File Hash Single file hash or a list of file hash based on which you want to retrieve the reputation of a file.
File hash supported format md5, sha1, and sha256.

 

Output

The JSON output contains a report of the provided file based on the specified file hash.

Following image displays a sample output:

 

Sample output of the Get File Reputation using FileHash operation

 

operation: Get IP Registrant

Input parameters

 

Parameter Description
Host Hostname, IP address, or URL of the system for which you want to retrieve registrant details.

 

Output

The JSON output contains the registrant details of the specified host.

Following image displays a sample output:

 

Sample output of the Get IP Registrant operation

 

operation: Search Signature

Input parameters

 

Parameter Description
Query String Search term based on which you want to search for a signature.

 

Output

The JSON output contains a list of signatures associated with the specified search term.

Following image displays a sample output:

 

Sample output of the Search Signature operation

 

operation: Search Signature by XPU

Input parameters

 

Parameter Description
XPU XPU name based on which you want to search for a signature.

 

Output

The JSON output contains a list of signatures associated with the specified XPU.

Following image displays a sample output:

 

Sample output of the Search Signature by XPU operation

 

operation: Search Signature by PAMID

Input parameters

 

Parameter Description
PAMID PAMID based on which you want to search for a signature.

 

Output

The JSON output contains a list of signatures associated with the specified PAMID.

Following image displays a sample output:

 

Sample output of the Search Signature by PAMID operation

 

operation: Get DNS Record

Input parameters

 

Parameter Description
Query IP address, Domain, or URL based on which you want to search for DNS information.

 

Output

The JSON output contains the DNS information associated with the specified IP address, Domain or URL.

Following image displays a sample output:

 

Sample output of the Get DNS Record operation

 

operation: Get Vulnerability from XFID

Input parameters

 

Parameter Description
xfid XFID based on which retrieve a vulnerability list.

 

Output

The JSON output contains a list of vulnerabilities associated with the specified XFID.

Following image displays a sample output:

 

Sample output of the Get Vulnerability from XFID operation

 

operation: Get Vulnerability from STDCODE

Input parameters

 

Parameter Description
STDCODE STDCODE number based on which retrieve a vulnerability list.

 

Output

The JSON output contains a list of vulnerabilities associated with the specified STDCODE.

Following image displays a sample output:

 

Sample output of the Get Vulnerability from STDCODE operation

 

operation: Get Vulnerability

Input parameters

 

Parameter Description
query Search term based on which retrieve a vulnerability list.
For example, Heartbleed is used for searching for vulnerabilities based on affected platforms.
Start date Start of the daterange from which you want to search for vulnerabilities.
End date End of the daterange till when you want to search for vulnerabilities.
bookmark Bookmark used to page through the results

 

Output

The JSON output contains a list of vulnerabilities associated with the specified search term.

Following image displays a sample output:

 

Sample output of the Get Vulnerability operation

 

Included playbooks

The Sample-IBM XForce-1.0.1 playbook collection comes bundled with the IBM XForce connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the IBM XForce connector.

  • Get DNS record
  • Get File Reputation using File Hash
  • Get IP Behavior
  • Get IP Registrant
  • Get IP Report
  • Get IP Reputation
  • Get Relative Malware
  • Get URL Behavior
  • Get URL Report
  • Get Vulnerability
  • Get Vulnerability by STDCODE
  • Get Vulnerability by XFID
  • Search Signature
  • Search Signature by PAMID
  • Search Signature by XPU

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

 

Troubleshooting

Connection refusal while requesting to run the wrapper

This generally occurs in the case of self-signed SSL certificates. If you are using self-signed certificates for testing or staging, keep in mind this problem will not occur in production and you might need to switch the certificates on or off.

Resolution:

Ensure that the SSL certificates are trusted or that SSL checking is turned off in the wrapper script. This is not advised for production instances.

Playbook fails after the ingestion is triggered

There are many reasons for a playbook failure, for example, if a required field is null in the target module record, or there are problems with the Playbook Appliance keys.

Resolution:

Investigate the reason for failure using the Running Playbooks tab in the Playbook Administration page. Review the step in which the failure is being generated and the result of the step, which should contain the trace of the error. Once you have identified the error and if you cannot troubleshoot the error, contact Fortinet support for further assistance.

 

About the connector

IBM X-Force is a cloud-based threat intelligence platform that allows you to consume, share, and act on threat intelligence. It enables you to rapidly research the latest global security threats, aggregate actionable intelligence, consult with experts, and collaborate with peers. IBM X-Force, supported by human- and machine-generated intelligence, leverages the scale of IBM X-Force to help users stay ahead of emerging threats.

This document provides information about the XForce connector, which facilitates automated interactions, with an IBM XForce server using FortiSOAR™ playbooks. Add the xforce connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving reputation of an IP address that you have specified or searching for a signature of a term or XPU.

 

Version information

Connector Version: 1.0.1

Compatibility with FortiSOAR™ Versions: 4.9.0.0-708 and later

Compatibility with IBM X Force build Number: 22700 and later

 

Release Notes for version 1.0.1

Following enhancements have been made to the XForce Connector in version 1.0.1:

Important: When you upgrade the IBM XForce connector from version 1.0.0 to 1.0.1, connector configuration is lost. This impacts the functioning of the playbook(s) using this connector. To solve this issue, you must recreate the connector configuration and update the playbook(s) to use the new configuration.

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

 

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the XForce connector and click Configure to configure the following parameters:

 

Parameter Description
Host Name Host name of the IBM XForce API endpoint to which you will connect and perform the automated operations.
The Host Name is added by default and it is in the api.xforce.ibmcloud.com format.
API Key API key configured for your account for using the API endpoint.
API Password API Password to access the XForce API endpoint.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
Defaults to True.

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Get IP Reputation Retrieves the reputation, along with the score and other details, of the specified IP address. ip_reputation
Investigation
Get IP Behavior Retrieves the behavioral analysis for the specified IP address. malware_content
Investigation
Get IP Report Retrieves a report for the specified IP address get_report
Investigation
Get URL Report Retrieves a report for the specified URL address. get_report
Investigation
Get URL Behavior Retrieves the behavioral analysis for the specified URL address. malware_content
Investigation
Get Relative Malware Retrieves all active malware related to the malware family name that you have specified. malware_content
Investigation
Get File Reputation using FileHash Retrieves a report of a provided file from the specified file hash. file_reputation
Investigation
Get IP Registrant Retrieves the details of the registrant based on the Host details that you have specified. whois_info
Investigation
Search Signature Retrieves a list of signatures based on the search term that you have specified. search_signature
Investigation
Search Signature by XPU Retrieves a list of signatures based on the XPU that you have specified. search_signature
Investigation
Search Signature by PAMID Retrieves a list of signatures based on the PAMID that you have specified. search_signature
Investigation
Get DNS Record Retrieves DNS information based on the IP address, Domain or URL that you have specified. dns_details
Investigation
Get Vulnerability from XFID Retrieves a list of vulnerabilities based on the XFID number that you have specified. search_vulnerability
Investigation
Get Vulnerability from STDCODE Retrieves a list of vulnerabilities based on the STDCODE number that you have specified. search_vulnerability
Investigation
Get Vulnerability Retrieves a list of vulnerabilities based on the search term that you have specified. search_vulnerability
Investigation

 

operation: Get IP Reputation

Input parameters

 

Parameter Description
IP IP address of the system for which you want to retrieve reputation information.

 

Output

The JSON output contains the reputation with the score and other details of the specified IP address.

Following image displays a sample output:

 

Sample output of the Get IP Reputation operation

 

operation: Get IP Behavior

Input parameters

 

Parameter Description
IP IP address of the system for which you want to retrieve behavioral information.

 

Output

The JSON output contains the behavioral analysis of the specified IP address.

Following image displays a sample output:

 

Sample output of the Get IP Behavior operation

 

operation: Get IP Report

Input parameters

 

Parameter Description
IP IP address of the system for which you want to generate the report.

 

Output

The JSON output contains the report of the specified IP address.

Following image displays a sample output:

 

Sample output of the Get IP Report operation

 

operation: Get URL Report

Input parameters

 

Parameter Description
URL URL of the system for which you want to generate the report.

 

Output

The JSON output contains the report of the specified URL.

Following image displays a sample output:

 

Sample output of the Get URL Report operation

 

operation: Get URL Behavior

Input parameters

 

Parameter Description
URL URL of the system for which you want to retrieve behavioral information.

 

Output

The JSON output contains the behavioral analysis of the specified URL.

Following image displays a sample output:

 

Sample output of the Get URL Behavior operation

 

operation: Get Relative Malware

Input parameters

 

Parameter Description
Family Name of the family based on which you want to retrieve all related active malware.

 

Output

The JSON output contains the all related active malware of the specified family.

Following image displays a sample output:

 

Sample output of the Get Relative Malware operation

 

operation: Get File Reputation using FileHash

Input parameters

 

Parameter Description
File Hash Single file hash or a list of file hash based on which you want to retrieve the reputation of a file.
File hash supported format md5, sha1, and sha256.

 

Output

The JSON output contains a report of the provided file based on the specified file hash.

Following image displays a sample output:

 

Sample output of the Get File Reputation using FileHash operation

 

operation: Get IP Registrant

Input parameters

 

Parameter Description
Host Hostname, IP address, or URL of the system for which you want to retrieve registrant details.

 

Output

The JSON output contains the registrant details of the specified host.

Following image displays a sample output:

 

Sample output of the Get IP Registrant operation

 

operation: Search Signature

Input parameters

 

Parameter Description
Query String Search term based on which you want to search for a signature.

 

Output

The JSON output contains a list of signatures associated with the specified search term.

Following image displays a sample output:

 

Sample output of the Search Signature operation

 

operation: Search Signature by XPU

Input parameters

 

Parameter Description
XPU XPU name based on which you want to search for a signature.

 

Output

The JSON output contains a list of signatures associated with the specified XPU.

Following image displays a sample output:

 

Sample output of the Search Signature by XPU operation

 

operation: Search Signature by PAMID

Input parameters

 

Parameter Description
PAMID PAMID based on which you want to search for a signature.

 

Output

The JSON output contains a list of signatures associated with the specified PAMID.

Following image displays a sample output:

 

Sample output of the Search Signature by PAMID operation

 

operation: Get DNS Record

Input parameters

 

Parameter Description
Query IP address, Domain, or URL based on which you want to search for DNS information.

 

Output

The JSON output contains the DNS information associated with the specified IP address, Domain or URL.

Following image displays a sample output:

 

Sample output of the Get DNS Record operation

 

operation: Get Vulnerability from XFID

Input parameters

 

Parameter Description
xfid XFID based on which retrieve a vulnerability list.

 

Output

The JSON output contains a list of vulnerabilities associated with the specified XFID.

Following image displays a sample output:

 

Sample output of the Get Vulnerability from XFID operation

 

operation: Get Vulnerability from STDCODE

Input parameters

 

Parameter Description
STDCODE STDCODE number based on which retrieve a vulnerability list.

 

Output

The JSON output contains a list of vulnerabilities associated with the specified STDCODE.

Following image displays a sample output:

 

Sample output of the Get Vulnerability from STDCODE operation

 

operation: Get Vulnerability

Input parameters

 

Parameter Description
query Search term based on which retrieve a vulnerability list.
For example, Heartbleed is used for searching for vulnerabilities based on affected platforms.
Start date Start of the daterange from which you want to search for vulnerabilities.
End date End of the daterange till when you want to search for vulnerabilities.
bookmark Bookmark used to page through the results

 

Output

The JSON output contains a list of vulnerabilities associated with the specified search term.

Following image displays a sample output:

 

Sample output of the Get Vulnerability operation

 

Included playbooks

The Sample-IBM XForce-1.0.1 playbook collection comes bundled with the IBM XForce connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the IBM XForce connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

 

Troubleshooting

Connection refusal while requesting to run the wrapper

This generally occurs in the case of self-signed SSL certificates. If you are using self-signed certificates for testing or staging, keep in mind this problem will not occur in production and you might need to switch the certificates on or off.

Resolution:

Ensure that the SSL certificates are trusted or that SSL checking is turned off in the wrapper script. This is not advised for production instances.

Playbook fails after the ingestion is triggered

There are many reasons for a playbook failure, for example, if a required field is null in the target module record, or there are problems with the Playbook Appliance keys.

Resolution:

Investigate the reason for failure using the Running Playbooks tab in the Playbook Administration page. Review the step in which the failure is being generated and the result of the step, which should contain the trace of the error. Once you have identified the error and if you cannot troubleshoot the error, contact Fortinet support for further assistance.