apivoid v1.0.2

About the connector

apivoid provides several threat intelligence services ranging from IP, URL, and Domain reputation to domain age and website screenshots.

This document provides information about the apivoid connector, which facilitates automated interactions with apivoid using FortiSOAR™ playbooks. Add the apivoid connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving the reputation for specified email ID, IP addresses, domain names, etc, taking high-quality screenshots of the specified website, or retrieving the domain registration date and domain age, in days, for the specified domain.

Version information

Connector Version: 1.0.2

FortiSOAR™ Version Tested on: 7.4.0-3024

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.0.2

The following enhancements have been made to the apivoid connector in version 1.0.2:

• Updated the 'Compute API Void Summary' step in the following enrichment playbooks to take API Void's inverse threat score into account (100 is good and 0 is bad):
  • IP Address > API Void > Enrichment
  • Domain > API Void > Enrichment
  • Email Address > API Void > Enrichment
  • URL > API Void > Enrichment
    For more information, see the Pluggable Enrichment topic.
• Updated the output schema for all the actions.

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-apivoid

Prerequisites to configuring the connector

• You must have the IP address or FQDN of the apivoid cloud platform to which you will connect and perform automated operations and credentials to access that server.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the apivoid 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 apivoid connector card. On the connector popup, click the Configurations tab to enter the required configuration details:

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations:

operation: Get ThreatLog Domain Reputation

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"host": "",
"threatlog": {
"detected": "",
"scantime": "",
"reference": ""
}
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get Domain Reputation

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"report": {
"host": "",
"server": {
"ip": "",
"asn": "",
"isp": "",
"latitude": "",
"city_name": "",
"longitude": "",
"region_name": "",
"reverse_dns": "",
"country_code": "",
"country_name": "",
"continent_code": "",
"continent_name": ""
},
"category": {
"is_pastebin": "",
"is_anonymizer": "",
"is_code_sandbox": "",
"is_form_builder": "",
"is_free_hosting": "",
"is_url_shortener": "",
"is_free_dynamic_dns": "",
"is_free_file_sharing": ""
},
"blacklists": {
"engines": {
"": {
"engine": "",
"elapsed": "",
"detected": "",
"reference": "",
"confidence": ""
}
},
"scantime": "",
"detections": "",
"engines_count": "",
"detection_rate": ""
},
"risk_score": {
"result": ""
},
"security_checks": {
"is_risky_category": "",
"is_most_abused_tld": "",
"website_popularity": "",
"is_domain_ipv4_valid": "",
"is_domain_blacklisted": "",
"is_domain_ipv4_private": "",
"is_domain_ipv4_assigned": "",
"is_domain_ipv4_loopback": "",
"is_domain_ipv4_reserved": "",
"is_uncommon_host_length": "",
"is_uncommon_dot_char_count": "",
"is_uncommon_dash_char_count": "",
"is_uncommon_clickable_domain": ""
}
}
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get IP Reputation

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"report": {
"ip": "",
"is_tor": "",
"is_vpn": "",
"is_proxy": "",
"is_hosting": "",
"is_webproxy": ""
},
"blacklists": {
"engines": {
"": {
"engine": "",
"elapsed": "",
"detected": "",
"reference": ""
}
},
"scantime": "",
"detections": "",
"engines_count": "",
"detection_rate": ""
},
"risk_score": {
"result": ""
},
"information": {
"asn": "",
"isp": "",
"latitude": "",
"city_name": "",
"longitude": "",
"region_name": "",
"reverse_dns": "",
"country_code": "",
"country_name": "",
"continent_code": "",
"continent_name": "",
"country_currency": "",
"country_calling_code": ""
}
}
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
}

operation: Get URL Screenshot

Input parameters

Output

