APIVoid

Integration version: 11.0

Configure APIVoid to work with Google Security Operations SOAR

How to get API key

  1. To obtain your personal API Key, sign in to your APIVoid account.

  2. Click My API keys to navigate to the page where your API key is stored.

  3. Click Copy to copy over the API key to your clipboard. This will be used later on when configuring this integration in the Google Security Operations SOAR platform.

Network

Function Default port Direction Protocol
API Multivalues Outbound apikey

Configure APIVoid integration in Google Security Operations SOAR

For detailed instructions on how to configure an integration in Google Security Operations SOAR, see Configure integrations.

Integration parameters

Use the following parameters to configure the integration:

Parameter name Type Default value Is mandatory Description
Instance Name String N/A No Name of the Instance you intend to configure integration for.
Description String N/A No Description of the Instance.
Api Root String https://endpoint.apivoid.com Yes Address of the APIVoid instance.
Api Key Password N/A Yes API key generated in APIVoid's console.
Verify SSL Checkbox Unchecked No Use this checkbox, if your APIVoid connection requires an SSL verification.
Run Remotely Checkbox Unchecked No Check the field in order to run the configured integration remotely. Once checked, the option appears to select the remote user (agent).

Actions

Get Domain Reputation

Description

Get domain reputation checks if a domain is blacklisted by a popular and trusted domain blacklist services such as URLVir, ThreatLog, OpenPhish, Spam404, PhishTank, ZeuS Tracker, and more. The multiple domain blacklist services identify potentially malicious and fraudulent websites involved in malware distribution, phishing incidents, and fake online shops.

Parameters

Parameter name Type Default value Is mandatory Description
Threshold String 0 Yes Domain risk threshold. The threshold must be a numeric value. Example: 3
Create Insights Checkbox Checked Yes Specify whether the action should create insights or not.

Use cases

One of the use cases of Domain Reputation API is to check if the client's websites are blacklisted, check URLs submitted by users on your application, or to identify potentially malicious and unsafe websites.

Run on

This action runs on the following entities:

  • Hostname
  • URL

Action results

Entity enrichment

Mark entity as suspicious if the number of negative engines is equal or above the given threshold.

Enrichment field name Logic - When to apply
alexa_top_100k Returns if it exists in JSON result
domain_length Returns if it exists in JSON result
alexa_top_10k Returns if it exists in JSON result
blacklists Returns if it exists in JSON result
server Returns if it exists in JSON result
host Returns if it exists in JSON result
most_abused_tld Returns if it exists in JSON result
alexa_top_250k Returns if it exists in JSON result
Insights
Severity Description
Warn A warning insight shall be created to inform on the malicious status of the enriched entity. The insight will be created when the number of detected engines equals or exceeds the minimum suspicious Threshold set before scan.
Script result
Script result name Value options Example
success True/False success:False
JSON result
[
    {
        "EntityResult": {
            "alexa_top_100k": false,
            "domain_length": 17,
            "alexa_top_10k": false,
            "blacklists": {
                "scantime": "0.07",
                "detection_rate": "0%",
                "detections": 0,
                "engines_count": 29,
                "engines": [{
                    "engine": "ThreatLog",
                    "detected": false,
                    "confidence": "high",
                    "reference": "http://www.threatlog.com/"
                }, {
                    "engine": "Threat Sourcing",
                    "detected": false,
                    "confidence": "high",
                    "reference": "https://www.threatsourcing.com/"
                }, {
                    "engine": "URLVir",
                    "detected": false,
                    "confidence": "high",
                    "reference": "http://www.urlvir.com/"
                }]},
            "server": {
                "region_name": null,
                "reverse_dns": " ",
                "ip": " ",
                "isp": null,
                "continent_code": null,
                "latitude": null,
                "city_name": null,
                "longitude": null,
                "country_code": null,
                "country_name": null,
                "continent_name": null
            },
            "host": "qotaerltozres.com",
            "most_abused_tld": false,
            "alexa_top_250k": false
        },
        "Entity": "qotaerltozres.com"
    }, {
        "EntityResult": {
            "alexa_top_100k": false,
            "domain_length": 9,
            "alexa_top_10k": false,
            "blacklists": {
                "scantime": "0.03",
                "detection_rate": "0%",
                "detections": 0,
                "engines_count": 29,
                "engines": [{
                    "engine": "ThreatLog",
                    "detected": false,
                    "confidence": "high",
                    "reference": "http://www.threatlog.com/"
                }, {
                    "engine": "Threat Sourcing",
                    "detected": false,
                    "confidence": "high",
                    "reference": "https://www.threatsourcing.com/"
                }, {
                    "engine": "URLVir",
                    "detected": false,
                    "confidence": "high",
                    "reference": "http://www.urlvir.com/"
                }]},
            "server": {
                "region_name": null,
                "reverse_dns": " ",
                "ip": " ",
                "isp": null,
                "continent_code": null,
                "latitude": null,
                "city_name": null,
                "longitude": null,
                "country_code": null,
                "country_name": null,
                "continent_name": null
            },
            "host": "1.1.1.1",
            "most_abused_tld": false,
            "alexa_top_250k": false
        },
        "Entity": "1.1.1.1"
    }
]

