Integrate APIVoid with Google SecOps

This document describes how to integrate APIVoid with Google Security Operations (Google SecOps).

Integration version: 12.0

Before you begin

To obtain your personal API key, complete the following steps:

  1. 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 SecOps platform.

Network

Function Default port Direction Protocol
API Multivalues Outbound apikey

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).

For instructions about how to configure an integration in Google SecOps, see Configure integrations.

You can make changes at a later stage, if needed. After you configure an integration instance, you can use it in playbooks. For more information about how to configure and support multiple instances, see Supporting multiple instances.

Actions

For more information about actions, see Respond to pending actions from Your Workdesk and Perform a manual action.

Get Domain Reputation

Get domain reputation checks if a domain is excluded by a popular and trusted domain blocklist services, such as URLVir, ThreatLog, OpenPhish, Spam404, PhishTank, ZeuS Tracker, and more. The multiple domain blocklist 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 excluded, 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 is created to inform on the malicious status of the enriched entity. The is 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": "example.com",
            "most_abused_tld": false,
            "alexa_top_250k": false
        },
        "Entity": "example.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": "192.0.2.1",
            "most_abused_tld": false,
            "alexa_top_250k": false
        },
        "Entity": "192.0.2.1"
    }
]

Get Ip Reputation

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 is created to inform on the malicious status of the enriched hash. The insight is 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": "Engine",
                    "detected": true,
                    "reference": "https://home.nuug.no/~engine/"
                }, {"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": "192.0.2.1"
        },
        "Entity": "192.0.2.1"
    }
]

Get URL Reputation

Get safety reputation and risk score of a 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 retrieve the URL reputation, similar to how to retrieve the reputation of a domain or IP address.

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": "example.com",
                "region_name": "Seoul-teukbyeolsi",
                "ip": "192.0.2.141",
                "isp": "Example 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": "example.com",
                "host": "www.example.com",
                "path": "/dynamic/example.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": "192.0.2.95",
                        "isp": "Example Corporation",
                        "target": "example.com",
                        "country_code": "KR"
                    }, {
                        "country_name": "Korea (Republic of)",
                        "ip": "192.0.2.26",
                        "isp": "LX",
                        "target": "example.com",
                        "country_code": "KR"
                    }]},
                "mx": {
                    "records": []
                }}},
        "Entity": "www.example.com:80/dynamic/example.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 blocklist 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

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": "example.com",
            "valid_tld": true,
            "email": "user@example.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": "user",
            "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": "USER@EXAMPLE.COM"
    }
]
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 is available, create a new file object:

  1. attachment title: 'Screenshot - {0}'.format(entity.identifier)
  2. filename 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

Test the 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

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
Script result
Script result name Value options Example
is_success True/False is_success:False
JSON result
[
    {
        "EntityResult": {
            "domain": "example.com",
            "valid_tld": true,
            "email": "user@example.com",
            "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": "user",
            "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": "USER@EXAMPLE.COm"
    }
]
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

Need more help? Get answers from Community members and Google SecOps professionals.