The output contains the following populated JSON schema:
{
"data": {
"id": "",
"@id": "",
"file": {
"id": "",
"@id": "",
"file": [],
"size": "",
"@type": "",
"@context": "",
"filename": "",
"metadata": [],
"mimeType": "",
"thumbnail": "",
"uploadDate": ""
},
"name": "",
"type": "",
"@type": "",
"@context": "",
"createDate": "",
"createUser": {
"id": "",
"@id": "",
"name": "",
"@type": "",
"avatar": "",
"userId": "",
"userType": "",
"@settings": "",
"createDate": "",
"createUser": "",
"modifyDate": "",
"modifyUser": ""
},
"modifyDate": "",
"modifyUser": {
"id": "",
"@id": "",
"name": "",
"@type": "",
"avatar": "",
"userId": "",
"userType": "",
"@settings": "",
"createDate": "",
"createUser": "",
"modifyDate": "",
"modifyUser": ""
},
"recordTags": "",
"description": ""
},
"status": "",
"_status": "",
"message": "",
"operation": "",
"request_id": ""
}

operation: Get URL Reputation

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"report": {
"web_page": {
"title": "",
"keywords": "",
"description": ""
},
"file_type": {
"headers": "",
"extension": "",
"signature": ""
},
"url_parts": {
"host": "",
"path": "",
"port": "",
"query": "",
"scheme": "",
"host_nowww": ""
},
"html_forms": {
"email_field_present": "",
"number_of_total_forms": "",
"password_field_present": "",
"credit_card_field_present": "",
"two_text_inputs_in_a_form": "",
"number_of_total_input_fields": ""
},
"risk_score": {
"result": ""
},
"dns_records": {
"mx": {
"records": [
{
"ip": "",
"isp": "",
"target": "",
"country_code": "",
"country_name": ""
}
]
},
"ns": {
"records": [
{
"ip": "",
"isp": "",
"target": "",
"country_code": "",
"country_name": ""
}
]
}
},
"redirection": {
"url": "",
"found": "",
"external": ""
},
"geo_location": {
"countries": []
},
"site_category": {
"is_torrent": "",
"is_pastebin": "",
"is_anonymizer": "",
"is_code_sandbox": "",
"is_form_builder": "",
"is_free_hosting": "",
"is_vpn_provider": "",
"is_url_shortener": "",
"is_free_dynamic_dns": "",
"is_free_file_sharing": ""
},
"server_details": {
"ip": "",
"asn": "",
"isp": "",
"hostname": "",
"latitude": "",
"city_name": "",
"longitude": "",
"region_name": "",
"country_code": "",
"country_name": "",
"continent_code": "",
"continent_name": ""
},
"security_checks": {
"is_masked_file": "",
"is_valid_https": "",
"is_host_an_ipv4": "",
"is_china_country": "",
"is_domain_recent": "",
"is_linux_elf_file": "",
"is_ms_office_file": "",
"is_password_field": "",
"is_risky_category": "",
"is_robots_noindex": "",
"is_suspended_page": "",
"is_url_accessible": "",
"is_most_abused_tld": "",
"is_nigeria_country": "",
"is_possible_emotet": "",
"is_android_apk_file": "",
"is_empty_page_title": "",
"is_sinkholed_domain": "",
"is_windows_exe_file": "",
"is_credit_card_field": "",
"is_defaced_heuristic": "",
"is_directory_listing": "",
"is_domain_ipv4_valid": "",
"is_external_redirect": "",
"is_http_client_error": "",
"is_http_server_error": "",
"is_http_status_error": "",
"is_non_standard_port": "",
"is_suspicious_domain": "",
"is_domain_blacklisted": "",
"is_domain_very_recent": "",
"is_empty_page_content": "",
"is_phishing_heuristic": "",
"is_risky_geo_location": "",
"is_suspicious_content": "",
"is_domain_ipv4_private": "",
"is_domain_ipv4_assigned": "",
"is_domain_ipv4_loopback": "",
"is_domain_ipv4_reserved": "",
"is_uncommon_host_length": "",
"is_masked_linux_elf_file": "",
"is_linux_elf_file_on_ipv4": "",
"is_suspicious_url_pattern": "",
"is_uncommon_clickable_url": "",
"is_masked_windows_exe_file": "",
"is_uncommon_dot_char_count": "",
"is_android_apk_file_on_ipv4": "",
"is_apk_on_directory_listing": "",
"is_doc_on_directory_listing": "",
"is_exe_on_directory_listing": "",
"is_pdf_on_directory_listing": "",
"is_php_on_directory_listing": "",
"is_uncommon_dash_char_count": "",
"is_windows_exe_file_on_ipv4": "",
"is_zip_on_directory_listing": "",
"is_redirect_to_search_engine": "",
"is_suspicious_file_extension": "",
"is_email_address_on_url_query": "",
"is_linux_elf_file_on_free_hosting": "",
"is_android_apk_file_on_free_hosting": "",
"is_windows_exe_file_on_free_hosting": "",
"is_linux_elf_file_on_free_dynamic_dns": "",
"is_android_apk_file_on_free_dynamic_dns": "",
"is_windows_exe_file_on_free_dynamic_dns": ""
},
"domain_blacklist": {
"engines": [
{
"name": "",
"detected": "",
"reference": ""
}
],
"detections": ""
},
"response_headers": {
"p3p": "",
"code": "",
"date": "",
"server": "",
"status": "",
"alt-svc": "",
"expires": "",
"accept-ch": "",
"report-to": "",
"set-cookie": "",
"content-type": "",
"origin-trial": "",
"cache-control": "",
"content-length": "",
"x-frame-options": "",
"content-encoding": "",
"x-xss-protection": "",
"permissions-policy": "",
"strict-transport-security": "",
"cross-origin-opener-policy": "",
"content-security-policy-report-only": ""
}
}
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get Domain Age

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"host": "",
"debug_message": "",
"domain_age_found": "",
"domain_registered": "",
"domain_age_in_days": "",
"domain_age_in_years": "",
"domain_age_in_months": "",
"domain_creation_date": ""
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get Domain Trustworthiness

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"report": {
"web_page": {
"title": "",
"keywords": "",
"description": ""
},
"url_parts": {
"host": "",
"path": "",
"port": "",
"query": "",
"scheme": "",
"host_nowww": ""
},
"domain_age": {
"found": "",
"domain_age_in_days": "",
"domain_age_in_years": "",
"domain_age_in_months": "",
"domain_creation_date": ""
},
"dns_records": {
"mx": {
"records": [
{
"ip": "",
"isp": "",
"target": "",
"country_code": "",
"country_name": ""
}
]
},
"ns": {
"records": [
{
"ip": "",
"isp": "",
"target": "",
"country_code": "",
"country_name": ""
}
]
}
},
"redirection": {
"url": "",
"found": "",
"external": ""
},
"trust_score": {
"result": ""
},
"geo_location": {
"countries": []
},
"server_details": {
"ip": "",
"asn": "",
"isp": "",
"hostname": "",
"latitude": "",
"city_name": "",
"longitude": "",
"region_name": "",
"country_code": "",
"country_name": "",
"continent_code": "",
"continent_name": ""
},
"security_checks": {
"is_free_email": "",
"is_valid_https": "",
"is_fake_socials": "",
"is_ipv6_enabled": "",
"is_china_country": "",
"is_domain_recent": "",
"is_dmarc_enforced": "",
"is_high_discounts": "",
"is_robots_noindex": "",
"is_suspended_site": "",
"is_email_spoofable": "",
"is_most_abused_tld": "",
"is_nigeria_country": "",
"is_ssl_blacklisted": "",
"is_website_popular": "",
"is_dmarc_configured": "",
"is_email_configured": "",
"is_empty_page_title": "",
"is_sinkholed_domain": "",
"is_defaced_heuristic": "",
"is_directory_listing": "",
"is_domain_ipv4_valid": "",
"is_external_redirect": "",
"is_heuristic_pattern": "",
"is_http_client_error": "",
"is_http_server_error": "",
"is_http_status_error": "",
"is_suspicious_domain": "",
"is_domain_blacklisted": "",
"is_domain_very_recent": "",
"is_ecommerce_platform": "",
"is_empty_page_content": "",
"is_risky_geo_location": "",
"is_website_accessible": "",
"is_domain_ipv4_private": "",
"is_domain_ipv4_assigned": "",
"is_domain_ipv4_loopback": "",
"is_domain_ipv4_reserved": "",
"is_uncommon_host_length": "",
"is_custom_404_configured": "",
"is_uncommon_dot_char_count": "",
"is_uncommon_dash_char_count": "",
"is_redirect_to_search_engine": ""
},
"domain_blacklist": {
"engines": [
{
"name": "",
"detected": "",
"reference": ""
}
],
"detections": ""
},
"response_headers": {
"age": "",
"via": "",
"code": "",
"date": "",
"etag": "",
"vary": "",
"server": "",
"status": "",
"x-cache": "",
"set-cookie": "",
"x-amz-id-2": "",
"x-amz-cf-id": "",
"content-type": "",
"x-amz-cf-pop": "",
"cache-control": "",
"last-modified": "",
"content-encoding": "",
"x-amz-request-id": "",
"x-amz-version-id": "",
"x-amz-meta-cf-origin": "",
"x-amz-server-side-encryption": ""
},
"ecommerce_platform": {
"is_other": "",
"is_shopyy": "",
"is_magento": "",
"is_shopify": "",
"is_ueeshop": "",
"is_zencart": "",
"is_opencart": "",
"is_shoplazza": "",
"is_prestashop": "",
"is_youcanshop": "",
"is_woocommerce": ""
}
}
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get Domain Parked Status

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"host": "",
"parked_domain": "",
"a_records_found": ""
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get URL Status

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"report": {
"analysis": {
"url_status": "",
"suspended_page": "",
"url_taken_down": "",
"valid_server_ip": "",
"http_status_code": "",
"sinkholed_domain": "",
"http_client_error": "",
"http_server_error": ""
},
"web_page": {
"title": "",
"keywords": "",
"description": ""
},
"url_parts": {
"host": "",
"path": "",
"port": "",
"query": "",
"scheme": "",
"host_nowww": ""
},
"redirection": {
"url": "",
"found": "",
"external": ""
},
"server_details": {
"ip": "",
"hostname": ""
},
"response_headers": {
"p3p": "",
"code": "",
"date": "",
"server": "",
"status": "",
"alt-svc": "",
"expires": "",
"location": "",
"report-to": "",
"set-cookie": "",
"content-type": "",
"origin-trial": "",
"cache-control": "",
"content-length": "",
"x-frame-options": "",
"x-xss-protection": "",
"permissions-policy": "",
"cross-origin-opener-policy": "",
"content-security-policy-report-only": ""
}
}
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get Email Reputation

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"email": "",
"score": "",
"domain": "",
"username": "",
"risky_tld": "",
"valid_tld": "",
"disposable": "",
"free_email": "",
"did_you_mean": "",
"is_spoofable": "",
"role_address": "",
"should_block": "",
"valid_format": "",
"has_a_records": "",
"police_domain": "",
"dmarc_enforced": "",
"domain_popular": "",
"has_mx_records": "",
"has_spf_records": "",
"china_free_email": "",
"dmarc_configured": "",
"suspicious_email": "",
"government_domain": "",
"suspicious_domain": "",
"dirty_words_domain": "",
"educational_domain": "",
"russian_free_email": "",
"suspicious_username": "",
"dirty_words_username": ""
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get DNS Propagation

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"host": "",
"dns_type": "",
"propagation": [
{
"service": "",
"response": "",
"country_code": "",
"country_name": ""
}
]
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get URL HTML

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"format": "",
"elapsed": "",
"base64_file": "",
"file_md5_hash": "",
"file_size_bytes": "",
"file_size_readable": ""
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

