Added a new connector for the Updated Crowdstrike Alerts endpoint. #1710

(#1724) * Temporary Commit. Signed-off-by: DerekRushton <[email protected]> * Crowdstrike_temp_commits_2 Signed-off-by: DerekRushton <[email protected]> * crowdstrike_3 Signed-off-by: DerekRushton <[email protected]> * commit3 Signed-off-by: DerekRushton <[email protected]> * Test4 Signed-off-by: DerekRushton <[email protected]> * test4 Signed-off-by: DerekRushton <[email protected]> * Draft_final_commit Signed-off-by: DerekRushton <[email protected]> * Crowdstrike_Alerts_Final_Draft Signed-off-by: DerekRushton <[email protected]> * Update config.json * Update requirements.txt * Delete requirements.txt * Update connector.py * Update connector.py * Update connector.py * Update CHANGELOG.md * Update from_stix_map.json * Update to_stix_map.json * Update requirements.txt * Ensuring the configs match. Signed-off-by: DerekRushton <[email protected]> * Fixed some issues with length+offset Signed-off-by: DerekRushton <[email protected]> * Made a mistake with the last small fix. Signed-off-by: DerekRushton <[email protected]> * Changing the display name Signed-off-by: DerekRushton <[email protected]> * Fixed STIX 2.1 mapping Signed-off-by: DerekRushton <[email protected]> * STIX 2.1 Signed-off-by: DerekRushton <[email protected]> --------- Signed-off-by: DerekRushton <[email protected]> Co-authored-by: Ben Craig <[email protected]>
opencybersecurityalliance · Sep 13, 2024 · 80f3b37 · 80f3b37
1 parent d7fb558
commit 80f3b37
Show file tree

Hide file tree

Showing 46 changed files with 47,905 additions and 3 deletions.
diff --git a/docs/supported-mappings.md b/docs/supported-mappings.md
@@ -25,6 +25,7 @@ Stix-shifter currently offers connector support for the following cybersecurity
 - [Carbon Black Cloud](../stix_shifter_modules/cbcloud/cbcloud_supported_stix.md)
 - [Cisco Secure Email](../stix_shifter_modules/cisco_secure_email/cisco_secure_email_supported_stix.md)
 - [CrowdStrike Falcon](../stix_shifter_modules/crowdstrike/crowdstrike_supported_stix.md)
+- [CrowdStrike Falcon Alerts API](../stix_shifter_modules/crowdstrike_alerts/crowdstrike_alerts_supported_stix.md)
 - [Cybereason](../stix_shifter_modules/cybereason/cybereason_supported_stix.md)
 - [Darktrace](../stix_shifter_modules/darktrace/darktrace_supported_stix.md)
 - [Datadog](../stix_shifter_modules/datadog/datadog_supported_stix.md)

diff --git a/stix_shifter/requirements.txt b/stix_shifter/requirements.txt
@@ -11,10 +11,11 @@ flask==3.0.0
 flatten_json==0.1.14
 json-fix==1.0.0
 jsonmerge==1.9.2
+numpy==1.24.4
 pyOpenSSL==24.1.0
 python-dateutil==2.8.2
 stix2-matcher==3.0.0
 stix2-patterns==1.3.2
 xmltodict==0.13.0
 urllib3==1.26.19
-regex==2023.12.25
+regex==2023.12.25
diff --git a/stix_shifter/scripts/supported_property_exporter.py b/stix_shifter/scripts/supported_property_exporter.py
@@ -28,6 +28,7 @@
     "cbcloud": "Carbon Black Cloud", 
     "cisco_secure_email": "Cisco Secure Email",
     "crowdstrike": 'CrowdStrike Falcon',
+    "crowdstrike_alerts": 'CrowdStrike Falcon Alerts API',
     "cybereason": "Cybereason",
     "darktrace": "Darktrace",
     "datadog": "Datadog",

diff --git a/stix_shifter_modules/crowdstrike/README.md b/stix_shifter_modules/crowdstrike/README.md
@@ -1,5 +1,8 @@
 # CrowdStrike Falcon
 
+The CrowdStrike connector is set for deprecation and will no longer be supported. To continue receiving data, use the CrowdStrike Alerts connector instead.
+The CrowdStrike Alerts connector will collect the same data as this one, except it uses the newer alerts endpoint instead of the detections endpoint. 
+
 ## Supported STIX Mappings
 
 See the [table of mappings](crowdstrike_supported_stix.md) for the STIX objects and operators supported by this connector.

diff --git a/stix_shifter_modules/crowdstrike/configuration/lang_en.json b/stix_shifter_modules/crowdstrike/configuration/lang_en.json
@@ -18,11 +18,11 @@
             "type" : "fields",
             "client_id": {
                 "label": "Client ID",
-                "description": "Unique identifier of CrowdStrike API. It can be found in the API client table in the Falcon console"
+                "description": "Unique identifier for CrowdStrike APIs. An API Client can be created in the API clients and keys section of the Falcon console"
             },
             "client_secret": {
                 "label": "Client secret",
-                "description": "Secret code of CrowdStrike API client. It can be found while creating a API client in Falcon console"
+                "description": "Secret code for CrowdStrike API client. An API Client can be created in the API clients and keys section of the Falcon console"
             }
         }
     }

