Nbensalmon/ciac 13043/collection extrahop reveal x

Packs/ExtraHop/Integrations/ExtrahopRevealXEventCollector/ExtrahopRevealXEventCollector.yml

@@ -0,0 +1,84 @@
+category: Analytics & SIEM
+sectionorder:
+- Connect
+- Collect
+commonfields:
+  id: ExtrahopRevealXEventCollector
+  version: -1
+configuration:
+- display: Server URL
+  name: server_url
+  required: true
+  type: 0
+  section: Connect
+- additionalinfo: The Client Credentials (ID, Secret) generated on your ExtraHop system that is required for authentication if connecting to ExtraHop Reveal(x) 360.
+  displaypassword: Client Secret
+  display: Client ID
+  name: credentials
+  required: true
+  type: 9
+  section: Connect
+- display: Trust any certificate (not secure)
+  name: insecure
+  required: false
+  type: 8
+  section: Collect
+  advanced: true
+- display: Use system proxy settings
+  name: proxy
+  required: false
+  type: 8
+  section: Collect
+  advanced: true
+- display: Fetch events
+  name: isFetchEvents
+  type: 8
+  section: Collect
+  required: false
+  hidden:
+  - xsoar
+  defaultvalue: "true"
+- additionalinfo: 'Defines the maximum number of audits events per fetch cycle. Default value: 25000.'
+  defaultvalue: "25000"
+  display: Maximum number of events per fetch
+  name: max_events_per_fetch
+  required: true
+  type: 0
+  section: Collect
+  advanced: true
+description: ExtraHop Reveal(x) is a network detection and response solution that provides complete visibility of network communications at enterprise scale, real-time threat detections backed by machine learning, and guided investigation workflows that simplify response.
+display: ExtraHop Reveal(x) Event Collector
+name: ExtrahopRevealXEventCollector
+supportlevelheader: xsoar
+script:
+  commands:
+  - name: revealx-get-events
+    description: Retrieves a list of audit logs events from the Extrahop RevealX instance.
+    arguments:
+      - auto: PREDEFINED
+        defaultValue: 'false'
+        description: Set this argument to true in order to create events, otherwise it will only display them.
+        name: should_push_events
+        predefined:
+          - 'true'
+          - 'false'
+        required: true
+      - description: Returns no more than the specified number of detections.
+        name: limit
+        required: false
+      - description: "The UTC date or relative timestamp from where to start fetching incidents
+                      Supported formats: N minutes, N hours, N days, N weeks, N months, N years, yyyy-mm-dd, yyyy-mm-ddTHH:MM:SSZ."
+        name: first_fetch
+        required: false
+  isfetch: false
+  runonce: false
+  script: '-'
+  type: python
+  subtype: python3
+  isfetchevents: true
+  dockerimage: demisto/python3:3.12.8.1983910
+fromversion: 6.10.0
+marketplaces:
+- marketplacev2
+tests:
+- No tests (auto formatted)

Packs/ExtraHop/Integrations/ExtrahopRevealXEventCollector/ExtrahopRevealXEventCollector_description.md

@@ -0,0 +1,19 @@
+## Configure an instance for ExtraHop Reveal(x)
+
+### How to create REST API Credentials:
+* You must have system and access administration privileges.
+1. Log in to RevealX 360.
+2. Click the System Settings icon - at the top right of the page and then click All Administration.
+3. Click API Access.
+4. Click Create Credentials.
+5. In the Name field, type a name for the credentials.
+6. In the Privileges field, specify a privilege level for the credentials. The privilege level determines which actions can be performed with the credential. Do not grant more privileges to REST API credentials than needed because it can create a security risk. For example, applications that only retrieve metrics should not be granted credentials that grant administrative privileges. For more information about each privilege level, see User privileges. 
+* Note: System and Access Administration privileges are similar to Full write privileges and allow the credentials to connect sensors and Trace appliances to RevealX 360.*
+7. In the Packet Access field, specify whether you can retrieve packets and session keys with the credentials.
+8. Click Save. The Copy REST API Credentials pane appears.
+9. Under ID, click Copy to Clipboard and save the ID to your local machine.
+10. Under Secret, click Copy to Clipboard and save the secret to your local machine.
+11. Click Done.
+
+
+

