DOCUMENT LIBRARY
1.0.1
DOCUMENT LIBRARY
1.0.1
IPStack searches for the geolocation facility of a specified IP address or Domain.
This document provides information about the IPStack connector, which facilitates automated interactions, with an IPStack server using FortiSOAR™ playbooks. Add the IPStack connector as a step in FortiSOAR™ playbooks and perform automated operations such as searching and retrieving geolocation locations for a specified IP address or Domain.
Connector Version: 1.0.1
FortiSOAR™ Version Tested on: 7.2.1-1021
IPStack Version Tested on: 3.0
Authored By: Fortinet
Certified: Yes
Following enhancements have been made to the IPStack Connector in version 1.0.1:
For more information, see the Pluggable Enrichment topic
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-ipstack
For the procedure to configure a connector, click here.
In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the IPStack connector card. On the connector popup, click the Configurations tab to enter the required configuration details:
| Parameter | Description |
|---|---|
| Server URL | URL of the IPStack server to which you will connect and perform the automated operations. |
| API Key | API key configured for your account to access the IPStack server |
| The protocol used to communicate, choose either http or https. By default, this is set to http. |
|
| Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as 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 |
|---|---|---|
| Geolocate IP | Retrieves the geolocation details of the IP address that you specify from the IPStack server. | geolocation Investigation |
| Geolocate IP | Retrieves the geolocation details of the domain that you specify from the IPStack server. | geolocation Investigation |
| Parameter | Description |
|---|---|
| IP Address | The IP address for which you want to retrieve geolocation details from the IPStack server. |
| Specify Response Fields | (Optional) Use this parameter to limit results returned by this operation to a certain object or set of objects. For example, If you specify country_code then this operation returns only the country_code object instead of returning the entire result. |
| Enable Hostname Lookup | Select this option (i.e. set to True) if you want to retrieve the hostname with your API response.By default, this is set to False. |
| Enable Security Module | Select this option (i.e. set to True) if you want to retrieve security information with your API response.By default, this is set to False. |
The JSON output contains the geolocation details of the IP address that you have specified retrieved from the IPStack server.
The output contains the following populated JSON schema:
{
"zip": "",
"latitude": "",
"longitude": "",
"country_code": "",
"country_name": "",
"city": "",
"continent_code": "",
"continent_name": "",
"region_code": "",
"region_name": "",
"type": "",
"ip": "",
"location": {
"geoname_id": "",
"calling_code": "",
"is_eu": "",
"capital": "",
"country_flag": "",
"country_flag_emoji_unicode": "",
"country_flag_emoji": "",
"languages": [
{
"name": "",
"code": "",
"native": ""
}
]
}
}
| Parameter | Description |
|---|---|
| IP Address | Name of the domain for which you want to retrieve geolocation details from the IPStack server. Important: Do not prefix the domain name with http, https, or www. |
| Specify Response Fields | (Optional) Use this parameter to limit results returned by this operation to a certain object or set of objects. For example, If you specify country_code then this operation returns only the country_code object instead of returning the entire result. |
| Enable Hostname Lookup | Select this option (i.e. set to True) if you want to retrieve the hostname with your API response.By default, this is set to False. |
| Enable Security Module | Select this option (i.e. set to True) if you want to retrieve security information with your API response.By default, this is set to False. |
The JSON output contains the geolocation details of the domain name that you have specified retrieved from the IPStack server.
The output contains the following populated JSON schema:
{
"zip": "",
"latitude": "",
"longitude": "",
"country_code": "",
"country_name": "",
"city": "",
"continent_code": "",
"continent_name": "",
"region_code": "",
"region_name": "",
"type": "",
"ip": "",
"location": {
"geoname_id": "",
"calling_code": "",
"is_eu": "",
"capital": "",
"country_flag": "",
"country_flag_emoji_unicode": "",
"country_flag_emoji": "",
"languages": [
{
"name": "",
"code": "",
"native": ""
}
]
}
}
The Sample - IPStack - 1.0.1 playbook collection comes bundled with the IPStack 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 IPStack 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 the connector upgrade and delete.
The Sample - IPStack - 1.0.1 playbook collection contains pluggable enrichment playbooks that are used to provide verdicts for indicator types IP address and Domain. The pluggable enrichment playbooks are in the format: '<indicator type> > IP Stack > Geolocation'. For example, 'IP > IP Stack > Geolocation'.
Based on the IP Stack integration API response following variables are returned:
| Variable Name | Description | Return Value |
|---|---|---|
cti_name |
The name of the connector is called the CTI (Cyber Threat Intelligence) name | IPStack |
source_data |
The source_data response returned by the integration API. | A JSON response object containing the source data of the threat intelligence integration. |
enrichment_summary |
The contents that are added, in the HTML format, in the 'Description' field of the specified FortiSOAR indicator record. |
The following values are returned in the HTML format:
The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record:  |
IPStack searches for the geolocation facility of a specified IP address or Domain.
This document provides information about the IPStack connector, which facilitates automated interactions, with an IPStack server using FortiSOAR™ playbooks. Add the IPStack connector as a step in FortiSOAR™ playbooks and perform automated operations such as searching and retrieving geolocation locations for a specified IP address or Domain.
Connector Version: 1.0.1
FortiSOAR™ Version Tested on: 7.2.1-1021
IPStack Version Tested on: 3.0
Authored By: Fortinet
Certified: Yes
Following enhancements have been made to the IPStack Connector in version 1.0.1:
For more information, see the Pluggable Enrichment topic
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-ipstack
For the procedure to configure a connector, click here.
In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the IPStack connector card. On the connector popup, click the Configurations tab to enter the required configuration details:
| Parameter | Description |
|---|---|
| Server URL | URL of the IPStack server to which you will connect and perform the automated operations. |
| API Key | API key configured for your account to access the IPStack server |
| The protocol used to communicate, choose either http or https. By default, this is set to http. |
|
| Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as 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 |
|---|---|---|
| Geolocate IP | Retrieves the geolocation details of the IP address that you specify from the IPStack server. | geolocation Investigation |
| Geolocate IP | Retrieves the geolocation details of the domain that you specify from the IPStack server. | geolocation Investigation |
| Parameter | Description |
|---|---|
| IP Address | The IP address for which you want to retrieve geolocation details from the IPStack server. |
| Specify Response Fields | (Optional) Use this parameter to limit results returned by this operation to a certain object or set of objects. For example, If you specify country_code then this operation returns only the country_code object instead of returning the entire result. |
| Enable Hostname Lookup | Select this option (i.e. set to True) if you want to retrieve the hostname with your API response.By default, this is set to False. |
| Enable Security Module | Select this option (i.e. set to True) if you want to retrieve security information with your API response.By default, this is set to False. |
The JSON output contains the geolocation details of the IP address that you have specified retrieved from the IPStack server.
The output contains the following populated JSON schema:
{
"zip": "",
"latitude": "",
"longitude": "",
"country_code": "",
"country_name": "",
"city": "",
"continent_code": "",
"continent_name": "",
"region_code": "",
"region_name": "",
"type": "",
"ip": "",
"location": {
"geoname_id": "",
"calling_code": "",
"is_eu": "",
"capital": "",
"country_flag": "",
"country_flag_emoji_unicode": "",
"country_flag_emoji": "",
"languages": [
{
"name": "",
"code": "",
"native": ""
}
]
}
}
| Parameter | Description |
|---|---|
| IP Address | Name of the domain for which you want to retrieve geolocation details from the IPStack server. Important: Do not prefix the domain name with http, https, or www. |
| Specify Response Fields | (Optional) Use this parameter to limit results returned by this operation to a certain object or set of objects. For example, If you specify country_code then this operation returns only the country_code object instead of returning the entire result. |
| Enable Hostname Lookup | Select this option (i.e. set to True) if you want to retrieve the hostname with your API response.By default, this is set to False. |
| Enable Security Module | Select this option (i.e. set to True) if you want to retrieve security information with your API response.By default, this is set to False. |
The JSON output contains the geolocation details of the domain name that you have specified retrieved from the IPStack server.
The output contains the following populated JSON schema:
{
"zip": "",
"latitude": "",
"longitude": "",
"country_code": "",
"country_name": "",
"city": "",
"continent_code": "",
"continent_name": "",
"region_code": "",
"region_name": "",
"type": "",
"ip": "",
"location": {
"geoname_id": "",
"calling_code": "",
"is_eu": "",
"capital": "",
"country_flag": "",
"country_flag_emoji_unicode": "",
"country_flag_emoji": "",
"languages": [
{
"name": "",
"code": "",
"native": ""
}
]
}
}
The Sample - IPStack - 1.0.1 playbook collection comes bundled with the IPStack 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 IPStack 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 the connector upgrade and delete.
The Sample - IPStack - 1.0.1 playbook collection contains pluggable enrichment playbooks that are used to provide verdicts for indicator types IP address and Domain. The pluggable enrichment playbooks are in the format: '<indicator type> > IP Stack > Geolocation'. For example, 'IP > IP Stack > Geolocation'.
Based on the IP Stack integration API response following variables are returned:
| Variable Name | Description | Return Value |
|---|---|---|
cti_name |
The name of the connector is called the CTI (Cyber Threat Intelligence) name | IPStack |
source_data |
The source_data response returned by the integration API. | A JSON response object containing the source data of the threat intelligence integration. |
enrichment_summary |
The contents that are added, in the HTML format, in the 'Description' field of the specified FortiSOAR indicator record. |
The following values are returned in the HTML format:
The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record: |