Fortinet white logo
Fortinet white logo

IP Quality Score

1.0.1

IP Quality Score v1.0.1

About the connector

The IPQualityScore (IPQS) Threat Intelligence application provides threat intelligence for IP addresses, email addresses, URLs, and domains.

This document provides information about the IP Quality Score Connector, which facilitates automated interactions, with an IP Quality Score server using FortiSOAR™ playbooks. Add the IP Quality Score connector as a step in FortiSOAR™ playbooks and perform automated operations with IP Quality Score.

Version information

Connector Version: 1.0.1

FortiSOAR™ Version Tested on: 7.2.1-1021

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.0.1

Following enhancements have been made to the IP Quality Score Connector in version 1.0.1:

  • Added the following pluggable enrichment playbooks that automatically enrich data when you install and configure the IP Quality Score:
    • IP Address > IP Quality Score > Enrichment
    • Email Address > IP Quality Score > Enrichment
    • URL > IP Quality Scored > Enrichment
      For more information, see the Pluggable Enrichment topic.

Installing the connector

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-ip-quality-score

Prerequisites to configuring the connector

  • You must have the URL of the IP Quality Score server to which you will connect and perform automated operations and the private key used to access that server.
  • The FortiSOAR™ server should have outbound connectivity to port 443 on the IP Quality Score server.

Minimum Permissions Required

  • Not applicable

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the IP Quality Score connector card. On the connector popup, click the Configurations tab to enter the required configuration details.

Parameter Description
Server URL The URL of the IPQualityScore server to which you will connect and perform the automated operations.
Private Key The private key used to access the IPQualityScore server to which you will connect and perform the automated operations.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as 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:

Function Description Annotation and Category
Get IP Reputation Retrieves the reputation of the submitted IP address from IPQualityScore based on the IP address and other input parameters you have specified. get_ip_reputation
Investigation
Get Email Reputation Retrieves the reputation of the submitted email address from IPQualityScore based on the email address and other input parameters you have specified. get_email_reputation
Investigation
Get URL Reputation Retrieves the reputation of the submitted URL from IPQualityScore based on the URL and other input parameters you have specified. get_url_reputation
Investigation

operation: Get IP Reputation

Input parameters

Parameter Description
IP Address Specify the IP address whose reputation you want to retrieve from IPQualityScore.
Strictness (Optional) Select the level of strictness you want to apply while retrieving the IP reputation. Stricter checks might lead to a higher false-positive rate. Therefore, it is recommended to set the strictness to level '0', the lowest strictness setting, and then increase it to '1' or '2' depending on your levels of fraud.
User Agent (Optional) Specify a value in this parameter so that IPQualityScore can run additional checks to see if the user is a bot or running an invalid browser. This allows IPQualityScore to evaluate the risk of the user as judged in the "fraud_score".
User Language (Optional) Specify a value in this parameter so that IPQualityScore can evaluate the risk of the user as judged in the "fraud_score".
Fast Select the 'Fast' parameter to greatly increases the API speed without much impact on accuracy. This option is intended for services that require quick decisions and can be used for any strictness level. In this case, our API does not perform certain forensic checks that take longer to process.
Mobile Select the 'Mobile' parameter (recommended) for mobile lookups that do not have a user agent attached to the request.
Allow Public Access Points Select the 'Allow Public Access Points' parameter to bypass certain checks for IP addresses from education and research institutions, schools, and some corporate connections to better accommodate audiences that frequently use public connections.
Lighter Penalties Select the 'Lighter Penalties' parameter to lower detection rates and Fraud Scores for mixed-quality IP addresses. If you experience any false positives with your traffic, then enabling this option provides better results.
Transaction Strictness (Optional) Select the level of transaction strictness you want to apply while retrieving the IP reputation. This parameter adjusts the weights for penalties applied due to irregularities and fraudulent patterns detected on order and transaction details that can be optionally provided on each API request. This option is beneficial only if you are passing order and transaction details.

Output

The output contains the following populated JSON schema:
{
"success": "",
"message": "",
"fraud_score": "",
"country_code": "",
"region": "",
"city": "",
"ISP": "",
"ASN": "",
"organization": "",
"is_crawler": "",
"timezone": "",
"mobile": "",
"host": "",
"proxy": "",
"vpn": "",
"tor": "",
"active_vpn": "",
"active_tor": "",
"recent_abuse": "",
"bot_status": "",
"connection_type": "",
"abuse_velocity": "",
"zip_code": "",
"latitude": "",
"longitude": "",
"request_id": ""
}

