CrowdStrike Falcon Streaming v2

Use the CrowdStrike Falcon Stream v2 integration to stream detections and audit security events.

Details

ID	`CrowdStrike Falcon Streaming v2`
Provider	CrowdStrike
Category	Endpoint
From Version	5.0.0
Docker Image	`demisto/py3-tools:1.0.0.4257568`

README

Overview

Use CrowdStrike Falcon Streaming v2 integration to connect to CrowdStrike Falcon stream and fetch events as incidents to Cortex XSOAR.

Define CrowdStrike API client

In order to use the integration, an API client need to be defined, and its ID and secret should be configured in the integration instance.

Follow this article in order to get access to CrowdStrike API, and generate client ID and client secret.

The required scope is Event streams.

Configure CrowdStrike Falcon Streaming v2 on Cortex XSOAR

Navigate to Settings > Integrations > Servers & Services.
Search for CrowdStrike Falcon Streaming v2
Click Add instance to create and configure a new integration instance.
- Name: a textual name for the integration instance.
- Cloud Base URL (e.g. https://api.crowdstrike.com)
- Client ID
- Client Secret
- Application ID
- Event type to fetch
- Offset to fetch events from
- Stream client read timeout
- Incident type
- Store sample events for mapping
- Trust any certificate (not secure)
- Use system proxy settings
Click Test to validate the URLs, token, and connection.

Important Notes

If you’re using Falcon’s commercial cloud, use the default value of the Cloud base URL.
If you use another CrowdStrike cloud environment, use one of the following:
- GovCloud: https://api.laggar.gcw.crowdstrike.com
- EU cloud: https://api.eu-1.crowdstrike.com
Offset to fetch events from should have an integer value, in order to fetch all events set it to 0 (as the default value).

Only events starting from this offset will be fetched

For example, if set to 10: the event with offset 9 will not be fetched, and events with offsets 10 and 11 will be fetched.
Event type to fetch parameter accepts multiple values, so choose as many as you want to fetch.

In order to fetch all events of all types, you can leave it empty.

You can also add event type that is not listed, by entering it in the parameter value.
In order to run multiple clients (stream consumers) simultaneously, each integration instance should have unique application ID. The application ID can be of length up to 32 characters.

Fetched Incidents Data

Event metadata will be fetched as the incident details, which contain the following:

Type
Offset
Creation time
Used ID
Service Name
Detection Name
Detection Description
Severity

Mapping incoming events

Because this is a push-based streaming integration, it cannot fetch sample events in the mapping wizard.

In order to view sample events, enable events storage by selecting the checkbox of the integration parameter Store sample events for mapping.

The last events (maximum of 20) are fetched every 1 minute. Allow the integration to run for at least 5 minutes before running the command.
After you finish mapping, it is recommended to turn off the Store sample events for mapping to reduce performance overhead.

For Cortex XSOAR version 6.0 and above, you will be able to fetch samples in the mapping wizard

For earlier versions, you should run the crowdstrike-falcon-streaming-get-sample-events command.

The command output is as follows:

{
    "event": {
        "ComputerName": "FALCON-CROWDSTR",
        "DetectId": "ldt:15dbb9d8f06b45fe9f61eb46e829d986:55929758895",
        "DetectName": "Suspicious Activity",
        "FileName": "choice.exe",
        "FilePath": "\\Device\\HarddiskVolume1\\Windows\\System32",
        "GrandparentCommandLine": "C:\\Windows\\Explorer.EXE",
        "GrandparentImageFileName": "\\Device\\HarddiskVolume1\\Windows\\explorer.exe",
        "MD5String": "463b5477ff96ab86a01ba49bcc02b539",
        "MachineDomain": "FALCON-CROWDSTR",
        "Objective": "Falcon Detection Method",
        "ParentCommandLine": "\"C:\\Windows\\system32\\cmd.exe\" ",
        "ParentImageFileName": "\\Device\\HarddiskVolume1\\Windows\\System32\\cmd.exe",
        "ParentProcessId": 79569204402,
        "PatternDispositionDescription": "Detection, standard detection.",
        "PatternDispositionFlags": {
            "BootupSafeguardEnabled": false,
            "CriticalProcessDisabled": false,
            "Detect": false,
            "FsOperationBlocked": false,
            "InddetMask": false,
            "Indicator": false,
            "KillParent": false,
            "KillProcess": false,
            "KillSubProcess": false,
            "OperationBlocked": false,
            "PolicyDisabled": false,
            "ProcessBlocked": false,
            "QuarantineFile": false,
            "QuarantineMachine": false,
            "RegistryOperationBlocked": false,
            "Rooting": false,
            "SensorOnly": false
        },
        "PatternDispositionValue": 0,
        "ProcessEndTime": 1592479032,
        "ProcessId": 79867150228,
        "ProcessStartTime": 1592479032,
        "Severity": 2,
        "SeverityName": "Low",
        "Tactic": "Falcon Overwatch",
        "Technique": "Malicious Activity",
        "UserName": "admin"
    },
    "metadata": {
        "customerIDString": "20874a8064904ecfbb62c118a6a19411",
        "eventCreationTime": 1592479032000,
        "eventType": "EppDetectionSummaryEvent",
        "offset": 70628,
        "version": "1.0"
    }
}

You can now upload that JSON file to the mapping wizard and continue as usual.

Configuration parameters

base_url — Cloud Base URL (e.g., https://api.crowdstrike.com) (required)
client_id — Client ID
client_secret — Client Secret
credentials_client — Client ID
app_id — Application ID
longRunning — Long running instance
event_type — Event type to fetch
offset — Offset to fetch events from
incidentType — Incident type
fetch_time — First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)
sock_read_timeout — Stream client read timeout
store_samples — Store sample events for mapping
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings

Commands (1)

crowdstrike-falcon-streaming-get-sample-events
Returns a list of sample events fetched from the stream.

Source

CrowdStrikeFalconStreamingV2.py CrowdStrikeFalconStreamingV2_test.py CrowdStrikeFalconStreamingV2.yml CrowdStrikeFalconStreamingV2_description.md

Download History Raw

import json

import demistomock as demisto
import pytest
from CrowdStrikeFalconStreamingV2 import get_sample_events, merge_integration_context, replace_deprecated_event_types


def test_get_sample_events_with_results(mocker):
    """
    Given:
     - Samples events stored in the integration context.
     - Store events integration parameter is enabled.

    When:
     - Running get sample events command.

    Then:
     - Ensure the command runs successfully
     - Verify expected results are returned.
    """
    sample_events = [
        {
            "event": {
                "AuditKeyValues": [
                    {"Key": "partition", "ValueString": "0"},
                    {"Key": "offset", "ValueString": "70626"},
                    {"Key": "appId", "ValueString": "demisto"},
                    {"Key": "eventType", "ValueString": "All event type(s)"},
                ],
                "OperationName": "streamStarted",
                "ServiceName": "Crowdstrike Streaming API",
                "Success": True,
                "UTCTimestamp": 1592479007,
            },
            "metadata": {
                "eventCreationTime": 1592479007646,
                "eventType": "AuthActivityAuditEvent",
                "offset": 70627,
                "version": "1.0",
            },
        },
        {
            "event": {
                "CommandLine": "choice  /m crowdstrike_sample_detection",
                "ComputerName": "FALCON-CROWDSTR",
                "Description": "For evaluation only - benign, no action needed.",
                "Name": "Suspicious Activity",
                "FileName": "choice.exe",
                "FilePath": "\\Device\\HarddiskVolume1\\Windows\\System32",
                "GrandparentCommandLine": "C:\\Windows\\Explorer.EXE",
                "GrandparentImageFileName": "\\Device\\HarddiskVolume1\\Windows\\explorer.exe",
                "MD5String": "463b5477ff96ab86a01ba49bcc02b539",
                "MachineDomain": "FALCON-CROWDSTR",
                "Objective": "Falcon Detection Method",
                "ParentCommandLine": "'C:\\Windows\\system32\\cmd.exe' ",
                "ParentImageFileName": "\\Device\\HarddiskVolume1\\Windows\\System32\\cmd.exe",
                "ParentProcessId": 79569204402,
                "PatternDispositionDescription": "Detection, standard detection.",
                "PatternDispositionFlags": {
                    "BootupSafeguardEnabled": False,
                    "CriticalProcessDisabled": False,
                    "Detect": False,
                    "FsOperationBlocked": False,
                    "InddetMask": False,
                    "Indicator": False,
                    "KillParent": False,
                    "KillProcess": False,
                    "KillSubProcess": False,
                    "OperationBlocked": False,
                    "PolicyDisabled": False,
                    "ProcessBlocked": False,
                    "QuarantineFile": False,
                    "QuarantineMachine": False,
                    "RegistryOperationBlocked": False,
                    "Rooting": False,
                    "SensorOnly": False,
                },
                "PatternDispositionValue": 0,
                "ProcessEndTime": 1592479032,
                "ProcessId": 79867150228,
                "ProcessStartTime": 1592479032,
                "SHA1String": "0000000000000000000000000000000000000000",
                "SHA256String": "90f352c1fb7b21cc0216b2f0701a236db92b786e4301904d28f4ec4cb81f2a0b",
                "SensorId": "15dbb9d8f06b45fe9f61eb46e829d986",
                "Severity": 2,
                "SeverityName": "Low",
                "Tactic": "Falcon Overwatch",
                "Technique": "Malicious Activity",
                "UserName": "admin",
            },
            "metadata": {
                "eventCreationTime": 1592479032000,
                "eventType": "EppDetectionSummaryEvent",
                "offset": 70628,
                "version": "1.0",
            },
        },
    ]
    mocker.patch.object(demisto, "getIntegrationContext", return_value={"sample_events": json.dumps(sample_events)})
    mocker.patch.object(demisto, "results")
    get_sample_events()
    assert demisto.results.call_count == 1
    results = demisto.results.call_args[0][0]
    assert results == sample_events


def test_get_sample_events_integration_param(mocker):
    """
    Given:
     - Samples events not stored in the integration context.
     - Store events integration parameter is disabled.

    When:
     - Running get sample events command.

    Then:
     - Ensure the command runs successfully
     - Verify output message.
    """
    mocker.patch.object(demisto, "getIntegrationContext", return_value={})
    mocker.patch.object(demisto, "results")
    get_sample_events(store_samples=False)
    assert demisto.results.call_count == 1
    results = demisto.results.call_args[0][0]
    assert (
        results == 'No sample events found. The "Store sample events for mapping" integration parameter need to '
        "be enabled for this command to return results."
    )


@pytest.mark.parametrize(
    "current_integration_context, updated_integration_context",
    [
        ({"offset": 1}, {"offset": "1"}),
        ({"sample_events": [{"event": {}}]}, {"sample_events": '[{"event": {}}]'}),
        ({"offset": "1", "sample_events": '[{"event": {}}]'}, {}),
    ],
)
def test_merge_integration_context(mocker, current_integration_context, updated_integration_context):
    """
    Given:
     - Case A: Integration context with the property offset of type int
     - Case B: Integration context with the property sample_events of type list
     - Case C: Integration context with the properties offset and sample_events of type str

    When:
     - Merging integration context

    Then:
     - Case A: Ensure integration context is updated with offset of type str
     - Case B: Ensure integration context is updated with sample_events of type str
     - Case C: Ensure integration context is not updated as it is in the proper state
    """
    mocker.patch.object(demisto, "getIntegrationContext", return_value=current_integration_context)
    mocker.patch.object(demisto, "setIntegrationContext")
    merge_integration_context()
    if updated_integration_context:
        # Cases A and B
        assert demisto.setIntegrationContext.call_args[0][0] == updated_integration_context
    else:
        # Case C
        assert not demisto.setIntegrationContext.called


@pytest.mark.parametrize(
    "input_event_types, expected_output",
    [
        ([], ""),
        (["AuthActivityAuditEvent"], "AuthActivityAuditEvent"),
        (["DetectionSummaryEvent"], "EppDetectionSummaryEvent"),
        (["AuthActivityAuditEvent", "DetectionSummaryEvent"], "AuthActivityAuditEvent,EppDetectionSummaryEvent"),
        (["DetectionSummaryEvent", "AuthActivityAuditEvent"], "EppDetectionSummaryEvent,AuthActivityAuditEvent"),
        (["DetectionSummaryEvent", "DetectionSummaryEvent"], "EppDetectionSummaryEvent,EppDetectionSummaryEvent"),
        (["EppDetectionSummaryEvent", "AuthActivityAuditEvent"], "EppDetectionSummaryEvent,AuthActivityAuditEvent"),
        (
            ["UserActivityAuditEvent", "DetectionSummaryEvent", "ProcessRollup2Event"],
            "UserActivityAuditEvent,EppDetectionSummaryEvent,ProcessRollup2Event",
        ),  # noqa: E501
    ],
)
def test_replace_deprecated_event_types(input_event_types, expected_output):
    """
    Given:
     - Case A: Empty list of event types
     - Case B: List with only non-deprecated event types
     - Case C: List with only deprecated DetectionSummaryEvent
     - Case D: List with deprecated event at the end
     - Case E: List with deprecated event at the beginning
     - Case F: List with multiple deprecated events
     - Case G: List with already updated EppDetectionSummaryEvent
     - Case H: List with mixed event types including deprecated one in the middle

    When:
     - Calling replace_deprecated_event_types function

    Then:
     - Case A: Return empty string
     - Case B: Return original event types unchanged
     - Case C: Return EppDetectionSummaryEvent
     - Case D: Return list with DetectionSummaryEvent replaced with EppDetectionSummaryEvent
     - Case E: Return list with DetectionSummaryEvent replaced with EppDetectionSummaryEvent
     - Case F: Return list with all DetectionSummaryEvent instances replaced
     - Case G: Return list unchanged (already using new event type)
     - Case H: Return list with only DetectionSummaryEvent replaced, others unchanged
    """
    result = replace_deprecated_event_types(input_event_types)
    assert result == expected_output