Zerohack XDR

The companion integration for Zerohack XDR. Current versions allow the user to collect data from the XDR and later versions will support data exfiltration to XDR.

Network Security · Zerohack XDR

Details

IDZerohack XDR
ProviderZerohack
CategoryNetwork Security
From Version5.0.0
Docker Imagedemisto/python3:3.12.13.10116658
Supported ModulesAgentix XSIAM

README

Integration and Setup Instructions

The companion integration for Zerohack XDR.
Current versions allow the user to collect data from the XDR and later versions will support data exfiltration to XDR.
This integration was integrated and tested with version 1.0 of Zerohack XDR

Create API key on Zerohack XDR for Cortex XSOAR

  1. Navigate to Side Panel > Administration > Integration > Key Management.

    Setup Account

  2. Click on Create API key.

    Setup Account

  3. Click on Drop down of Select application.

    Setup Account

  4. Click on Palo Alto XSOAR.

    Setup Account

  5. Select API Type “Full Control”.

    Setup Account

  6. Click on Create Api.

    Setup Account

  7. Copy your API key.

    Setup Account

Configure Zerohack XDR on Cortex XSOAR

  1. Navigate to Settings on bottom left corner of dashboard > Integrations > Servers & Services.

Setup Account

  1. Search for Zerohack XDR.

Setup Account

  1. Click Add instance to create and configure a new integration instance.

    Setup Account

    Parameter Description Required
    Fetch incidents   False
    Incident type   False
    Maximum number of incidents per fetch This number determines how many incidents must be fetched with each API call. It is suggested you keep it below 100. False
    Zerohack XDR API Key This API key can be generated from your zerohack XDR account. Please ensure that you fill this field before you test the integration. True
    First fetch time This parameter decides how many old events you want to fetch when starting the integration. False
    Trust any certificate (not secure)   False
    Incidents Fetch Interval   True
    Minimum Severity This parameter defines the lowest severity level (xdr) to use for fetching incidents. True
  2. Click on Gear Icon.

Setup Account

  1. Click Test to validate the URLs, token, and connection.

Setup Account

  1. Access the Fetch results.

Setup Account

Setup Account

Commands

You can execute these commands from the Cortex XSOAR 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.

zerohack-get-latest-incident


Fetch a single incident of your choice of severity level to study the incidents structure before you start continously fecthing incidents.

Base Command

zerohack-get-latest-incident

Input

Argument Name Description Required
severity_level The severity level helps in extracting latest incident of a specific severity. Required

Setup Account

Context Output

"message_type": "success",
"data_len": 1,
"data": [
    {
        "tcp_port": "22.0",
        "ip_rep": "unknown",
        "dl_threat_class": "Potentially Bad Traffic",
        "ml_severity": 2,
        "attacker_mac": "ff:ff:ff:ff:ff:ff",
        "geoip_region_name": null,
        "target_mac_address": "ff:ff:ff:ff:ff:ff",
        "geoip_postal_code": null,
        "timezone": "UTC-0.0",
        "dl_severity": 2,
        "geoip_asn_number": null,
        "platform": "aws",
        "attack_os": "Linux 2.2.x-3.x",
        "ids_threat_severity": 2.0,
        "geoip_country_name": null,
        "packet_id": 464887,
        "attacker_ip": "8.8.8.8",
        "geoip_location_properties": null,
        "udp_port": "nan",
        "geoip_longitude": null,
        "geoip_location_string": null,
        "service_name": "TCP",
        "geoip_latitude": null,
        "ids_threat_type": "ET SCAN Potential SSH Scan OUTBOUND",
        "ml_accuracy": 82,
        "attack_epoch_time": 1662120908000,
        "type_of_threat": "Lateral Movement",
        "ml_threat_class": "Misc Attack",
        "target_os": "Linux 2.2.x-3.x",
        "@timestamp": "2022-09-02 12:18:26.22009012",
        "attack_timestamp": "2022-09-02 12:15:08",
        "target_ip": "8.8.8.8",
        "dl_accuracy": 80,
        "geoip_city": null,
        "geoip_region_code": null,
        "ids_threat_class": "Attempted Information Leak",
        "icmp_port": null,
        "geoip_location_array": null,
        "geoip_country_code": null,
        "geoip_asn_name": null
    }
]

Setup Account

Configuration parameters

  • isFetch — Fetch incidents
  • incidentType — Incident type
  • max_fetch — Maximum number of incidents per fetch
  • apikey — Zerohack XDR API Key (required)
  • first_fetch — First fetch time
  • insecure — Trust any certificate (not secure)
  • incidentFetchInterval — Incidents Fetch Interval (required)
  • min_severity — Minimum Severity (required)

