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.
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
Following enhancements have been made to the XForce Connector in version 1.0.1:
api.xforce.ibmcloud.com
format.Important: When you upgrade the IBM XForce connector from version 1.0.0 to 1.0.1, the 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.
For the procedure to install a connector, click here.
For the procedure to configure a connector, click here.
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. |
The following automated operations can be included in playbooks and you can also use the annotations to access operations:
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 | 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 |
Parameter | Description |
---|---|
IP | IP address of the system for which you want to retrieve reputation information. |
The JSON output contains the reputation with the score and other details of the specified IP address.
The output contains the following populated JSON schema:
{
"ip": "",
"history": []
}
Parameter | Description |
---|---|
IP | IP address of the system for which you want to retrieve behavioral information. |
The JSON output contains the behavioral analysis of the specified IP address.
The output contains the following populated JSON schema:
{
"malware": [
{
"family": [
""
],
"first": "",
"last": "",
"md5": "",
"origin": "",
"uri": ""
}
]
}
Parameter | Description |
---|---|
IP | IP address of the system for which you want to generate the report. |
The JSON output contains the report of the specified IP address.
The output contains the following populated JSON schema:
{
"ip": "",
"subnets": [],
"cats": {},
"geo": {
"country": "",
"countrycode": ""
},
"score": 0,
"tags": []
}
Parameter | Description |
---|---|
URL | URL of the system for which you want to generate the report. |
The JSON output contains the report of the specified URL.
The output contains the following populated JSON schema:
{
"result": {
"url": "",
"cats": {},
"categoryDescriptions": {},
"score": 0
},
"associated": [],
"tags": []
}
Parameter | Description |
---|---|
URL | URL of the system for which you want to retrieve behavioral information. |
The JSON output contains the behavioral analysis of the specified URL.
The output contains the following populated JSON schema:
{
"count": 0,
"malware": []
}
Parameter | Description |
---|---|
Family | Name of the family based on which you want to retrieve all related active malware. |
The JSON output contains the all related active malware of the specified family.
The output contains the following populated JSON schema:
{
"tags": [],
"count": 0,
"family": [],
"firstseen": "",
"lastseen": "",
"malware": []
}
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. |
The JSON output contains a report of the provided file based on the specified file hash.
The output contains the following populated JSON schema:
{
"malware": {
"created": "",
"type": "",
"family": [],
"familyMembers": {},
"md5": "",
"mimetype": "",
"origins": {
"CnCServers": {},
"downloadServers": {},
"emails": {},
"external": {},
"subjects": {}
},
"risk": ""
},
"tags": []
}
Parameter | Description |
---|---|
Host | Hostname, IP address, or URL of the system for which you want to retrieve registrant details. |
The JSON output contains the registrant details of the specified host.
The output contains the following populated JSON schema:
{
"createdDate": "",
"updatedDate": "",
"netRange": "",
"contact": [],
"extended": {}
}
Parameter | Description |
---|---|
Query String | Search term based on which you want to search for a signature. |
The JSON output contains a list of signatures associated with the specified search term.
The output contains the following populated JSON schema:
{
"total_rows": 0,
"bookmark": "",
"rows": []
}
Parameter | Description |
---|---|
XPU | XPU name based on which you want to search for a signature. |
The JSON output contains a list of signatures associated with the specified XPU.
The output contains the following populated JSON schema:
{
"rows": [
{
"type": "PAM",
"priority": 0,
"pamid": "",
"releaseDate": "",
"shortDesc": "",
"pamName": ""
}
]
}
Parameter | Description |
---|---|
PAMID | PAMID based on which you want to search for a signature. |
The JSON output contains a list of signatures associated with the specified PAMID.
The output contains the following populated JSON schema:
{
"type": "PAM",
"pamid": "",
"updated": true,
"releaseDate": "",
"shortDesc": "",
"pamName": "",
"description": "",
"priority": 0,
"category": "",
"products_containing": [],
"protects_against": {},
"covers": {}
}
Parameter | Description |
---|---|
Query | IP address, Domain, or URL based on which you want to search for DNS information. |
The JSON output contains the DNS information associated with the specified IP address, Domain or URL.
The output contains the following populated JSON schema:
{
"A": [],
"AAAA": [],
"MX": {},
"TXT": [],
"RDNS": [],
"Passive": {}
}
Parameter | Description |
---|---|
xfid | XFID based on which retrieve a vulnerability list. |
The JSON output contains a list of vulnerabilities associated with the specified XFID.
The output contains the following populated JSON schema:
{
"tags": [],
"type": "",
"xfdbid": 0,
"updateid": 0,
"updated": true,
"variant": "",
"title": "",
"description": "",
"description_fmt": "",
"risk_level": 0,
"CVSS3_Version": "",
"CVSS3_PrivilegesRequired": "",
"CVSS3_UserInteraction": "",
"CVSS3_Scope": "",
"access_vector": "",
"access_complexity": "",
"confidentiality_impact": "",
"integrity_impact": "",
"availability_impact": "",
"temporal_score": 0,
"remediation_level": "",
"remedy": "",
"remedy_fmt": "",
"reported": "",
"tagname": "",
"stdcode": [],
"platforms_affected": [],
"exploitability": "",
"consequences": "",
"references": [],
"report_confidence": ""
}
Parameter | Description |
---|---|
STDCODE | STDCODE number based on which retrieve a vulnerability list. |
The JSON output contains a list of vulnerabilities associated with the specified STDCODE.
The output contains the following populated JSON schema:
{
"type": "",
"xfdbid": 0,
"updateid": 0,
"updated": true,
"variant": "",
"title": "",
"description": "",
"description_fmt": "",
"risk_level": 0,
"CVSS3_Version": "",
"CVSS3_PrivilegesRequired": "",
"CVSS3_UserInteraction": "",
"CVSS3_Scope": "",
"access_vector": "",
"access_complexity": "",
"confidentiality_impact": "",
"integrity_impact": "",
"availability_impact": "",
"temporal_score": 0,
"remediation_level": "",
"remedy": "",
"remedy_fmt": "",
"reported": "",
"tagname": "",
"stdcode": [],
"platforms_affected": [],
"exploitability": "",
"consequences": "",
"references": [],
"report_confidence": ""
}
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 |
The JSON output contains a list of vulnerabilities associated with the specified search term.
The output contains the following populated JSON schema:
{
"total_rows": 0,
"bookmark": "",
"rows": []
}
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.
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.
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.
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.
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
Following enhancements have been made to the XForce Connector in version 1.0.1:
api.xforce.ibmcloud.com
format.Important: When you upgrade the IBM XForce connector from version 1.0.0 to 1.0.1, the 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.
For the procedure to install a connector, click here.
For the procedure to configure a connector, click here.
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. |
The following automated operations can be included in playbooks and you can also use the annotations to access operations:
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 | 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 |
Parameter | Description |
---|---|
IP | IP address of the system for which you want to retrieve reputation information. |
The JSON output contains the reputation with the score and other details of the specified IP address.
The output contains the following populated JSON schema:
{
"ip": "",
"history": []
}
Parameter | Description |
---|---|
IP | IP address of the system for which you want to retrieve behavioral information. |
The JSON output contains the behavioral analysis of the specified IP address.
The output contains the following populated JSON schema:
{
"malware": [
{
"family": [
""
],
"first": "",
"last": "",
"md5": "",
"origin": "",
"uri": ""
}
]
}
Parameter | Description |
---|---|
IP | IP address of the system for which you want to generate the report. |
The JSON output contains the report of the specified IP address.
The output contains the following populated JSON schema:
{
"ip": "",
"subnets": [],
"cats": {},
"geo": {
"country": "",
"countrycode": ""
},
"score": 0,
"tags": []
}
Parameter | Description |
---|---|
URL | URL of the system for which you want to generate the report. |
The JSON output contains the report of the specified URL.
The output contains the following populated JSON schema:
{
"result": {
"url": "",
"cats": {},
"categoryDescriptions": {},
"score": 0
},
"associated": [],
"tags": []
}
Parameter | Description |
---|---|
URL | URL of the system for which you want to retrieve behavioral information. |
The JSON output contains the behavioral analysis of the specified URL.
The output contains the following populated JSON schema:
{
"count": 0,
"malware": []
}
Parameter | Description |
---|---|
Family | Name of the family based on which you want to retrieve all related active malware. |
The JSON output contains the all related active malware of the specified family.
The output contains the following populated JSON schema:
{
"tags": [],
"count": 0,
"family": [],
"firstseen": "",
"lastseen": "",
"malware": []
}
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. |
The JSON output contains a report of the provided file based on the specified file hash.
The output contains the following populated JSON schema:
{
"malware": {
"created": "",
"type": "",
"family": [],
"familyMembers": {},
"md5": "",
"mimetype": "",
"origins": {
"CnCServers": {},
"downloadServers": {},
"emails": {},
"external": {},
"subjects": {}
},
"risk": ""
},
"tags": []
}
Parameter | Description |
---|---|
Host | Hostname, IP address, or URL of the system for which you want to retrieve registrant details. |
The JSON output contains the registrant details of the specified host.
The output contains the following populated JSON schema:
{
"createdDate": "",
"updatedDate": "",
"netRange": "",
"contact": [],
"extended": {}
}
Parameter | Description |
---|---|
Query String | Search term based on which you want to search for a signature. |
The JSON output contains a list of signatures associated with the specified search term.
The output contains the following populated JSON schema:
{
"total_rows": 0,
"bookmark": "",
"rows": []
}
Parameter | Description |
---|---|
XPU | XPU name based on which you want to search for a signature. |
The JSON output contains a list of signatures associated with the specified XPU.
The output contains the following populated JSON schema:
{
"rows": [
{
"type": "PAM",
"priority": 0,
"pamid": "",
"releaseDate": "",
"shortDesc": "",
"pamName": ""
}
]
}
Parameter | Description |
---|---|
PAMID | PAMID based on which you want to search for a signature. |
The JSON output contains a list of signatures associated with the specified PAMID.
The output contains the following populated JSON schema:
{
"type": "PAM",
"pamid": "",
"updated": true,
"releaseDate": "",
"shortDesc": "",
"pamName": "",
"description": "",
"priority": 0,
"category": "",
"products_containing": [],
"protects_against": {},
"covers": {}
}
Parameter | Description |
---|---|
Query | IP address, Domain, or URL based on which you want to search for DNS information. |
The JSON output contains the DNS information associated with the specified IP address, Domain or URL.
The output contains the following populated JSON schema:
{
"A": [],
"AAAA": [],
"MX": {},
"TXT": [],
"RDNS": [],
"Passive": {}
}
Parameter | Description |
---|---|
xfid | XFID based on which retrieve a vulnerability list. |
The JSON output contains a list of vulnerabilities associated with the specified XFID.
The output contains the following populated JSON schema:
{
"tags": [],
"type": "",
"xfdbid": 0,
"updateid": 0,
"updated": true,
"variant": "",
"title": "",
"description": "",
"description_fmt": "",
"risk_level": 0,
"CVSS3_Version": "",
"CVSS3_PrivilegesRequired": "",
"CVSS3_UserInteraction": "",
"CVSS3_Scope": "",
"access_vector": "",
"access_complexity": "",
"confidentiality_impact": "",
"integrity_impact": "",
"availability_impact": "",
"temporal_score": 0,
"remediation_level": "",
"remedy": "",
"remedy_fmt": "",
"reported": "",
"tagname": "",
"stdcode": [],
"platforms_affected": [],
"exploitability": "",
"consequences": "",
"references": [],
"report_confidence": ""
}
Parameter | Description |
---|---|
STDCODE | STDCODE number based on which retrieve a vulnerability list. |
The JSON output contains a list of vulnerabilities associated with the specified STDCODE.
The output contains the following populated JSON schema:
{
"type": "",
"xfdbid": 0,
"updateid": 0,
"updated": true,
"variant": "",
"title": "",
"description": "",
"description_fmt": "",
"risk_level": 0,
"CVSS3_Version": "",
"CVSS3_PrivilegesRequired": "",
"CVSS3_UserInteraction": "",
"CVSS3_Scope": "",
"access_vector": "",
"access_complexity": "",
"confidentiality_impact": "",
"integrity_impact": "",
"availability_impact": "",
"temporal_score": 0,
"remediation_level": "",
"remedy": "",
"remedy_fmt": "",
"reported": "",
"tagname": "",
"stdcode": [],
"platforms_affected": [],
"exploitability": "",
"consequences": "",
"references": [],
"report_confidence": ""
}
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 |
The JSON output contains a list of vulnerabilities associated with the specified search term.
The output contains the following populated JSON schema:
{
"total_rows": 0,
"bookmark": "",
"rows": []
}
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.
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.
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.