Get Ip Reputation

Description

IP Reputation API detects potentially malicious IP addresses which are commonly used for spam, website attacks or fraudulent activity.

Parameters

Parameter Type Default value Is mandatory Description
Threshold String N/A Yes IP risk threshold. The threshold must be a numeric value. Example: 3.
Create Insights Checkbox Checked Yes Specify whether the action should create insights or not.

Run on

This action runs on the IP Address entity.

Action results

Entity enrichment

Mark entity as suspicious if the number of negative engines is equal or above the given threshold.

Enrichment field name Logic - When to apply
information Returns if it exists in JSON result
blacklists Returns if it exists in JSON result
anonymity Returns if it exists in JSON result
ip Returns if it exists in JSON result
Insights
Severity Description
Warn A warning insight shall be created to inform on the malicious status of the enriched hash. The insight will be created when the number of detected engines equals or exceeds the minimum suspicious Threshold set before scan.
Script result
Script result name Value options Example
success True/False success:False
JSON result
[
    {
        "EntityResult": {
            "information": {
                "is_proxy": false,
                "is_vpn": false,
                "region_name": "Zhejiang",
                "is_webproxy": false,
                "latitude": 28.680280685424805,
                "isp": "ChinaNet Zhejiang Province Network",
                "continent_code": "AS",
                "is_tor": false,
                "reverse_dns": " ",
                "detections": 18,
                "engines_count": 76,
                "longitude": 121.44277954101562,
                "city_name": "Jiaojiang",
                "country_name": "China",
                "continent_name": "Asia",
                "detection_rate": "24%",
                "country_code": "CN",
                "is_hosting": false
            },
            "blacklists": {
                "scantime": "0.57",
                "detection_rate":
                "24%",
                "detections": 18,
                "engines_count": 76,
                "engines": [{
                    "engine": "PlonkatronixBL",
                    "detected": false,
                    "reference": "http://bl.plonkatronix.com/"
                }, {
                    "engine": "Peter-s NUUG IP BL",
                    "detected": true,
                    "reference": "https://home.nuug.no/~peter/"
                }, {"engine": "Malc0de",
                    "detected": false,
                    "reference": "http://malc0de.com/database/index.php"
                   }]},
            "anonymity": {
                "is_tor": false,
                "is_proxy": false,
                "is_vpn": false,
                "is_webproxy": false,
                "is_hosting": false
            },
            "ip": "1.1.1.1"
        },
        "Entity": "1.1.1.1"
    }
]

Get URL Reputation

Description

Get safety reputation and risk score of an URL.

Parameters

Parameter name Type Default value Is mandatory Description
Threshold Integer N/A Yes

URL risk threshold. The threshold must be a numeric value. Example: 3

Use cases

An analyst can get URL reputation (similar to get domain/ip reputation).

Run on

This action runs on the URL entity.

Action results

Entity enrichment

Mark entity as suspicious if the number of negative engines is equal or above the given threshold. if data.get("report", {}).get("risk_score", {}).get("result") > threshold