operation: Get Email Reputation

Input parameters

Parameter Description
Email Address Specify the email address whose reputation you want to retrieve from IPQualityScore.
Fast Select the 'Fast' parameter to greatly increases the API speed. In this case, our API does not perform an SMTP check with the mail service provider, which greatly increases the API speed.
Timeout Specify the timeout value in seconds. The IP Quality Score connector provides better accuracy if response time is not an issue. You can specify the timeout value between 1 and 60. The default timeout is set at 7 seconds.
Suggest Domain Select this option to force analysis if the domain of the specified email address has a typo and should be corrected to a popular mail service. By default, this test is currently only performed when the email is invalid or if the "recent abuse" status is true.
Strictness (Optional) Select the level of strictness you want to apply while retrieving the email reputation. This parameter sets how strictly spam traps and honeypots are detected by our system, depending on how comfortable you are with identifying emails suspected of being a spam trap. '0' is the lowest level, which only returns spam traps with high confidence. Strictness levels above '0' return increasingly more strict results, with level '2' providing the greatest detection rates.
Abuse Strictness (Optional) Select the level of strictness for machine learning pattern recognition of abusive email addresses with the "recent_abuse" data point. The default level of '0' provides good coverage; however, if you are filtering account applications and facing advanced fraudsters, then we recommend increasing this value to level '1' or '2'.

Output

The output contains the following populated JSON schema:
{
"message": "",
"success": "",
"valid": "",
"disposable": "",
"smtp_score": "",
"overall_score": "",
"first_name": "",
"generic": "",
"common": "",
"dns_valid": "",
"honeypot": "",
"deliverability": "",
"frequent_complainer": "",
"spam_trap_score": "",
"catch_all": "",
"timed_out": "",
"suspect": "",
"recent_abuse": "",
"fraud_score": "",
"suggested_domain": "",
"leaked": "",
"domain_age": {
"human": "",
"timestamp": "",
"iso": ""
},
"first_seen": {
"human": "",
"timestamp": "",
"iso": ""
},
"sanitized_email": "",
"domain_velocity": "",
"user_activity": "",
"associated_names": {
"status": "",
"names": []
},
"associated_phone_numbers": {
"status": "",
"phone_numbers": []
},
"request_id": ""
}

operation: Get URL Reputation

Input parameters

Parameter Description
URL Specify the URL whose reputation you want to retrieve from IPQualityScore.
Strictness (Optional) Select the level of strictness you want to apply while retrieving the URL reputation. Stricter checks might lead to a higher false-positive rate. Therefore, it is recommended to set the strictness to level '0', the lowest strictness setting, and then increase it to '1' or '2' depending on your levels of abuse.
Fast Select the 'Fast' parameter to greatly increases the API speed and provide quicker response times using lighter checks and analysis.

Output

The output contains the following populated JSON schema:
{
"message": "",
"success": "",
"unsafe": "",
"domain": "",
"ip_address": "",
"server": "",
"content_type": "",
"status_code": "",
"page_size": "",
"domain_rank": "",
"dns_valid": "",
"parking": "",
"spamming": "",
"malware": "",
"phishing": "",
"suspicious": "",
"adult": "",
"risk_score": "",
"category": "",
"domain_age": {
"human": "",
"timestamp": "",
"iso": ""
},
"request_id": ""
}

Included playbooks

The Sample - IP Quality Score - 1.0.1 playbook collection comes bundled with the IP Quality Score connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the IP Quality Score connector.

  • Email Address > IP Quality Score > Enrichment
  • Get Email Reputation
  • Get IP Reputation
  • Get URL Reputation
  • IP Address > IP Quality Score > Enrichment
  • URL > IP Quality Scored > Enrichment

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.

Pluggable Enrichment

The Sample - IP Quality Score - 1.0.1 playbook collection contains pluggable enrichment playbooks that are used to provide verdicts for various indicator types. The indicator can be of any of the following types: IP address, URL, or email address. The pluggable enrichment playbooks are in the format: '<indicator type> > IP Quality Score > Enrichment'. For example, 'URL > IP Quality Score > Enrichment'.