operation: Get SSL Info

Input parameters

Output

The output contains the following populated JSON schema:
{
"result": {
"data": {
"host": "",
"certificate": {
"found": "",
"valid": "",
"details": {
"issuer": {
"state": "",
"country": "",
"location": "",
"common_name": "",
"organization": "",
"organization_unit": ""
},
"subject": {
"name": "",
"state": "",
"street": "",
"country": "",
"category": "",
"location": "",
"common_name": "",
"postal_code": "",
"organization": "",
"alternative_names": "",
"organization_unit": ""
},
"validity": {
"valid_to": "",
"days_left": "",
"valid_from": "",
"valid_to_timestamp": "",
"valid_from_timestamp": ""
},
"signature": {
"type": "",
"serial": "",
"serial_hex": ""
},
"extensions": {
"key_usage": "",
"basic_constraints": "",
"extended_key_usage": "",
"certificate_policies": "",
"authority_info_access": "",
"subject_key_identifier": "",
"crl_distribution_points": "",
"authority_key_identifier": ""
}
},
"expired": "",
"name_match": "",
"valid_peer": "",
"blacklisted": "",
"fingerprint": "",
"debug_message": "",
"deprecated_issuer": ""
}
},
"success": "",
"elapsed_time": "",
"credits_remained": "",
"estimated_queries": ""
},
"status": ""
}