Enrichment field name Logic - When to apply
domain_blacklist Returns if it exists in JSON result
html_forms Returns if it exists in JSON result
server_details Returns if it exists in JSON result
response_headers Returns if it exists in JSON result
redirection Returns if it exists in JSON result
file_type Returns if it exists in JSON result
risk_score Returns if it exists in JSON result
security_checks Returns if it exists in JSON result
geo_location Returns if it exists in JSON result
url_parts Returns if it exists in JSON result
site_category Returns if it exists in JSON result
web_page Returns if it exists in JSON result
dns_records Returns if it exists in JSON result
Script result
Script result name Value options Example
is_success True/False is_success:False
JSON result
[
    {
        "EntityResult": {
            "domain_blacklist": {
                "detections": 0,
                "engines": [{
                    "detected": false,
                        "name": "SpamhausDBL", "reference": "https://www.spamhaus.org/lookup/"
                    }, {
                        "detected": false,
                        "name": "ThreatLog",
                        "reference": "http://www.threatlog.com/"
                    }, {
                        "detected": false,
                        "name": "OpenPhish",
                        "reference": "http://www.openphish.com/"
                    }, {
                        "detected": false,
                        "name": "PhishTank",
                        "reference": "http://www.phishtank.com/"
                    }, {
                        "detected": false,
                        "name": "Phishing.Database",
                        "reference": "https://github.com/mitchellkrogza/Phishing.Database"
                    }, {
                        "detected": false,
                        "name": "PhishStats",
                        "reference": "https://phishstats.info/"
                    }, {
                        "detected": false,
                        "name": "URLVir",
                        "reference": "http://www.urlvir.com/"
                    }, {
                        "detected": false,
                        "name": "URLhaus",
                        "reference": "https://urlhaus.abuse.ch/"
                    }, {
                        "detected": false,
                        "name": "RPiList Not Serious",
                        "reference": "https://github.com/RPiList/specials"
                    }, {
                        "detected": false,
                        "name": "precisionsec",
                        "reference": "https://precisionsec.com/"
                    }, {
                        "detected": false,
                        "name": "AntiSocial Blacklist",
                        "reference": "https://theantisocialengineer.com/"
                    }, {
                        "detected": false,
                        "name": "PhishFeed",
                        "reference": "https://phishfeed.com/"
                    }, {
                        "detected": false,
                        "name": "Spam404",
                        "reference": "https://www.spam404.com/"
                    }]},
            "html_forms": {
                "number_of_total_input_fields": 0,
                "email_field_present": false,
                "number_of_total_forms": 0,
                "password_field_present": false,
                "two_text_inputs_in_a_form": false,
                "credit_card_field_present": false
            },
            "server_details": {
                "continent_name": "Asia",
                "hostname": "mfwd12.mailplug.co.kr",
                "region_name": "Seoul-teukbyeolsi",
                "ip": "14.49.36.141",
                "isp": "KT Corporation",
                "continent_code": "AS",
                "country_name": "Korea (Republic of)",
                "city_name": "Seoul",
                "longitude": 126.97782897949219,
                "country_code": "KR",
                "latitude": 37.568260192871094
            },
            "response_headers": {
                "status": "HTTP/1.1 404 Not Found",
                "content-length": "177",
                "code": 404,
                "server": "nginx/1.4.6 (Ubuntu)",
                "connection": "keep-alive",
                "date": "Wed, 15 Jul 2020 08:21:54 GMT",
                "content-type": "text/html"
            },
            "redirection": {
                "url": null,
                "found": false,
                "external": false
            },
            "file_type": {
                "headers": "HTML",
                "extension": "HTML",
                "signature": " "
            },
            "risk_score": {
                "result": 10
            },
            "security_checks": {
                "is_suspended_page": false,
                "is_defaced_heuristic": false,
                "is_windows_exe_file": false,
                "is_credit_card_field": false,
                "is_windows_exe_file_on_free_hosting": false,
                "is_masked_linux_elf_file": false,
                "is_exe_on_directory_listing": false,
                "is_php_on_directory_listing": false,
                "is_masked_windows_exe_file": false,
                "is_sinkholed_domain": false,
                "is_robots_noindex": false,
                "is_windows_exe_file_on_free_dynamic_dns": false,
                "is_doc_on_directory_listing": false,
                "is_non_standard_port": false,
                "is_linux_elf_file_on_free_dynamic_dns": false,
                "is_suspicious_domain": false, "is_suspicious_url_pattern": false,
                "is_china_country": false,
                "is_risky_geo_location": false,
                "is_pdf_on_directory_listing": false,
                "is_valid_https": false,
                "is_external_redirect": false, "is_windows_exe_file_on_ipv4": false,
                "is_phishing_heuristic": false,
                "is_linux_elf_file_on_ipv4": false,
                "is_email_address_on_url_query": false,
                "is_uncommon_clickable_url": false,
                "is_most_abused_tld": false,
                "is_domain_blacklisted": false,
                "is_host_an_ipv4": false,
                "is_linux_elf_file_on_free_hosting": false,
                "is_zip_on_directory_listing": false,
                "is_password_field": false,
                "is_linux_elf_file": false,
                "is_empty_page_title": false,
                "is_directory_listing": false,
                "is_masked_file": false,
                "is_suspicious_file_extension": false,
                "is_suspicious_content": false
            },
            "geo_location": {
                "countries": ["KR"]
            },
            "url_parts": {
                "host_nowww": "funad.co.kr",
                "host": "www.funad.co.kr",
                "path": "/dynamic/adv/sb/searchnqpopu.html",
                "query": null,
                "scheme": "http",
                "port": 80},
            "site_category": {
                "is_vpn_provider": false,
                "is_url_shortener": false,
                "is_anonymizer": false,
                "is_torrent": false,
                "is_free_dynamic_dns": false,
                "is_free_hosting": false
            },
            "web_page": {
                "keywords": "",
                "description": "",
                "title": "404 Not Found"
            },
            "dns_records": {
                "ns": {
                    "records": [{
                        "country_name": "Korea (Republic of)",
                        "ip": "211.253.28.95",
                        "isp": "KT Corporation",
                        "target": "ns.mailplug.com",
                        "country_code": "KR"
                    }, {
                        "country_name": "Korea (Republic of)",
                        "ip": "223.26.214.26",
                        "isp": "LX",
                        "target": "ns2.mailplug.com",
                        "country_code": "KR"
                    }]},
                "mx": {
                    "records": []
                }}},
        "Entity": "www.funad.co.kr:80/dynamic/adv/sb/searchnqpopu.html"
    }
]
Case wall
Result type Description Type
Output message*
  1. Successful entities: "APIVoid: Fetched reputation for the following entities: <entities identifer list>
  2. Failed entities: "An error occurred on the following entities: <entities identifer list>"
  3. Missing entities (no data): 'Can not found reputation for the following entities: <entities identifer list>"
  4. Alert without URL entities: "APIVoid: No URLs found."
 General
