Google Safe Browsing v2

Search Safe Browsing, The Safe Browsing APIs (v4) let your client applications check URLs against Google's constantly updated lists of unsafe web resources.

Data Enrichment & Threat Intelligence · Google Safe Browsing

Details

IDGoogle Safe Browsing v2
ProviderGoogle
CategoryData Enrichment & Threat Intelligence
From Version5.5.0
Docker Imagedemisto/python3:3.12.13.10116658
Supported ModulesAgentix XSIAM

README

Search Safe Browsing v4

Configure GoogleSafeBrowsing in Cortex

Parameter Description Required
API Key   True
Client ID   True
Client Version   True
Base URL   True
Source Reliability Reliability of the source providing the intelligence data. True
Use system proxy settings   False
Trust any certificate (not secure)   False

Commands

You can execute these commands from the CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

url

Check URL Reputation

Notice: Submitting indicators using this command might make the indicator data publicly available. See the vendor’s documentation for more details.

Base Command

url

Input

Argument Name Description Required
url URL to check. Required

Context Output

Path Type Description
DBotScore.Indicator string The indicator that was tested.
DBotScore.Type string The indicator type.
DBotScore.Vendor string The vendor used to calculate the score.
DBotScore.Score int The actual score.
DBotScore.Reliability string Reliability of the source providing the intelligence data.
GoogleSafeBrowsing.URL.cacheDuration string The URL cache duration time.
GoogleSafeBrowsing.URL.threatType string The URL threat type.
GoogleSafeBrowsing.URL.threatEntryType string The URL threat entry type.
GoogleSafeBrowsing.URL.platformType string The URL platform type.
URL.Data string Bad URLs found
URL.Malicious.Vendor string For malicious URLs, the vendor that made the decision
URL.Malicious.Description string For malicious URLs, the reason for the vendor to make the decision

Command Example

!url url="http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/"

Context Example

{
    "DBotScore": {
        "Indicator": "http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/",
        "Reliability": "C - Fairly reliable",
        "Score": 3,
        "Type": "url",
        "Vendor": "GoogleSafeBrowsing"
    },
    "URL": {
        "Data": "http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/",
        "Malicious": {
            "Description": "Match found: MALWARE/ANY_PLATFORM,MALWARE/WINDOWS,MALWARE/LINUX,MALWARE/ALL_PLATFORMS,MALWARE/OSX,MALWARE/CHROME",
            "Vendor": "GoogleSafeBrowsing"
        }
    }
}

Human Readable Output

Google Safe Browsing APIs - URL Query

Found matches for URL http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/

cacheDuration platformType threat threatEntryType threatType
300s ANY_PLATFORM {“url”:”http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/”} URL MALWARE
300s WINDOWS {“url”:”http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/”} URL MALWARE
300s LINUX {“url”:”http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/”} URL MALWARE
300s ALL_PLATFORMS {“url”:”http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/”} URL MALWARE
300s OSX {“url”:”http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/”} URL MALWARE
300s CHROME {“url”:”http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/”} URL MALWARE

Configuration parameters

  • url — Your server URL (required)
  • client_id — The Client ID
  • client_version — The Client Version
  • api_key — API Key
  • api_creds — The Client ID
  • integrationReliability — Source Reliability (required)
  • insecure — Trust any certificate (not secure)
  • proxy — Use system proxy settings

Commands (1)

  • url

    Searches for the specified URL on lists.

Source

GoogleSafeBrowsingV2.py GoogleSafeBrowsingV2_test.py GoogleSafeBrowsingV2.yml GoogleSafeBrowsingV2_description.md command_examples.txt
Download History Raw 
import pytest
from CommonServerPython import DBotScoreReliability
from GoogleSafeBrowsingV2 import Client

CLIENT_BODY = {"clientId": "Client ID", "clientVersion": "Client Version"}

HEADERS = {"Content-Type": "application/json", "Accept": "application/json"}


def create_client(proxy: bool = False, verify: bool = False, base_url="", reliability: str = DBotScoreReliability.B):
    return Client(proxy=proxy, verify=verify, base_url=base_url, reliability=reliability, params={})


def test_build_request_body():
    """
    Given:
        - request body for the API request

    When:
        - we build the request according to the client body and the urls

    Then:
        - validating that the request body is as expected
    """
    urls = ["www.test.com", "www.test1.com"]

    client = create_client()

    request_body = client.build_request_body(CLIENT_BODY, urls)

    assert request_body == {
        "client": {"clientId": "Client ID", "clientVersion": "Client Version"},
        "threatInfo": {
            "platformTypes": ["ANY_PLATFORM", "WINDOWS", "LINUX", "ALL_PLATFORMS", "OSX", "CHROME", "IOS", "ANDROID"],
            "threatEntries": [{"url": "www.test.com"}, {"url": "www.test1.com"}],
            "threatEntryTypes": ["URL"],
            "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING", "POTENTIALLY_HARMFUL_APPLICATION", "UNWANTED_SOFTWARE"],
        },
    }