Included playbooks

The Sample - ApiVoid - 1.0.2 playbook collection comes bundled with the apivoid 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 apivoid connector.

• Domain > API Void > Enrichment
• Email Address > API Void > Enrichment
• Get DNS Propagation
• Get Domain Age
• Get Domain Parked Status
• Get Domain Reputation
• Get Domain Trustworthiness
• Get Email Reputation
• Get IP Reputation
• Get SSL Info
• Get ThreatLog Domain Reputation
• Get URL HTML
• Get URL Reputation
• Get URL Screenshot
• Get URL Status
• IP Address > API Void > Enrichment
• URL > API Void > 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 the connector upgrade and delete.

Pluggable Enrichment

The sample playbook collection of the API Void connector post version 1.0.1 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, domain, URL, or Email address. The pluggable enrichment playbooks are in the format: '<indicator type> > API Void > Enrichment' format. For example, 'URL > API Void > Enrichment'.

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

NOTE: When compared to other threat intelligence services, the API Void threat scores are inverse. For API Void, a score of 100 is good, while a score of 0 is bad. The 'Compute API Void Summary' step in the enrichment playbooks takes into account this inverse score.

Default variables for indicator type IP, Domain, and URL

The following table lists the variable names and their default values:

Based on the above default values, the API Void integration API response returns the verdict, cti_score, and enrichment_summary (all the other variables are common, which is listed in the Common Variable Table).