Packs/ExtraHop/Integrations/ExtrahopRevealXEventCollector/ExtrahopRevealXEventCollector_test.py

@@ -0,0 +1,130 @@
+import pytest
+
+from ExtrahopRevealXEventCollector import Client
+from CommonServerPython import *
+
+MOCK_BASEURL = "https://example.com"
+MOCK_CLIENT_ID = "ID"
+MOCK_CLIENT_SECRET = "SECRET"
+OK_CODES = (200, 201, 204)
+
+
+def util_load_json(path):
+    with open(path, encoding="utf-8") as f:
+        return json.loads(f.read())
+
+
+@pytest.fixture
+def client():
+    return Client(
+        base_url=MOCK_BASEURL,
+        verify=False,
+        client_id=MOCK_CLIENT_ID,
+        client_secret=MOCK_CLIENT_SECRET,
+        use_proxy=False,
+        ok_codes=OK_CODES
+    )
+
+
+def test_update_time_values_detections():
+    """
+    Given: A mock raw response containing detections logs.
+    When: Updating time fields
+    Then: Ensure the events are added the new time fields
+    """
+    from ExtrahopRevealXEventCollector import update_time_values_detections
+    raw_detections = util_load_json("test_data/detections-dummy.json")
+    update_time_values_detections(raw_detections)
+
+    for detection in raw_detections:
+        assert "_TIME" in detection
+        assert "_ENTRY_STATUS" in detection
+
+
+
+def test_fetch_events_update_last_run(client, mocker):
+    """
+    Given: A mock raw response containing detections logs.
+    When: fetching events.
+    Then: Make sure that the last run object was updated as expected
+    """
+    from ExtrahopRevealXEventCollector import fetch_events
+    raw_detections = util_load_json("test_data/detections-dummy.json")
+    mocker.patch("ExtrahopRevealXEventCollector.Client.detections_list", return_value=raw_detections)
+
+    output, new_last_run = fetch_events(client, last_run={}, max_events=len(raw_detections))
+
+    assert len(output) == 5
+    assert new_last_run.get("offset") == 0
+    assert new_last_run.get("detection_start_time") == raw_detections[-1]["mod_time"] + 1
+
+
+def test_fetch_events_already_fetched(client, mocker):
+    """
+    Given: A mock raw response containing detections events.
+    When: Fetching events that was already fetched
+    Then: Ensure the function does not return any events
+    """
+    from ExtrahopRevealXEventCollector import fetch_events
+    raw_detections = util_load_json("test_data/detections-dummy.json")
+    mocker.patch("ExtrahopRevealXEventCollector.Client.detections_list", return_value=raw_detections)
+
+    mock_already_fetched = [d["id"] for d in raw_detections]
+    last_run_mock = {"already_fetched": mock_already_fetched}
+
+    output, new_last_run = fetch_events(client, last_run=last_run_mock, max_events=len(raw_detections))
+
+    assert len(output) == 0
+    assert new_last_run.get("already_fetched") == mock_already_fetched
+
+
+def test_fetch_events_reaching_limit(client, mocker):
+    """
+    Given: A mock raw response containing detections events.
+    When: Fetching events with a fetch limit higher than the number of available logs.
+    Then: Ensure the function returns exactly the requested number of events and updates the last run timestamp correctly.
+    """
+    from ExtrahopRevealXEventCollector import fetch_events
+    raw_detections = util_load_json("test_data/detections-dummy.json")[:-2]
+    mocker.patch("ExtrahopRevealXEventCollector.Client.detections_list", return_value=raw_detections)
+
+    output, new_last_run = fetch_events(client, last_run={}, max_events=len(raw_detections) + 2)
+
+    assert len(output) == len(raw_detections)
+    assert new_last_run.get("detection_start_time") == raw_detections[-1]["mod_time"] + 1
+
+
+def test_fetch_events_more_than_exist(client, mocker):
+    """
+    Given: A mock raw response containing detections events.
+    When: Fetching events with a fetch limit smaller than the number of available logs.
+    Then: Ensure the function returns exactly the requested number of events and updates the last run timestamp correctly.
+    """
+    from ExtrahopRevealXEventCollector import fetch_events
+    raw_detections = util_load_json("test_data/detections-dummy.json")
+    mocker.patch("ExtrahopRevealXEventCollector.Client.detections_list", return_value=raw_detections)
+
+    output, new_last_run = fetch_events(client, last_run={}, max_events=len(raw_detections) - 2)
+
+    assert len(output) == len(raw_detections) - 2
+    assert new_last_run.get("detection_start_time") == raw_detections[-3]["mod_time"] + 1
+
+
+def test_fetch_events_same_mod_time(client, mocker):
+    """
+    Given: A mock raw response containing detections events.
+    When: Fetching events with a fetch limit less than the number of available logs and they all have the same mod_time
+    Then: Ensure the function returns exactly the requested number of events and updates the last run timestamp correctly.
+    """
+    from ExtrahopRevealXEventCollector import fetch_events
+    raw_detections = util_load_json("test_data/detections-dummy.json")
+    mod_time_all = 1000
+    for d in raw_detections:
+        d["mod_time"] = mod_time_all
+
+    mocker.patch("ExtrahopRevealXEventCollector.Client.detections_list", return_value=raw_detections)
+
+    output, new_last_run = fetch_events(client, last_run={}, max_events=len(raw_detections) - 2)
+
+    assert len(output) == len(raw_detections) - 2
+    assert new_last_run.get("detection_start_time") == mod_time_all