The 'Configuration' step in all the pluggable enrichment playbooks contains variables that have default values for calculating the 'Verdict' for various indicator types.

Default variables for indicator type 'IP'

The following table lists the variable names and their default values for the 'IP Address > IP Quality Score > Enrichment' playbook:

Variable Name Default value (fraud_score)
good_score 0
suspicious_score 87-1
malicious_score 100-88
NOTE: The range of default values must be in the <Upper Bound>-<Lower Bound> format, For example, 87-1

Based on the above default values and the IP Quality Score integration API response returns the verdict, cti_score, and enrichment_summary for the indicator of type 'IP' (all the other variables are common, which is listed in the Common Variable Table):

Variable Name Description Return Value
verdict This connector returns a high-reliability value called verdict. Use this verdict to find the reputation of the IP type of indicator.

If the fraud_score value returned is between the value specified in the malicious_score variable, then return the verdict as Malicious.
If the fraud_score value returned is between the value specified in the suspicious_score variable, then return the verdict as Suspicious.
If the fraud_score value returned is between the value specified in the good_score variable, then return the verdict as Good.
For any other value, return the verdict as No Reputation Available

cti_score The verdict value returned by the integration API. fraud_score
enrichment_summary The contents 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:

  • Fraud Score
  • Recent Abuse
  • Proxy
  • TOR
  • VPN

The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record:

Default variables for indicator type 'URL'

The following table lists the variable names and their default values for the 'URL > IP Quality Score > Enrichment' playbook:

Variable Name Default value (risk_score)
good_score 0
suspicious_score 99-1
malicious_score 100
NOTE: The range of default values must be in the <Upper Bound>-<Lower Bound> format, For example, 99-1

Based on the above default values and the IP Quality Score integration API response returns the verdict, cti_score, and enrichment_summary for the indicator of type 'URL' (all the other variables are common, which is listed in the Common Variable Table):

Variable Name Description Return Value
verdict This connector returns a high-reliability value called 'verdict'. Use this verdict to find the reputation of the IP type of indicator.

If the risk_score value returned is between the value specified in the malicious_score variable, then return the verdict as Malicious.
If the risk_score value returned is between the value specified in the suspicious_score variable, then return the verdict as Suspicious.
If the risk_score value returned is between the value specified in the good_score variable, then return the verdict as Good.
For any other value, return the verdict as No Reputation Available

cti_score The verdict value returned by the integration API. risk_score
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:

  • Risk Score
  • Malware
  • Phishing
  • Spamming
  • Category

The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record:

Default variables for indicator type 'Email Address'

The following table lists the variable names and their default values for the 'Email Address > IP Quality Score > Enrichment' playbook:

Variable Name Default value (fraud_score)
good_score 0
suspicious_score 89-1
malicious_score 100-90
NOTE: The range of default values must be in the <Upper Bound>-<Lower Bound> format, For example, 89-1

Based on the above default values and the IP Quality Score integration API response returns the verdict, cti_score, and enrichment_summary for the indicator of type 'Email Address' (all the other variables are common, which is listed in the Common Variable Table):

Variable Name Description Return Value
verdict This connector returns a high-reliability value called 'verdict'. Use this verdict to find the reputation of the IP type of indicator. If the fraud_score value returned is between the value specified in the malicious_score variable, then return the verdict as Malicious.
If the fraud_score value returned is between the value specified in the suspicious_score variable, then return the verdict as Suspicious.
If the fraud_score value returned is between the value specified in the good_score variable, then return the verdict as Good.
For any other value, return the verdict as No Reputation Available
cti_score The verdict value returned by the integration API. fraud_score
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:

  • Fraud Score
  • Spam Trap Score
  • Leaked
  • Honeypot

The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record:

Common Variable Table

Variable Name Description Return Value
cti_name The name of the connector is called the CTI (Cyber Threat Intelligence) name IPQualityScore
source_data The source_data response returned by the integration API. A JSON response object containing the source data of the threat intelligence integration.
field_mapping The mapping of the FortiSOAR 'indicator' module fields with the IP Quality Score response fields. A JSON response object containing the field mapping of the threat intelligence integration.

Updating the value of the 'Verdict' parameter in the Pluggable Enrichment Playbooks

