DarktraceEmail

Details

ID	`DarktraceEmail`
Provider	Thoma Bravo
Category	Network Security
From Version	6.10.0
Docker Image	`demisto/python3:3.12.13.10116658`
Supported Modules	Agentix XSIAM

README

This pack includes configurations to combine the world-class threat detection of Darktrace with the synchrony and automation abilities of XSOAR, allowing security teams to investigate critical incidents along with accompanying summaries and timelines.
This integration was integrated and tested with version 6.2 of DarktraceEmail.

Configure DarktraceEmail in Cortex

Parameter	Description	Required
Server URL (e.g. https://example.net)		True
Fetch incidents		False
Trust any certificate (not secure)		False
Use system proxy settings		False
Incident type		False
Public API Token	Public token obtained by creating an API token pair on the /config configuration page.	True
Private API Token	Private token obtained by creating an API token pair on the /config configuration page.	True
Minimum Score	Minimum Darktrace score for fetched incidents (0-100).	True
Maximum Emails per Fetch	Maximum number of Darktrace Emails to fetch at a time.	False
First fetch time	Time to start fetching the first incidents. Default is to begin fetching 1 day ago. Max number of model breaches that will be populated upon first fetch is 20.	False
Incidents Fetch Interval		False
Darktrace Tag Severity	Fetches Emails with any tags of the desired severity level, filtering is inclusive. By default fetches all severity levels.	False
Only Actioned Emails	Only fetch Emails that have been actioned. Disabled by default.	False
Direction	Fetch emails based on direction; either inbound, outbound or internal. By default fetches all directions.	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.

darktrace-email-get-email

Fetch details about a specific Email.

Base Command

darktrace-email-get-email

Input

Argument Name	Description	Required
uuid	Darktrace UUID of the Email.	Required

Context Output

Path	Type	Description
Darktrace.Email.uuid	string	UUID of email.
Darktrace.Email.direction	string	Direction of email.
Darktrace.Email.dtime	string	Timestamp of email.
Darktrace.Email.header_from_email	string	Email address of sender.
Darktrace.Email.header_subject	string	Subject of email.
Darktrace.Email.model_score	number	Anomaly score of email.
Darktrace.Email.receipt_status	string	Receipt status of email.

darktrace-email-hold-email

Apply “hold” action to a specified Email.

Base Command

darktrace-email-hold-email

Input

Argument Name	Description	Required
uuid	Unique ID of Email.	Required

Context Output

Path	Type	Description
Darktrace.Action.resp	string	Status of the hold action.

darktrace-email-release-email

Apply “release” action to a specified Email.

Base Command

darktrace-email-release-email

Input

Argument Name	Description	Required
uuid	Unique ID of Email.	Required
recipient	Recipient of Email. Not required but speeds up the command.	Optional

Context Output

Path	Type	Description
Darktrace.Action.resp	string	Status of the release action.

Configuration parameters

url — Server URL (e.g. https://example.net) (required)
isFetch — Fetch incidents
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings
incidentType — Incident type
publicApiKey — Public API Token (required)
privateApiKey — Private API Token (required)
min_score — Minimum Score (required)
max_fetch — Maximum Emails per Fetch
first_fetch — First fetch time
incidentFetchInterval — Incidents Fetch Interval
tag_severity — Darktrace Tag Severity
actioned — Only Actioned Emails
direction — Direction

Commands (3)

darktrace-email-get-email
Fetch details about a specific Email.
darktrace-email-hold-email
Apply "hold" action to a specified Email.
darktrace-email-release-email
Apply "release" action to a specified Email.

Source

DarktraceEmail.py DarktraceEmail_test.py DarktraceEmail.yml DarktraceEmail_description.md

Download History Raw

import json


from DarktraceEmail import Client, get_email_command, release_email_command, hold_email_command, fetch_incidents


"""*****HELPER FUNCTIONS****"""


def util_load_json(path):
    with open(path, encoding="utf-8") as f:
        return json.loads(f.read())


"""*****TEST FUNCTIONS****"""


def test_get_email(requests_mock):
    """
    Given
            Integration queries Darktrace Email for single email
    When
            Calling the darktrace-email-get-email command with a specific email UUID
    Then
            Email object is returned
    """
    uuid = "BA13B274-03F3-46D6-8698-244DFF1037A0.1"

    mock_api_response = util_load_json("test_data/get_email.json")
    requests_mock.get(f"https://mock.darktrace.com/agemail/api/v1.0/emails/{uuid}", json=mock_api_response)

    mock_api_response_tags = util_load_json("test_data/get_tags.json")
    requests_mock.get("https://mock.darktrace.com/agemail/api/v1.0/resources/tags", json=mock_api_response_tags)

    client = Client(base_url="https://mock.darktrace.com", verify=False, auth=("examplepub", "examplepri"))
    client.get_tag_mapper()

    integration_response = get_email_command(client, args={"uuid": uuid})
    expected_response = util_load_json("test_data/formatted_get_email.json")

    assert integration_response.outputs == expected_response
    assert integration_response.outputs_prefix == "Darktrace.Email"
    assert integration_response.outputs_key_field == "uuid"


def test_release_email(requests_mock):
    """
    Given
            Integration attempts to release an email that has been held
    When
            Calling the darktrace-email-release-email command with a specific email UUID
    Then
            Response to release request is returned
    """
    uuid = "BA13B274-03F3-46D6-8698-244DFF1037A0.1"
    recipient = "leeroy.jenkins@example.com"

    mock_api_response = util_load_json("test_data/release_email.json")
    requests_mock.post(f"https://mock.darktrace.com/agemail/api/v1.0/emails/{uuid}/action", json=mock_api_response)

    client = Client(base_url="https://mock.darktrace.com", verify=False, auth=("examplepub", "examplepri"))

    integration_response = release_email_command(client, args={"uuid": uuid, "recipient": recipient})
    expected_response = util_load_json("test_data/formatted_release_email.json")

    assert integration_response.outputs == expected_response
    assert integration_response.outputs_prefix == "Darktrace.Action"
    assert integration_response.outputs_key_field == "resp"


def test_hold_email(requests_mock):
    """
    Given
            Integration attempts to hold an email
    When
            Calling the darktrace-email-hold-email command with a specific email UUID
    Then
            Response to hold request is returned
    """
    uuid = "BA13B274-03F3-46D6-8698-244DFF1037A0.1"
    recipient = "leeroy.jenkins@example.com"

    mock_api_response_get_email = util_load_json("test_data/get_email.json")
    requests_mock.get(f"https://mock.darktrace.com/agemail/api/v1.0/emails/{uuid}", json=mock_api_response_get_email)

    mock_api_response = util_load_json("test_data/hold_email.json")
    requests_mock.post(f"https://mock.darktrace.com/agemail/api/v1.0/emails/{uuid}/action", json=mock_api_response)

    client = Client(base_url="https://mock.darktrace.com", verify=False, auth=("examplepub", "examplepri"))

    integration_response = hold_email_command(client, args={"uuid": uuid, "recipient": recipient})
    expected_response = util_load_json("test_data/formatted_hold_email.json")

    assert integration_response.outputs == expected_response
    assert integration_response.outputs_prefix == "Darktrace.Action"
    assert integration_response.outputs_key_field == "resp"


def test_fetch_incidents(requests_mock):
    """
    Given
            Integration pulls in incidents from ASM
    When
            Regular interval defined by user, default is one minute
    Then
            Incident info will be formatted for XSOAR UI and required info for next call will be returned
    """
    uuid_01 = "74AADFDC-33A9-4065-ACFC-B2493E8722BF.1"
    uuid_02 = "8EEFBFA4-6CA2-4306-B688-BA6B9F60AEEF.1"

    mock_api_response_incident_01 = util_load_json("test_data/incident_01.json")
    requests_mock.get(
        f"https://mock.darktrace.com/agemail/api/v1.0/emails/{uuid_01}?dtime=1744300527341", json=mock_api_response_incident_01
    )

    mock_api_response_incident_02 = util_load_json("test_data/incident_02.json")
    requests_mock.get(
        f"https://mock.darktrace.com/agemail/api/v1.0/emails/{uuid_02}?dtime=1744300434119", json=mock_api_response_incident_02
    )

    mock_api_response_get_email = util_load_json("test_data/fetch_incidents.json")
    requests_mock.post("https://mock.darktrace.com/agemail/api/v1.0/emails/search", json=mock_api_response_get_email)

    mock_api_response_tags = util_load_json("test_data/get_tags.json")
    requests_mock.get("https://mock.darktrace.com/agemail/api/v1.0/resources/tags", json=mock_api_response_tags)

    client = Client(base_url="https://mock.darktrace.com", verify=False, auth=("examplepub", "examplepri"))
    client.get_tag_mapper()

    last_run = {
        "last_fetch": 1598932817000  # Mon, Aug 31, 2020 9 PM Pacific
    }

    _, integration_response = fetch_incidents(
        client,
        max_alerts=20,
        last_run=last_run,
        first_fetch_time="1 day ago",
        min_score=20,
        tag_severity=["Critical", "Warning", "Informational"],
        actioned=False,
        direction=False,
    )

    expected_response = util_load_json("test_data/formatted_fetch_incidents.json")

    assert integration_response == expected_response
    assert len(integration_response) == 2