Packs/ExtraHop/Integrations/ExtrahopRevealXEventCollector/README.md

@@ -0,0 +1,59 @@
+ExtraHop Reveal(x) is a network detection and response solution that provides complete visibility of network communications at enterprise scale, real-time threat detections backed by machine learning, and guided investigation workflows that simplify response.
+#### This integration works with ExtraHop firmware version greater than or equal to 9.3.0
+
+## Configure an instance for ExtraHop Reveal(x)
+
+### How to create REST API Credentials:
+* You must have system and access administration privileges.
+1. Log in to RevealX 360.
+2. Click the System Settings icon - at the top right of the page and then click All Administration.
+3. Click API Access.
+4. Click Create Credentials.
+5. In the Name field, type a name for the credentials.
+6. In the Privileges field, specify a privilege level for the credentials. The privilege level determines which actions can be performed with the credential. Do not grant more privileges to REST API credentials than needed because it can create a security risk. For example, applications that only retrieve metrics should not be granted credentials that grant administrative privileges. For more information about each privilege level, see User privileges. 
+* Note: System and Access Administration privileges are similar to Full write privileges and allow the credentials to connect sensors and Trace appliances to RevealX 360.*
+7. In the Packet Access field, specify whether you can retrieve packets and session keys with the credentials.
+8. Click Save. The Copy REST API Credentials pane appears.
+9. Under ID, click Copy to Clipboard and save the ID to your local machine.
+10. Under Secret, click Copy to Clipboard and save the secret to your local machine.
+11. Click Done.
+
+
+## Configure ExtraHop Reveal(x) in Cortex
+
+
+| **Parameter** | **Description** | **Required** |
+| --- | --- | --- |
+| Your server URL |  | True |
+| Client Id | The client ID generated on your ExtraHop system that is required for authentication if connecting to ExtraHop Reveal\(x\) 360. | True |
+| Client Secret | The client secret generated on your ExtraHop system that is required for authentication if connecting to ExtraHop Reveal\(x\) 360. | True |
+| Trust any certificate (not secure) |  | False |
+| Use system proxy settings |  | False |
+| Fetch events |  | False |
+| Maximum number of events per fetch | Defines the maximum number of audits events per fetch cycle. Default value: 25000. | True |
+
+## 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.
+
+### revealx-get-events
+
+***
+Retrieves a list of audit logs events from the Extrahop RevealX instance.
+
+#### Base Command
+
+`revealx-get-events`
+
+#### Input
+
+| **Argument Name** | **Description** | **Required** |
+| --- | --- | --- |
+| should_push_events | Set this argument to true in order to create events, otherwise it will only display them. Possible values are: true, false. Default is false. | Required | 
+| max_events | Returns no more than the specified number of detections. | Optional | 
+
+#### Context Output
+
+There is no context output for this command.
+

Packs/ExtraHop/Integrations/ExtrahopRevealXEventCollector/command_examples.txt

@@ -0,0 +1 @@
+!revealx-get-events should_push_events=false limit=10 first_fetch="1 days"