You can change the default values of the 'Verdict' parameter to suit your requirements as follows:

  1. Navigate to Automation > Playbooks > Sample - IP Quality Score - 1.0.1.
  2. Open the required playbook in the Playbook Designer.
    The pluggable enrichment playbooks are in the '<indicator type> > IP Quality Score > Enrichment' format. For example, URL > IP Quality Score > Enrichment.
  3. To customize the 'verdict', open the Configuration step, and edit the default values of any or all of the following variables:
    good_score
    suspicious_score
    malicious_score
    For example, you can change the value of the suspicious_score from 99-1 to 90-1.
Previous
Next

IP Quality Score v1.0.1

About the connector

The IPQualityScore (IPQS) Threat Intelligence application provides threat intelligence for IP addresses, email addresses, URLs, and domains.

This document provides information about the IP Quality Score Connector, which facilitates automated interactions, with an IP Quality Score server using FortiSOAR™ playbooks. Add the IP Quality Score connector as a step in FortiSOAR™ playbooks and perform automated operations with IP Quality Score.

Version information

Connector Version: 1.0.1

FortiSOAR™ Version Tested on: 7.2.1-1021

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.0.1

Following enhancements have been made to the IP Quality Score Connector in version 1.0.1:

Installing the connector

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-ip-quality-score

Prerequisites to configuring the connector

Minimum Permissions Required

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the IP Quality Score connector card. On the connector popup, click the Configurations tab to enter the required configuration details.

Parameter Description
Server URL The URL of the IPQualityScore server to which you will connect and perform the automated operations.
Private Key The private key used to access the IPQualityScore server to which you will connect and perform the automated operations.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as 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:

Function Description Annotation and Category
Get IP Reputation Retrieves the reputation of the submitted IP address from IPQualityScore based on the IP address and other input parameters you have specified. get_ip_reputation
Investigation
Get Email Reputation Retrieves the reputation of the submitted email address from IPQualityScore based on the email address and other input parameters you have specified. get_email_reputation
Investigation
Get URL Reputation Retrieves the reputation of the submitted URL from IPQualityScore based on the URL and other input parameters you have specified. get_url_reputation
Investigation

operation: Get IP Reputation

Input parameters

Parameter Description
IP Address Specify the IP address whose reputation you want to retrieve from IPQualityScore.
Strictness (Optional) Select the level of strictness you want to apply while retrieving the IP reputation. Stricter checks might lead to a higher false-positive rate. Therefore, it is recommended to set the strictness to level '0', the lowest strictness setting, and then increase it to '1' or '2' depending on your levels of fraud.
User Agent (Optional) Specify a value in this parameter so that IPQualityScore can run additional checks to see if the user is a bot or running an invalid browser. This allows IPQualityScore to evaluate the risk of the user as judged in the "fraud_score".
User Language (Optional) Specify a value in this parameter so that IPQualityScore can evaluate the risk of the user as judged in the "fraud_score".
Fast Select the 'Fast' parameter to greatly increases the API speed without much impact on accuracy. This option is intended for services that require quick decisions and can be used for any strictness level. In this case, our API does not perform certain forensic checks that take longer to process.
Mobile Select the 'Mobile' parameter (recommended) for mobile lookups that do not have a user agent attached to the request.
Allow Public Access Points Select the 'Allow Public Access Points' parameter to bypass certain checks for IP addresses from education and research institutions, schools, and some corporate connections to better accommodate audiences that frequently use public connections.
Lighter Penalties Select the 'Lighter Penalties' parameter to lower detection rates and Fraud Scores for mixed-quality IP addresses. If you experience any false positives with your traffic, then enabling this option provides better results.
Transaction Strictness (Optional) Select the level of transaction strictness you want to apply while retrieving the IP reputation. This parameter adjusts the weights for penalties applied due to irregularities and fraudulent patterns detected on order and transaction details that can be optionally provided on each API request. This option is beneficial only if you are passing order and transaction details.

Output

The output contains the following populated JSON schema:
{
"success": "",
"message": "",
"fraud_score": "",
"country_code": "",
"region": "",
"city": "",
"ISP": "",
"ASN": "",
"organization": "",
"is_crawler": "",
"timezone": "",
"mobile": "",
"host": "",
"proxy": "",
"vpn": "",
"tor": "",
"active_vpn": "",
"active_tor": "",
"recent_abuse": "",
"bot_status": "",
"connection_type": "",
"abuse_velocity": "",
"zip_code": "",
"latitude": "",
"longitude": "",
"request_id": ""
}

