DarktraceAIA

Rapid detection of malicious behaviour can make all the difference in the response to a security event. 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. AI actions can also be applied.

Network Security · Darktrace

Details

IDDarktraceAIA
ProviderThoma Bravo
CategoryNetwork Security
From Version6.6.0
Docker Imagedemisto/python3:3.12.13.10116658
Supported ModulesAgentix XSIAM

README

Darktrace is a Cyber AI platform for threat detection and response across cloud, email, industrial, and the network.
This integration was integrated and tested with version 6.0.0 of Darktrace

Configure Darktrace in Cortex

Parameter Description Required
url Server URL (e.g. https://example.net) True
isFetch Fetch incidents False
insecure Trust any certificate (not secure) False
proxy Use system proxy settings False
public_api_token Public API Token True
private_api_token Private API Token True
min_score Minimum Score True
max_alerts Maximum Model Breaches per Fetch False
first_fetch First fetch time 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-get-ai-analyst-incident-event


Returns all AI Analyst incident events

Base Command

darktrace-get-ai-analyst-incident-event

Input

Argument Name Description Required
eventId Unique identified of an AI Analyst incident event Required

Context Output

Path Type Description
Darktrace.AIAnalyst.eventId Unknown AIAnalyst unique identifier
Darktrace.AIAnalyst.title String AIAnalyst event title
Darktrace.AIAnalyst.mitreTactics Unknown AIAnalyst mitre tactics seen on event
Darktrace.AIAnalyst.score Unknown group score for ai analyst incident
Darktrace.AIAnalyst.category String group category for ai analyst incident
Darktrace.AIAnalyst.summary String AIAnalyst event summary
Darktrace.AIAnalyst.groupId Unknown unique identifier for event Id
Darktrace.AIAnalyst.devices Unknown Associated devices with incident event
Darktrace.AIAnalyst.modelBreaches Unknown Associated model breaches with event Id

darktrace-get-comments-for-ai-analyst-incident-event


Returns all Darktrace Comments for a given Incident Event

Base Command

darktrace-get-comments-for-ai-analyst-incident-event

Input

Argument Name Description Required
eventId Unique identified of an AI Analyst incident event Required

Context Output

Path Type Description
Darktrace.AIAnalyst.incidet_id Number Incident event unique identifier
Darktrace.AIAnalyst.message String Posted message
Darktrace.AIAnalyst.eventId String Unique event identifier
Darktrace.AIAnalyst.time String Message post timestamp
Darktrace.AIAnalyst.username String Darktrace username of posting user

darktrace-post-comment-to-ai-analyst-incident-event


Post comment to an AI Analyst Incident Event.

Base Command

darktrace-post-comment-to-ai-analyst-incident-event

Input

Argument Name Description Required
eventId Unique identified of an AI Analyst incident event Required
comment Enter a message to comment Required

Context Output

Path Type Description
Darktrace.AIAnalyst.commented String Whether the incident is commented in Darktrace
Darktrace.AIAnalyst.response String Post command response
Darktrace.AIAnalyst.eventId String Unique event identifier
Darktrace.AIAnalyst.message String Message to be commented

darktrace-acknowledge-ai-analyst-incident-event


Acknowledges an AI Analyst Incident Event

Base Command

darktrace-acknowledge-ai-analyst-incident-event

Input

Argument Name Description Required
eventId Unique identified of an AI Analyst incident event Required

Context Output

Path Type Description
Darktrace.AIAnalyst.acknowledged String Whether the incident is acknowledge in Darktrace
Darktrace.AIAnalyst.response String Post response comment
Darktrace.AIAnalyst.eventId String incident event unique identifier

darktrace-unacknowledge-ai-analyst-incident-event


Unacknowledges an AI Analyst Incident Event

Base Command

darktrace-unacknowledge-ai-analyst-incident-event

Input

Argument Name Description Required
eventId Unique identified of an AI Analyst incident event Required

Context Output

Path Type Description
Darktrace.AIAnalyst.unacknowledged String Whether the incident is acknowledge in Darktrace
Darktrace.AIAnalyst.response String Post response comment
Darktrace.AIAnalyst.eventId String incident event unique identifier

darktrace-get-ai-analyst-incident-group-from-eventId


Pulls all linked events for a given event. Over time, events can become merged with one another. This happens when two sets of disparate activity are suddenly linked by shared factors.

Base Command

darktrace-get-ai-analyst-incident-group-from-eventId

Input

Argument Name Description Required
eventId Unique identified of an AI Analyst incident event Required

Context Output

Path Type Description
Darktrace.AIAnalyst.groupId String Investigation Group Unique Identifier
Darktrace.AIAnalyst.incidentEvents Unknown Associated events
Darktrace.AIAnalyst.mitreTactics Unknown Associated Mitre Tactics seen on incident
Darktrace.AIAnalyst.groupScore Number Group score
Darktrace.AIAnalyst.groupCategory String Group category

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
  • incidentFetchInterval — Incidents Fetch Interval
  • publicApiKey — Public API Token (required)
  • privateApiKey — Private API Token (required)
  • min_score — Minimum Score (required)
  • max_fetch — Maximum Model Breaches per Fetch
  • first_fetch — First fetch time

Commands (6)

  • darktrace-acknowledge-ai-analyst-incident-event

    Acknowledge an AI Analyst Incident Event.

  • darktrace-get-ai-analyst-incident-event

    Fetch the details of an AI Analyst event.

  • darktrace-get-ai-analyst-incident-group-from-eventId

    Pulls all linked events for a given event. Over time, events can become merged with one another. This happens when two sets of disparate activity are suddenly linked by shared factors.

  • darktrace-get-comments-for-ai-analyst-incident-event

    Fetch all comments from an AI Analyst incident Event.

  • darktrace-post-comment-to-ai-analyst-incident-event

    Post a comment to an AI Analyst incident Event.

  • darktrace-unacknowledge-ai-analyst-incident-event

    Unacknowledge an AI Analyst Incident Event.

import json


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


"""*****COMMAND FUNCTIONS****"""


def test_fetch_incidents(requests_mock):
    """Tests the fetch-incidents command function.

    Configures requests_mock instance to generate the appropriate
    get_alert API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from DarktraceAIA import Client, fetch_incidents

    # GIVEN an integration is configured and fetch incidents
    mock_response = util_load_json("test_data/incident_fetch.json")
    requests_mock.get(
        "https://usw1-51965-01.cloud.darktrace.com/aianalyst/" + "incidentevents?mingroupscore=0&starttime=1598932817000",
        json=mock_response,
    )

    client = Client(base_url="https://usw1-51965-01.cloud.darktrace.com/", verify=False, auth=("examplepub", "examplepri"))

    # WHEN the most recent call was made on Mon, Aug 31, 2020 9 PM Pacific
    last_run = {
        "last_fetch": 1598932817000  # Mon, Aug 31, 2020 9 PM Pacific
    }

    _, integration_response = fetch_incidents(
        client=client, max_alerts=20, last_run=last_run, first_fetch_time="1 day ago", min_score=0
    )

    # THEN the relevant information will be fetched and pulled
    expected_response = util_load_json("test_data/formatted_incident_fetch.json")

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


def test_get_ai_analyst_incident_event(requests_mock):
    """Tests get_ai_analyst_incident_event command function.

    Configures requests_mock instance to generate the appropriate
    get_alert API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from DarktraceAIA import Client, get_ai_analyst_incident_event_command

    # GIVEN an integration is configured and fetch incidents
    eventId = "bc64f242-ce29-4f35-bc94-230991116564"
    mock_api_response = util_load_json("test_data/ai_analyst_incident.json")
    requests_mock.get("https://mock.darktrace.com/aianalyst/incidentevents?uuid=" + eventId, json=mock_api_response)

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

    args = {
        "eventId": eventId,
    }
    integration_response = get_ai_analyst_incident_event_command(client, args)
    expected_response = util_load_json("test_data/formatted_ai_analyst_incident.json")

    assert integration_response.outputs == expected_response
    assert integration_response.outputs_prefix == "Darktrace.AIAnalyst"


def test_get_comments_for_ai_analyst_incident_event_command(requests_mock):
    """Tests get_comments_for_ai_analyst_incident_event_command command function.

    Configures requests_mock instance to generate the appropriate
    get_alert API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from DarktraceAIA import Client, get_comments_for_ai_analyst_incident_event_command

    # GIVEN an integration is configured and fetch incidents
    eventId = "bc64f242-ce29-4f35-bc94-230991116564"
    mock_api_response = util_load_json("test_data/get_comment_response.json")
    requests_mock.get("https://mock.darktrace.com/aianalyst/incident/comments?incident_id=" + eventId, json=mock_api_response)

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

    args = {
        "eventId": eventId,
    }
    integration_response = get_comments_for_ai_analyst_incident_event_command(client, args)
    expected_response = util_load_json("test_data/formatted_get_comment_response.json")

    assert integration_response.outputs == expected_response
    assert integration_response.outputs_prefix == "Darktrace.AIAnalyst"


def test_post_comment_to_ai_analyst_incident_event(requests_mock):
    """Tests post_comments_for_ai_analyst_incident_event_command command function.

    Configures requests_mock instance to generate the appropriate
    get_alert API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from DarktraceAIA import Client, post_comment_to_ai_analyst_incident_event_command

    # GIVEN an integration is configured and fetch incidents
    eventId = "bc64f242-ce29-4f35-bc94-230991116564"
    mock_api_response = util_load_json("test_data/post_comment.json")
    requests_mock.post("https://mock.darktrace.com/aianalyst/incident/comments", json=mock_api_response)

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

    args = {"eventId": eventId, "comment": "test comment"}
    integration_response = post_comment_to_ai_analyst_incident_event_command(client, args)
    expected_response = util_load_json("test_data/formatted_post_comment.json")

    assert integration_response.outputs == expected_response
    assert integration_response.outputs_prefix == "Darktrace.AIAnalyst"


def test_acknowledge_ai_analyst_incident_event(requests_mock):
    """Tests acknowledge_ai_analyst_incident_event_command command function.

    Configures requests_mock instance to generate the appropriate
    get_alert API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from DarktraceAIA import Client, acknowledge_ai_analyst_incident_event_command

    # GIVEN an integration is configured and fetch incidents
    eventId = "bc64f242-ce29-4f35-bc94-230991116564"
    mock_api_response = util_load_json("test_data/ack_response.json")
    requests_mock.post("https://mock.darktrace.com/aianalyst/acknowledge", json=mock_api_response)

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

    args = {
        "eventId": eventId,
    }
    integration_response = acknowledge_ai_analyst_incident_event_command(client, args)
    expected_response = util_load_json("test_data/formatted_ack.json")

    assert integration_response.outputs == expected_response
    assert integration_response.outputs_prefix == "Darktrace.AIAnalyst"


def test_unacknowledge_ai_analyst_incident_event_command(requests_mock):
    """Tests acknowledge_ai_analyst_incident_event_command command function.

    Configures requests_mock instance to generate the appropriate
    get_alert API response, loaded from a local JSON file. Checks
    the output of the command function with the expected output.
    """
    from DarktraceAIA import Client, unacknowledge_ai_analyst_incident_event_command

    # GIVEN an integration is configured and fetch incidents
    eventId = "bc64f242-ce29-4f35-bc94-230991116564"
    mock_api_response = util_load_json("test_data/unack_response.json")
    requests_mock.post("https://mock.darktrace.com/aianalyst/unacknowledge", json=mock_api_response)

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

    args = {
        "eventId": eventId,
    }
    integration_response = unacknowledge_ai_analyst_incident_event_command(client, args)
    expected_response = util_load_json("test_data/formatted_unack.json")

    assert integration_response.outputs == expected_response
    assert integration_response.outputs_prefix == "Darktrace.AIAnalyst"


def test_get_ai_analyst_incident_group_from_eventId(requests_mock):
    from DarktraceAIA import Client, get__ai_analyst_incident_group_from_eventId_command

    eventId = "bc64f242-ce29-4f35-bc94-230991116564"
    mock_api_response = util_load_json("test_data/group_response.json")
    requests_mock.get("https://mock.darktrace.com/aianalyst/groups?uuid=" + eventId, json=mock_api_response)

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

    args = {
        "eventId": eventId,
    }

    integration_response = get__ai_analyst_incident_group_from_eventId_command(client, args)
    expected_response = util_load_json("test_data/formatted_group_response.json")

    assert integration_response.outputs == expected_response
    assert integration_response.outputs_prefix == "Darktrace.AIAnalyst"
    assert integration_response.outputs_key_field == "groupId"