Default responses for verdict, cti_score, and enrichment_summary variables for indicator type IP, Domain, and URL

Variable Name	Description	Return Value
verdict for IP address, Domain, and URL	This connector returns a high-reliability value called 'verdict'. Use this verdict to find the reputation of the various types of indicators.	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 for IP address, Domain, and URL	The verdict value returned by the integration API.	risk_score
enrichment_summary for IP Address	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 Proxy TOR Hosting Blacklisted Detection Engine Rate The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record:
enrichment_summary for Domain	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 Domain Blacklisted Risky Category Blacklisted Detection Engine Rate The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record:
enrichment_summary for URL	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 Domain Blacklisted Suspicious Domain Risky Geolocation Blacklisted Detection Engine Rate 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:

Based on the above default values, the API Void integration API response returns the verdict, cti_score, and enrichment_summary (all the other variables are common, which is listed in the Common Variable Table).

Default responses for verdict, cti_score, and enrichment_summary variables for indicator type Email Address

Common Variables Table

This table lists the variables, returned by the API Void integration response API, common to all indicators.

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 - API Void - .
2. Open the required playbook in the Playbook Designer.
   The pluggable enrichment playbooks are in the '<indicator type> > API Void > Enrichment' format. For example, URL > API Void > 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 good_score from 0 to 10.