def test_arrange_results_to_urls():
    """
    Given:
        - response data to arrange

    When:
        - we arrange the response according to the urls

    Then:
        - validating that the results is as expected
    """
    from GoogleSafeBrowsingV2 import arrange_results_to_urls

    urls = ["www.test.com", "www.test1.com"]
    result = [
        {
            "threatType": "MALWARE",
            "platformType": "ANY_PLATFORM",
            "threat": {"url": "www.test.com"},
            "cacheDuration": "300s",
            "threatEntryType": "URL",
        }
    ]

    results_urls_data = arrange_results_to_urls(result, urls)

    assert results_urls_data == {
        "www.test.com": [
            {
                "cacheDuration": "300s",
                "platformType": "ANY_PLATFORM",
                "threat": {"url": "www.test.com"},
                "threatEntryType": "URL",
                "threatType": "MALWARE",
            }
        ],
        "www.test1.com": [],
    }


def test_handle_errors():
    """
    Given:
        - Handle errors function to return understandable error massage

    When:
        - the response contain error

    Then:
        - validating that the error massage is as expected
    """
    from GoogleSafeBrowsingV2 import handle_errors

    with pytest.raises(Exception) as e:
        handle_errors({"StatusCode": 250})
    assert str(e.value) == "Failed to perform request, request status code: 250."

    with pytest.raises(Exception) as e:
        handle_errors({"StatusCode": 204, "Body": ""})
    assert str(e.value) == "No content received. Possible API rate limit reached."

    with pytest.raises(Exception) as e:
        handle_errors({"Body": ""})
    assert str(e.value) == "No content received. Maybe you tried a private API?."

    with pytest.raises(Exception) as e:
        handle_errors({"error": {"message": "massage", "code": "code"}})
    assert str(e.value) == "Failed accessing Google Safe Browsing APIs. Error: massage. Error code: code"


URL_RESPONSE = {
    "matches": [
        {
            "threatType": "MALWARE",
            "platformType": "ANY_PLATFORM",
            "threat": {"url": "benign.com"},
            "cacheDuration": "300s",
            "threatEntryType": "URL",
        },
        {
            "threatType": "MALWARE",
            "platformType": "WINDOWS",
            "threat": {"url": "malicious.com"},
            "cacheDuration": "300s",
            "threatEntryType": "URL",
        },
    ]
}

URL_CONTENTS = [
    {
        "cacheDuration": "300s",
        "platformType": "ANY_PLATFORM",
        "threat": {"url": "benign.com"},
        "threatEntryType": "URL",
        "threatType": "MALWARE",
    }
]


def test_command_url(mocker):
    """
    Given:
        - A url to check

    When:
        - Running the url_command and mocking a malicious response

    Then:
        - validating that the IOC score is as expected
        - validating the the Reliability is as expected
        - validating the the Contents is as expected
    """
    from GoogleSafeBrowsingV2 import url_command

    client = create_client(base_url="https://safebrowsing.googleapis.com/v4/threatMatches:find")
    mocker.patch.object(client, "_http_request", return_value=URL_RESPONSE)

    url_command = url_command(client, {"url": ["benign.com", "malicious.com"]})

    # validate score
    output = url_command[0].to_context().get("EntryContext", {})
    dbot_key = "DBotScore(val.Indicator && val.Indicator == obj.Indicator && val.Vendor == obj.Vendor && val.Type == obj.Type)"
    assert output.get(dbot_key, [])[0].get("Score") == 3
    assert output.get(dbot_key, [])[0].get("Reliability") == DBotScoreReliability.B
    assert url_command[0].to_context().get("Contents") == URL_CONTENTS


def test_url_not_found(mocker):
    """
        Given:
        - A url to check with no results

    When:
        - Running the url_command and mocking no results

    Then:
        - validating that the IOC score is as expected
        - validating the the Reliability is as expected
        - validating the the Contents is as expected
    """
    from GoogleSafeBrowsingV2 import url_command

    client = create_client(base_url="https://safebrowsing.googleapis.com/v4/threatMatches:find")
    mocker.patch.object(client, "_http_request", return_value={})

    url_command = url_command(client, {"url": ["test.com"]})
    # print(url_command.to_context())
    output = url_command.to_context().get("EntryContext", {})
    dbot_key = "DBotScore(val.Indicator && val.Indicator == obj.Indicator && val.Vendor == obj.Vendor && val.Type == obj.Type)"
    assert output.get(dbot_key, [])[0].get("Score") == 0
    assert output.get(dbot_key, [])[0].get("Reliability") == DBotScoreReliability.B
    assert url_command.readable_output == "No information was found for url ['test.com']"