CSV Case wall

If data available create new entity csv table:

  1. domain blacklist report: data.get("report",{}).get("domain_blacklist",{}).get("engines", [])
 General
Enrichment

If data available add the following as entity enrichment: (don't forget to add prefix "APIVoid")

  1. geo_location: data.get("report",{}).get("geo_location",{}).get("countries", [])
  2. is_suspicious_domain: data.get("report",{}).get("security_checks",{}).get("is_suspicious_domain")
  3. is_domain_blacklisted: data.get("report",{}).get("security_checks",{}).get("is_domain_blacklisted")
  4. is_risky_geo_location: data.get("report",{}).get("security_checks",{}).get("is_risky_geo_location")
  5. risk_score: data.get("report", {}).get("risk_score", {}).get("result")
  6. is_external_redirect: data.get("report",{}).get("security_checks",{}).get("is_external_redirect")
 Entity

Get Screenshot

Description

Capture a high-quality screenshot of any website or URL.

Parameters

N/A

Use cases

An analyst can capture high-quality screenshots of any website or URL, in PNG or JPG image format.

Run on

This action runs on the User entity.

Action results

Entity enrichment

Mark entity as suspicious if the number of negative engines is equal or above the given threshold. is_suspicious: if data.get("score") > threshold

Enrichment field name Logic - When to apply
domain Returns if it exists in JSON result
should_block Returns if it exists in JSON result
score Returns if it exists in JSON result
disposable Returns if it exists in JSON result
has_mx_records Returns if it exists in JSON result
has_spf_records Returns if it exists in JSON result
Script result
Script result name Value options Example
is_success True/False is_success:False
JSON result
[
    {
        "EntityResult": {
            "domain": "siemplify.co ",
            "valid_tld": true,
            "email": "vickie.b@siemplify.co",
            "role_address": false,
            "should_block": false,
            "risky_tld": false,
            "dirty_words_username": false,
            "suspicious_domain": false,
            "score": 100,
            "educational_domain": false,
            "dirty_words_domain": false,
            "did_you_mean": " ",
            "username": "vickie.b",
            "valid_format": true,
            "is_spoofable ": false,
            "disposable": false,
            "government_domain": false,
            "has_spf_records": true,
            "domain_popular": false,
            "has_mx_records": true,
            "china_free_email": false,
            "free_email": false,
            "russian_free_email": false,
            "police_domain": false,
            "dmarc_enforced": false,
            "suspicious_username": false
        },
        "Entity": "VICKIE.B@SIEMPLIFY.CO"
    }
]
Case wall
Result type Description Type
Output message*
  1. Successful entities: "APIVoid: Added screenshots for the following entities: <entities identifier list>"
  2. Failed entities: "An error occurred on the following entities: <entities identifier list>"
  3. Missing entities (no data): 'No screenshots found for the following entities: <entities identifier list>"
  4. Alert without URL entities: "APIVoid: No URL entities found for capturing screenshots."
  5. To big entities (attachment file size > 3MB): "Failed to add screenshots as attachments on the following entities: <<entities identifier list>>"
 General
Attachments

If data available create new file obj

  1. attachment title: 'Screenshot - {0}'.format(entity.identifier)
  2. file name should be the url without the suffix (https/http) + '_capture.<file format>'
  3. screenshot is returned in base64 encoded string --> file content should be b64decode(data.get('base64_file'))
  4. Don't forget to add try, except - we have 3MB limitation from the platform. In case of an error - add relevant message to the logger.
 General

Ping

Description

Test connectivity.

Parameters

N/A

Run on

This action runs on all entities.

Action results

Script result
Script result name Value options Example
success True/False success:False

Verify Email

Description

Check if an email is disposable, has MX records, and more.

Parameters

Parameter name Type Default value Is mandatory Description
Threshold Integer N/A Yes

Email risk threshold. The threshold must be a numeric value.

Example: 3

Use cases

An analyst can check if an email is disposable, get MX records, and more.

Run on

This action runs on the User entity.

Action results

Entity enrichment

Mark entity as suspicious if the number of negative engines is equal or above the given threshold. is_suspicious: if data.get("score") > threshold

Enrichment field name Logic - When to apply
domain Returns if it exists in JSON result
should_block Returns if it exists in JSON result
score Returns if it exists in JSON result
disposable Returns if it exists in JSON result
has_mx_records Returns if it exists in JSON result
has_spf_records Returns if it exists in JSON result
Insights

N/A

Script result
Script result name Value options Example
is_success True/False is_success:False
JSON result
[
    {
        "EntityResult": {
            "domain": "siemplify.co ",
            "valid_tld": true,
            "email": "vickie.b@siemplify.co",
            "role_address": false,
            "should_block": false,
            "risky_tld": false,
            "dirty_words_username": false,
            "suspicious_domain": false,
            "score": 100,
            "educational_domain": false,
            "dirty_words_domain": false,
            "did_you_mean": " ",
            "username": "vickie.b",
            "valid_format": true,
            "is_spoofable ": false,
            "disposable": false,
            "government_domain": false,
            "has_spf_records": true,
            "domain_popular": false,
            "has_mx_records": true,
            "china_free_email": false,
            "free_email": false,
            "russian_free_email": false,
            "police_domain": false,
            "dmarc_enforced": false,
            "suspicious_username": false
        },
        "Entity": "VICKIE.B@SIEMPLIFY.CO"
    }
]
Case wall
Result type Description Type
Output message*
  1. successful entities: "APIVoid: Fetched information for the following entities: <entities identifer list>
  2. Failed entities: "An error occurred on the following entities: <entities identifer list>"
  3. Missing entities (no data): 'Can not found information for the following entities: <entities identifer list>"
  4. Alert without URL entities: "APIVoid: No emails found."
 General
CSV Case wall CSV content: entity data(example below) General
Enrichment

If data available add the following as entity enrichment: (don't forget to add prefix "APIVoid")

  1. suspicious_domain: data.get("suspicious_domain")
  2. should_block: data.get("should_block")
  3. score: data.get("score")
  4. disposable: data.get("disposable")
  5. has_mx_records: data.get("has_mx_records")
  6. has_spf_records: data.get("has_spf_records")
 Entity