operation: Get Email Reputation

Input parameters

Parameter Description
Email Address Specify the email address whose reputation you want to retrieve from IPQualityScore.
Fast Select the 'Fast' parameter to greatly increases the API speed. In this case, our API does not perform an SMTP check with the mail service provider, which greatly increases the API speed.
Timeout Specify the timeout value in seconds. The IP Quality Score connector provides better accuracy if response time is not an issue. You can specify the timeout value between 1 and 60. The default timeout is set at 7 seconds.
Suggest Domain Select this option to force analysis if the domain of the specified email address has a typo and should be corrected to a popular mail service. By default, this test is currently only performed when the email is invalid or if the "recent abuse" status is true.
Strictness (Optional) Select the level of strictness you want to apply while retrieving the email reputation. This parameter sets how strictly spam traps and honeypots are detected by our system, depending on how comfortable you are with identifying emails suspected of being a spam trap. '0' is the lowest level, which only returns spam traps with high confidence. Strictness levels above '0' return increasingly more strict results, with level '2' providing the greatest detection rates.
Abuse Strictness (Optional) Select the level of strictness for machine learning pattern recognition of abusive email addresses with the "recent_abuse" data point. The default level of '0' provides good coverage; however, if you are filtering account applications and facing advanced fraudsters, then we recommend increasing this value to level '1' or '2'.

Output

The output contains the following populated JSON schema:
{
"message": "",
"success": "",
"valid": "",
"disposable": "",
"smtp_score": "",
"overall_score": "",
"first_name": "",
"generic": "",
"common": "",
"dns_valid": "",
"honeypot": "",
"deliverability": "",
"frequent_complainer": "",
"spam_trap_score": "",
"catch_all": "",
"timed_out": "",
"suspect": "",
"recent_abuse": "",
"fraud_score": "",
"suggested_domain": "",
"leaked": "",
"domain_age": {
"human": "",
"timestamp": "",
"iso": ""
},
"first_seen": {
"human": "",
"timestamp": "",
"iso": ""
},
"sanitized_email": "",
"domain_velocity": "",
"user_activity": "",
"associated_names": {
"status": "",
"names": []
},
"associated_phone_numbers": {
"status": "",
"phone_numbers": []
},
"request_id": ""
}

operation: Get URL Reputation

Input parameters

Parameter Description
URL Specify the URL whose reputation you want to retrieve from IPQualityScore.
Strictness (Optional) Select the level of strictness you want to apply while retrieving the URL reputation. Stricter checks might lead to a higher false-positive rate. Therefore, it is recommended to set the strictness to level '0', the lowest strictness setting, and then increase it to '1' or '2' depending on your levels of abuse.
Fast Select the 'Fast' parameter to greatly increases the API speed and provide quicker response times using lighter checks and analysis.

Output

The output contains the following populated JSON schema:
{
"message": "",
"success": "",
"unsafe": "",
"domain": "",
"ip_address": "",
"server": "",
"content_type": "",
"status_code": "",
"page_size": "",
"domain_rank": "",
"dns_valid": "",
"parking": "",
"spamming": "",
"malware": "",
"phishing": "",
"suspicious": "",
"adult": "",
"risk_score": "",
"category": "",
"domain_age": {
"human": "",
"timestamp": "",
"iso": ""
},
"request_id": ""
}

Included playbooks

The Sample - IP Quality Score - 1.0.1 playbook collection comes bundled with the IP Quality Score connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the IP Quality Score 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.

Pluggable Enrichment

The Sample - IP Quality Score - 1.0.1 playbook collection contains pluggable enrichment playbooks that are used to provide verdicts for various indicator types. The indicator can be of any of the following types: IP address, URL, or email address. The pluggable enrichment playbooks are in the format: '<indicator type> > IP Quality Score > Enrichment'. For example, 'URL > IP Quality Score > Enrichment'.

The 'Configuration' step in all the pluggable enrichment playbooks contains variables that have default values for calculating the 'Verdict' for various indicator types.

Default variables for indicator type 'IP'

The following table lists the variable names and their default values for the 'IP Address > IP Quality Score > Enrichment' playbook:

Variable Name Default value (fraud_score)
good_score 0
suspicious_score 87-1
malicious_score 100-88
NOTE: The range of default values must be in the <Upper Bound>-<Lower Bound> format, For example, 87-1