Commands (1)

  • zerohack-get-latest-incident

    Fetch a single incident of your choice of severity level to study the incidents structure before you start continously fecthing incidents.

# Tests verified with pytest -vv as demisto-sdk didnt work.
# Test records are present in the test_data directory.
# Kept here for future reference.

# Coverage
# --------
# There should be at least one unit test per command function. In each unit
# test, the target command function is executed with specific parameters and the
# output of the command function is checked against an expected output.
# Unit tests should be self contained and should not interact with external
# resources like (API, devices, ...). To isolate the code from external resources
# you need to mock the API of the external resource using pytest-mock:
# https://github.com/pytest-dev/pytest-mock/
# In the following code we configure requests-mock (a mock of Python requests)
# before each test to simulate the API calls to the HelloWorld API. This way we
# can have full control of the API behavior and focus only on testing the logic
# inside the integration code.
# We recommend to use outputs from the API calls and use them to compare the
# results when possible. See the ``test_data`` directory that contains the data
# we use for comparison, in order to reduce the complexity of the unit tests and
# avoding to manually mock all the fields.
# NOTE: we do not have to import or build a requests-mock instance explicitly.
# requests-mock library uses a pytest specific mechanism to provide a
# requests_mock instance to any function with an argument named requests_mock.

# Note: The test module function has not been added to these set of tests as it is only used for checking if the
#       connection with Zerohack XDR is working correctly.
import json


def util_load_json(path):
    with open(path) as file:
        text = file.read()
        return json.loads(text)


def test_get_latest_incident(requests_mock):
    from ZerohackXDR import ZEROHACK_XDR_API_BASE_URL, Client, get_latest_incident

    # Initialising the client.
    client = Client(
        base_url=ZEROHACK_XDR_API_BASE_URL,
        verify=False,
        api_key="Some Random Key",
        proxy=False,
    )

    mock_response = util_load_json("test_data/get_latest_incident.json")

    requests_mock.register_uri("GET", f"{ZEROHACK_XDR_API_BASE_URL}/xdr-api", json=mock_response)
    incident = get_latest_incident(client, severity_level=4)
    assert isinstance(incident, dict)


def test_fetch_incidents(requests_mock):
    from ZerohackXDR import ZEROHACK_SEVERITIES, ZEROHACK_XDR_API_BASE_URL, Client, fetch_incidents

    # Initialising the client.
    client = Client(
        base_url=ZEROHACK_XDR_API_BASE_URL,
        verify=False,
        api_key="Some Random Key",
        proxy=False,
    )
    min_severity = "4"
    severity_levels = ZEROHACK_SEVERITIES[ZEROHACK_SEVERITIES.index(min_severity) :]
    max_results_per_severity = 10
    mock_responses = util_load_json("test_data/fetch_incidents.json")

    responses_list = []
    for response in mock_responses:
        responses_list.append({"text": json.dumps(response)})

    last_run = {"last_fetch": 1662120898}

    requests_mock.register_uri("GET", f"{ZEROHACK_XDR_API_BASE_URL}/xdr-api", responses_list)

    next_run, incidents = fetch_incidents(
        client=client,
        max_results=max_results_per_severity,
        min_severity=min_severity,
        last_run=last_run,
        first_fetch="1 day",
    )
    # Type checks.
    assert isinstance(next_run, dict)
    assert isinstance(incidents, list)
    # Bound checks.
    assert len(incidents) <= max_results_per_severity * len(severity_levels)


def test_convert_to_demisto_severity():
    from ZerohackXDR import convert_to_demisto_severity

    severity_level = convert_to_demisto_severity("3.0")
    assert isinstance(severity_level, int)
    assert severity_level == 2

    severity_level = convert_to_demisto_severity("4.0")
    assert isinstance(severity_level, float)
    assert severity_level == 0.5

    severity_level = convert_to_demisto_severity("2.0")
    assert isinstance(severity_level, int)
    assert severity_level == 3

    severity_level = convert_to_demisto_severity("1.0")
    assert isinstance(severity_level, int)
    assert severity_level == 4


def test_main():
    from ZerohackXDR import main

    output = main()

    assert output is None


def test_test_module(requests_mock):
    from ZerohackXDR import ZEROHACK_XDR_API_BASE_URL, Client, test_module

    # Initialising the client.
    client = Client(
        base_url=ZEROHACK_XDR_API_BASE_URL,
        verify=False,
        api_key="Some Random Key",
        proxy=False,
    )

    mock_response = util_load_json("test_data/get_latest_incident.json")

    requests_mock.register_uri("GET", f"{ZEROHACK_XDR_API_BASE_URL}/xdr-api", json=mock_response)
    assert test_module(client) == "ok"