diff --git a/stix_shifter_modules/crowdstrike_alerts/README.md b/stix_shifter_modules/crowdstrike_alerts/README.md
@@ -0,0 +1,132 @@
+# CrowdStrike Falcon Alerts
+
+## About this connector
+
+This connector replaces the now deprecated crowdstrike connector for collecting CrowdStrike Falcon detection and alert data.
+
+## Supported STIX Mappings
+
+See the [table of mappings](crowdstrike_alerts_supported_stix.md) for the STIX objects and operators supported by this connector.
+
+## CrowdStrike Alerts Requirements
+
+The CrowdStrike Alerts API requires the following to work.
+
+1. A CrowdStrike environment with Endpoint Security set-up.
+2. An OAuth2 API Client created with Alerts Scope enabled for read and the Detections Scope enabled for read.
+3. Both the Client ID and Secret.
+
+## CrowdStrike Alerts Sample Curl Commands
+
+The Crowdstrike alerts API works via the following mechanisms.
+
+1. Use the OAuth2 API Client Credentials to obtain a bearer token (this token expires after a set amount of time).
+2. Using the bearer token, create a request for a list of ID's that match the query with a set limit.
+3. Create a query for the data results using the list of ID's. 
+
+Curl command to get a bearer token.
+
+```curl --location 'https://[host]/oauth2/token' \
+--header 'accept: application/json' \
+--header 'user-agent: oca_stixshifter_1.0' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'client_id=[id]' \
+--data-urlencode 'client_secret=[secret]'
+```
+
+Curl command to get a list of ID's.
+
+```curl --location 'https://[host]/alerts/queries/alerts/v2' \
+--header 'accept: application/json' \
+--header 'user-agent: oca_stixshifter_1.0' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer [bearer token]'
+```
+
+Curl command to get the ID details
+
+```curl --location 'https://[host]/alerts/queries/alerts/v2' \
+--header 'accept: application/json' \
+--header 'user-agent: oca_stixshifter_1.0' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer [bearer token]' \
+--data '{"composite_ids":[ID List]}'
+```
+
+## CrowdStrike Supported STIX Pattern values (Querying):
+
+The supported query values are defined in the mapping file from_stix_map.json. For detailed list of supported STIX Pattern values refer to the crowdstrike_alerts_supported_stix.md.
+
+### Execute a STIX pattern on a CrowdStrike instance
+
+```bash
+$ python3 main.py execute crowdstrike_alerts crowdstrike_alerts "<data_source>" "<connection>" "<configuration>" "<query>"
+```
+
+
+```bash
+$ python3 main.py execute crowdstrike_alerts crowdstrike_alerts "{\"type\":\"identity\",\"id\":\"identity--f431f809-377b-45e0-aa1c-6a4751cae5ff\",\"name\":\"Crowdstrike\",\"identity_class\":\"events\", \"created\":\"2022-05-22T13:22:50.336Z\",\"modified\":\"2022-05-25T13:22:50.336Z\"}" "{\"host\":\"[host\"}" "{\"auth\":{\"client_id\":\"[id]\", \"client_secret\":\"[secret]\"}}" "[ipv4-addr:value != '1.1.1.1'] START t'2024-03-01T11:00:00.000Z' STOP t'2024-07-03T11:54:00.000Z'" -r 100
+```
+
+Note in this example some logging is omitted.
+
+Translated CrowdStrike query and parsed STIX expression:
+
+```bash
+$ python3 main.py translate crowdstrike_alerts query '{}' "[process:name = 'cmd.exe']"
+
+    "queries": [
+        "(((filename: 'cmd.exe',grandparent_details.filename: 'cmd.exe',parent_details.filename: 'cmd.exe')) %2B timestamp:> '2024-07-19T14:53:37.560762')"
+    ]
+```
+
+## Example I - Converting from STIX patterns to FQL queries (STIX attributes)
+
+STIX to sentinel field mapping is defined in from_stix_map.json
+
+This example input pattern:
+
+```bash
+$ python3 main.py translate crowdstrike_alerts query '{}' "[process:name = 'cmd.exe']"
+```
+
+Returns the following native query:
+
+```bash
+    "queries": [
+        "(((filename: 'cmd.exe',grandparent_details.filename: 'cmd.exe',parent_details.filename: 'cmd.exe')) %2B timestamp:> '2024-07-19T14:53:37.560762')"
+    ]
+```
+
+
+## Example - Converting from CrowdStrike alerts to STIX (STIX attributes)
+
+Sentinel data to STIX mapping is defined in to_stix_map.json
+
+Sample data:
+
+CrowdStrike data to Stix mapping is defined in to_stix_map.json which is located in the crowdstrike module.
+
+For an example of an untranslated result see the file under crowdstrike_alerts/tests/stix_translation/sample_results_data.json.
+For an example of a translated result see the file under crowdstrike_alerts/tests/stix_translation/sample_results_transformed.json.
+
+## Operator Support (Data Source)
+AND (Comparison)
+OR (Comparison)
+=
+!=
+>
+>=
+<
+<= 
+IN 
+
+## Exclusions
+
+FQL does not supports the following operators:
+* LIKE 
+* Matches
+
+## Limitations
+
+Not all fields may be supported. The Alerts endpoint can pull results from multiple products. The current implementation will only support detection alerts.
diff --git a/stix_shifter_modules/crowdstrike_alerts/__init__.py b/stix_shifter_modules/crowdstrike_alerts/__init__.py
diff --git a/stix_shifter_modules/crowdstrike_alerts/configuration/config.json b/stix_shifter_modules/crowdstrike_alerts/configuration/config.json
@@ -0,0 +1,41 @@
+{
+    "connection": {
+        "type": {
+            "displayName": "CrowdStrike Falcon Alerts",
+            "group": "crowdstrike"
+        },
+        "host": {
+            "type": "text",
+            "regex": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9_:/\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9_:/\\-]*[A-Za-z0-9])$"
+        },
+        "port": {
+            "type": "number",
+            "default": 443,
+            "min": 1,
+            "max": 65535
+        },
+        "help": {
+            "default": "data-sources-crowdstrike-falcon.html",
+            "type": "link"
+        },
+        "options": {
+            "validate_pattern": {
+                "default": false
+            },
+            "result_limit": {
+                "default": 1000
+            }
+        }
+    },
+    "configuration": {
+        "auth": {
+            "type" : "fields",
+            "client_id": {
+                "type": "password"
+            },
+            "client_secret": {
+                "type": "password"
+            }
+        }
+    }
+}
diff --git a/stix_shifter_modules/crowdstrike_alerts/configuration/lang_en.json b/stix_shifter_modules/crowdstrike_alerts/configuration/lang_en.json
@@ -0,0 +1,29 @@
+{
+    "connection": {
+        "host": {
+            "label": "Management IP address or hostname",
+            "description": "Specify the IP address or hostname of the data source"
+        },
+        "port": {
+            "label": "Host port",
+            "description": "Set the port number that is associated with the hostname or IP address"
+        },
+        "help": {
+            "label": "Need additional help?",
+            "description": "More details on the data source setting can be found in the specified link"
+        }
+    },
+    "configuration": {
+        "auth": {
+            "type" : "fields",
+            "client_id": {
+                "label": "Client ID",
+                "description": "Unique identifier for CrowdStrike APIs. An API Client can be created in the API clients and keys section of the Falcon console"
+            },
+            "client_secret": {
+                "label": "Client secret",
+                "description": "Secret code for CrowdStrike API client. An API Client can be created in the API clients and keys section of the Falcon console"
+            }
+        }
+    }
+}