Based on the above default values and the IP Quality Score integration API response returns the verdict, cti_score, and enrichment_summary for the indicator of type 'IP' (all the other variables are common, which is listed in the Common Variable Table):

Variable Name Description Return Value
verdict This connector returns a high-reliability value called verdict. Use this verdict to find the reputation of the IP type of indicator.

If the fraud_score value returned is between the value specified in the malicious_score variable, then return the verdict as Malicious.
If the fraud_score value returned is between the value specified in the suspicious_score variable, then return the verdict as Suspicious.
If the fraud_score value returned is between the value specified in the good_score variable, then return the verdict as Good.
For any other value, return the verdict as No Reputation Available

cti_score The verdict value returned by the integration API. fraud_score
enrichment_summary The contents 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:

  • Fraud Score
  • Recent Abuse
  • Proxy
  • TOR
  • VPN

The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record:

Default variables for indicator type 'URL'

The following table lists the variable names and their default values for the 'URL > IP Quality Score > Enrichment' playbook:

Variable Name Default value (risk_score)
good_score 0
suspicious_score 99-1
malicious_score 100
NOTE: The range of default values must be in the <Upper Bound>-<Lower Bound> format, For example, 99-1

Based on the above default values and the IP Quality Score integration API response returns the verdict, cti_score, and enrichment_summary for the indicator of type 'URL' (all the other variables are common, which is listed in the Common Variable Table):

Variable Name Description Return Value
verdict This connector returns a high-reliability value called 'verdict'. Use this verdict to find the reputation of the IP type of indicator.

If the risk_score value returned is between the value specified in the malicious_score variable, then return the verdict as Malicious.
If the risk_score value returned is between the value specified in the suspicious_score variable, then return the verdict as Suspicious.
If the risk_score value returned is between the value specified in the good_score variable, then return the verdict as Good.
For any other value, return the verdict as No Reputation Available

cti_score The verdict value returned by the integration API. risk_score
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:

  • Risk Score
  • Malware
  • Phishing
  • Spamming
  • Category

The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record:

Default variables for indicator type 'Email Address'

The following table lists the variable names and their default values for the 'Email Address > IP Quality Score > Enrichment' playbook:

Variable Name Default value (fraud_score)
good_score 0
suspicious_score 89-1
malicious_score 100-90
NOTE: The range of default values must be in the <Upper Bound>-<Lower Bound> format, For example, 89-1

Based on the above default values and the IP Quality Score integration API response returns the verdict, cti_score, and enrichment_summary for the indicator of type 'Email Address' (all the other variables are common, which is listed in the Common Variable Table):

Variable Name Description Return Value
verdict This connector returns a high-reliability value called 'verdict'. Use this verdict to find the reputation of the IP type of indicator. If the fraud_score value returned is between the value specified in the malicious_score variable, then return the verdict as Malicious.
If the fraud_score value returned is between the value specified in the suspicious_score variable, then return the verdict as Suspicious.
If the fraud_score value returned is between the value specified in the good_score variable, then return the verdict as Good.
For any other value, return the verdict as No Reputation Available
cti_score The verdict value returned by the integration API. fraud_score
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:

  • Fraud Score
  • Spam Trap Score
  • Leaked
  • Honeypot

The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record:

Common Variable Table

Variable Name Description Return Value
cti_name The name of the connector is called the CTI (Cyber Threat Intelligence) name IPQualityScore
source_data The source_data response returned by the integration API. A JSON response object containing the source data of the threat intelligence integration.
field_mapping The mapping of the FortiSOAR 'indicator' module fields with the IP Quality Score response fields. A JSON response object containing the field mapping of the threat intelligence integration.

Updating the value of the 'Verdict' parameter in the Pluggable Enrichment Playbooks

You can change the default values of the 'Verdict' parameter to suit your requirements as follows:

  1. Navigate to Automation > Playbooks > Sample - IP Quality Score - 1.0.1.
  2. Open the required playbook in the Playbook Designer.
    The pluggable enrichment playbooks are in the '<indicator type> > IP Quality Score > Enrichment' format. For example, URL > IP Quality Score > Enrichment.
  3. To customize the 'verdict', open the Configuration step, and edit the default values of any or all of the following variables:
    good_score
    suspicious_score
    malicious_score
    For example, you can change the value of the suspicious_score from 99-1 to 90-1.
Previous
Next