Merge branch 'develop' into THREAT-422-Stratus-AWS-S3-Detections

Author: arielkr256

.cursor/rules/panther-rules.mdc

@@ -0,0 +1,74 @@
+---
+description: Understanding how to write optimal Panther Rules
+globs: *.py
+alwaysApply: false
+---
+You are an expert cybersecurity detection engineer specialzed in cloud infrastructure, SaaS security, and MITRE ATT&CK for mapping attacker techniques. Your goal is to create new Panther detection rules that cover threat models, analyze logs, and detect malicious behaviors important to your organization. Consider the existing rules by reading the `rules/` folder which are organized by classifeid log type.
+
+# System Context
+Panther contains several types of Detections:
+- Rules (`rules/`): Streaming Python rules that analyze events one at a time, best applied towards high-fidelity events such as alerts from IDS systems (GuardDuty, Wiz, etc) or very high-confidence events like a cronjob containing a wget command or exfiltration from an S3 bucket.
+- Signal (found in `rules/`): A special mode of a Rule where no alert is generated and events are labeled, dictated by the CreateAlert attribute being set to false. This is useful for security-relevant logs, but not behaviors that warrant immediate alerts. Signals are building blocks for correlation rules, dashboards, or expensive queries.
+- Scheduled Rules: An aggregate style detection sourced from scheduled queries (`queries/`) declared in SQL + YAML. These run on a defined schedule and execute the SQL query defined by the user. A subsequent Python rule is associated to control post-processing with the rule() function and additional alerting functionality like title interpolation and other auxilirary functions like setting dynamic severities.
+
+All log data is normalized per a strictly-defined schema prior to being passed into the detection engine.
+
+Thresholding and deduplication are handled by the Panther platform. DO NOT implement this logic in the rule.
+
+# Conventions
+
+## Event Functions
+- Use `event.get()` to safely access `event` fields that may not exist: `bucket_name = event.get('requestParameters')`
+- Use `event.deep_get()` to access nested `event` fields: `bucket_name = event.deep_get('requestParameters', 'bucketName')` DO NOT IMPORT THIS FUNCTION. IT'S DIRECTLY ACCESSIBLE ON THE EVENT.
+- Use `event.deep_walk()` to return values associated with keys that are deeply nested in Python dictionaries, which may contain any number of dictionaries or lists. If it matches multiple event fields, an array of matches will be returned; if only one match is made, the value of that match will be returned.
+
+## Style
+- ONLY ASSIGN VARIABLES WHEN REUSE IS REQUIRED.
+- Don't write Rule methods with type annotations.
+- WHENEVER possible, Return rule() functions early to reduce logic nesting and improve processing performance.
+- Optimize rule() functions for simplicity, such as a single return statement with `and` and `or` expressions.
+- Use class constants for sets/lists that are used within methods, such as status codes, users, patterns, list of network ports, etc.
+- Use class attributes for lists that can be modified by users in overrides.
+
+# Python Rule Syntax
+
+A Python detection MUST CONTAIN TWO FILES: a Python file for logic and a YML file containing metadata.
+
+The YML file has the following structure:
+AnalysisType: # rule, scheduled_rule, correlation_rule, or policy
+Enabled: # boolean
+FileName: # the Python file name
+RuleID: # or PolicyId
+LogTypes: 
+Tags: 
+Tests: 
+ScheduledQueries: # only applicable to scheduled rules
+Suppressions: # only applicable to policies
+CreateAlert: # not applicable to policies
+Severity:
+Description:
+DedupPeriodMinutes:
+Threshold: 
+DisplayName:
+OutputIds:
+Reference:
+Runbook:
+SummaryAttributes:
+
+The Python file can contain the following functions:
+- `rule(event: Dict[str, Any]) -> bool`: The main detection logic that determines if an alert is sent. Returns `True` if the event matches the rule criteria, `False` otherwise. REQUIRED FOR ALL DETECTIONS.
+- `title(event: Dict[str, Any]) -> str`: Returns a human-readable alert title with event interpolation sent to alert destinations. THIS IS ALSO THE DEFAULT DEDUP(). Do not make it too unique, otherwise too many alerts will be sent. REQUIRED FOR ALL DETECTIONS BUT NOT FOR SIGNALS.
+- `dedup(event: Dict[str, Any]) -> str`: A deduplication key for the alert. OPTIONAL. Only use if specifically instructed by user.
+- `alert_context(event: Dict[str, Any]) -> Dict[str, Any]`: Quick context included in the alert that describes the important parts of the log for analysts. OPTIONAL.
+
+ONLY USE THE FOLLOWING FUNCTIONS IF DYNAMIC SELECTION IS REQUESTED BY THE USER EXPLICITLY. OTHERWISE, use the related YAML field.
+- `severity(event: Dict[str, Any]) -> str`: The risk level of the alert (INFO, LOW, MEDIUM, HIGH, CRITICAL based on the `Severity` enum). Only set severity if it should be different levels based on specific conditions.
+- `destinations(event: Dict[str, Any]) -> List[str]`: Returns a list of destinations to send the alert to. Only add this when the user specifies.
+- `runbook(event: Dict[str, Any]) -> str`: The steps to triage the alert and recommend next steps.
+- `reference(event: Dict[str, Any]) -> str`: A reference to additional information about the alert, typically a URL to documentation.
+
+If a user asks to create a Signal, then:
+1. Set `CreateAlert` to false
+2. Set `Severity` to INFO
+3. ONLY include the rule method
+4. Ignore alert-related metadata like deduplication

.github/workflows/validate.yml

@@ -1,14 +1,13 @@
 on:
-  pull_request:
-    types:
-      - closed
+  pull_request_review:
+    types: [submitted]
 
 permissions:
   contents: read
 
 jobs:
   validate:
-    if: github.event.pull_request.merged == true
+    if: github.event.review.state == 'approved' && github.event.pull_request.head.repo.fork == false
     name: Validate
     runs-on: ubuntu-latest
     env:

correlation_rules/snowflake_data_exfiltration_streaming.yml

@@ -0,0 +1,70 @@
+AnalysisType: correlation_rule
+RuleID: "Snowflake.Stream.DataExfiltration"
+DisplayName: "Snowflake Data Exfiltration"
+Enabled: true
+Severity: Critical
+Description: In April 2024, Mandiant received threat intelligence on database records that were subsequently determined to have originated from a victim’s Snowflake instance. Mandiant notified the victim, who then engaged Mandiant to investigate suspected data theft involving their Snowflake instance. During this investigation, Mandiant determined that the organization’s Snowflake instance had been compromised by a threat actor using credentials previously stolen via infostealer malware. The threat actor used these stolen credentials to access the customer’s Snowflake instance and ultimately exfiltrate valuable data. At the time of the compromise, the account did not have multi-factor authentication (MFA) enabled.
+Reference: https://cloud.google.com/blog/topics/threat-intelligence/unc5537-snowflake-data-theft-extortion/
+Reports:
+    MITRE ATT&CK:
+        - TA0010:T1041  # Exfiltration Over C2 Channel
+Detection:
+  - Sequence:
+      - ID: SnowflakeTempStageCreated
+        RuleID: Snowflake.Stream.TempStageCreated
+      - ID: SnowflakeCopyIntoStage
+        RuleID: Snowflake.Stream.TableCopiedIntoStage
+      - ID: SnowflakeFileDownloaded
+        RuleID: Snowflake.Stream.FileDownloaded
+    Transitions:
+      - ID: Match SnowflakeTempStageCreated and SnowflakeCopyIntoStage on stage
+        From: SnowflakeTempStageCreated
+        To: SnowflakeCopyIntoStage
+        Match:
+          - On: p_alert_context.stage
+      - ID: Match SnowflakeCopyIntoStage and SnowflakeFileDownloaded on path
+        From: SnowflakeCopyIntoStage
+        To: SnowflakeFileDownloaded
+        Match:
+          - On: p_alert_context.stage
+    Schedule:
+      RateMinutes: 1440
+      TimeoutMinutes: 15
+    LookbackWindowMinutes: 2160
+Tests:
+    - Name: Data Exfiltration
+      ExpectedResult: true
+      RuleOutputs:
+        - ID: SnowflakeTempStageCreated
+          Matches:
+            p_alert_context.stage:
+                LOGS.PUBLIC.data_exfil:
+                    - "2006-01-02T15:04:05Z"
+                    - "2006-01-02T15:04:06Z"
+        - ID: SnowflakeCopyIntoStage
+          Matches:
+            p_alert_context.stage:
+                LOGS.PUBLIC.data_exfil:
+                    - "2006-01-02T15:04:05Z"
+                    - "2006-01-02T15:04:06Z"
+        - ID: SnowflakeFileDownloaded
+          Matches:
+            p_alert_context.stage:
+                LOGS.PUBLIC.data_exfil:
+                    - "2006-01-02T15:04:05Z"
+                    - "2006-01-02T15:04:06Z"
+    - Name: Data Staged but not Downloaded
+      ExpectedResult: false
+      RuleOutputs:
+        - ID: SnowflakeTempStageCreated
+          Matches:
+            p_alert_context.stage:
+                LOGS.PUBLIC.data_exfil:
+                    - "2006-01-02T15:04:05Z"
+                    - "2006-01-02T15:04:06Z"
+        - ID: SnowflakeCopyIntoStage
+          Matches:
+            p_alert_context.stage:
+                LOGS.PUBLIC.data_exfil:
+                    - "2006-01-02T15:04:05Z"
+                    - "2006-01-02T15:04:06Z"

global_helpers/panther_base_helpers.py

@@ -9,7 +9,6 @@
 from ipaddress import ip_address, ip_network
 from typing import Any, List, Optional, Sequence, Union
 
-import panther_base_helpers_old
 from dateutil import parser
 
 # # # # # # # # # # # # # #
@@ -353,139 +352,3 @@ def pantherflow_investigation(event, interval="30m"):
     query += "| sort p_event_time"
 
     return query
-
-
-# panther_base_helpers.GSUITE_PARAMETER_VALUES is DEPRECATED!!!
-# Instead use panther_gsuite_helpers.GSUITE_PARAMETER_VALUES
-GSUITE_PARAMETER_VALUES = panther_base_helpers_old.GSUITE_PARAMETER_VALUES
-
-
-def gsuite_parameter_lookup(parameters, key):
-    """Global `gsuite_parameter_lookup` is DEPRECATED.
-    Instead, use `from panther_gsuite_helpers import gsuite_parameter_lookup`."""
-    return panther_base_helpers_old.gsuite_parameter_lookup(parameters, key)
-
-
-def gsuite_details_lookup(detail_type, detail_names, event):
-    """Global `gsuite_details_lookup` is DEPRECATED.
-    Instead, use `from panther_gsuite_helpers import gsuite_details_lookup`."""
-    return panther_base_helpers_old.gsuite_details_lookup(detail_type, detail_names, event)
-
-
-# panther_base_helpers.ZENDESK_CHANGE_DESCRIPTION is DEPRECATED!!!
-# Instead use panther_zendesk_helpers.ZENDESK_CHANGE_DESCRIPTION
-ZENDESK_CHANGE_DESCRIPTION = panther_base_helpers_old.ZENDESK_CHANGE_DESCRIPTION
-# panther_base_helpers.ZENDESK_APP_ROLE_ASSIGNED is DEPRECATED!!!
-# Instead use panther_zendesk_helpers.ZENDESK_APP_ROLE_ASSIGNED
-ZENDESK_APP_ROLE_ASSIGNED = panther_base_helpers_old.ZENDESK_APP_ROLE_ASSIGNED
-# panther_base_helpers.ZENDESK_ROLE_ASSIGNED is DEPRECATED!!!
-# Instead use panther_zendesk_helpers.ZENDESK_ROLE_ASSIGNED
-ZENDESK_ROLE_ASSIGNED = panther_base_helpers_old.ZENDESK_ROLE_ASSIGNED
-
-
-def zendesk_get_roles(event):
-    """Global `zendesk_get_roles` is DEPRECATED.
-    Instead, use `from panther_zendesk_helpers import zendesk_get_roles`."""
-    return panther_base_helpers_old.zendesk_get_roles(event)
-
-
-def box_parse_additional_details(event: dict):
-    """Global `box_parse_additional_details` is DEPRECATED.
-    Instead, use `from panther_box_helpers import box_parse_additional_details`."""
-    return panther_base_helpers_old.box_parse_additional_details(event)
-
-
-def okta_alert_context(event: dict):
-    """Global `okta_alert_context` is DEPRECATED.
-    Instead, use `from panther_okta_helpers import okta_alert_context`."""
-    return panther_base_helpers_old.okta_alert_context(event)
-
-
-def crowdstrike_detection_alert_context(event: dict):
-    """Global `crowdstrike_detection_alert_context` is DEPRECATED.
-    Instead, use `from panther_crowdstrike_fdr_helpers import crowdstrike_detection_alert_context`.
-    """
-    return panther_base_helpers_old.crowdstrike_detection_alert_context(event)
-
-
-def crowdstrike_process_alert_context(event: dict):
-    """Global `crowdstrike_process_alert_context` is DEPRECATED.
-    Instead, use `from panther_crowdstrike_fdr_helpers import crowdstrike_process_alert_context`.
-    """
-    return panther_base_helpers_old.crowdstrike_process_alert_context(event)
-
-
-def crowdstrike_network_detection_alert_context(event: dict):
-    """Global `crowdstrike_network_detection_alert_context` is DEPRECATED.
-    Instead, use `from panther_crowdstrike_fdr_helpers
-    import crowdstrike_network_detection_alert_context`.
-    """
-    return panther_base_helpers_old.crowdstrike_network_detection_alert_context(event)
-
-
-def filter_crowdstrike_fdr_event_type(event, name: str) -> bool:
-    """Global `filter_crowdstrike_fdr_event_type` is DEPRECATED.
-    Instead, use `from panther_crowdstrike_fdr_helpers import filter_crowdstrike_fdr_event_type`.
-    """
-    return panther_base_helpers_old.filter_crowdstrike_fdr_event_type(event, name)
-
-
-def get_crowdstrike_field(event, field_name, default=None):
-    """Global `get_crowdstrike_field` is DEPRECATED.
-    Instead, use `from panther_crowdstrike_fdr_helpers import get_crowdstrike_field`.
-    """
-    return panther_base_helpers_old.get_crowdstrike_field(event, field_name, default)
-
-
-def slack_alert_context(event):
-    """Global `slack_alert_context` is DEPRECATED.
-    Instead, use `from panther_slack_helpers import slack_alert_context`."""
-    return panther_base_helpers_old.slack_alert_context(event)
-
-
-def github_alert_context(event):
-    """Global `github_alert_context` is DEPRECATED.
-    Instead, use `from panther_github_helpers import github_alert_context`."""
-    return panther_base_helpers_old.github_alert_context(event)
-
-
-def aws_strip_role_session_id(user_identity_arn):
-    """Global `aws_strip_role_session_id` is DEPRECATED.
-    Instead, use `from panther_aws_helpers import aws_strip_role_session_id`."""
-    return panther_base_helpers_old.aws_strip_role_session_id(user_identity_arn)
-
-
-def aws_rule_context(event: dict):
-    """Global `aws_rule_context` is DEPRECATED.
-    Instead, use `from panther_aws_helpers import aws_rule_context`."""
-    return panther_base_helpers_old.aws_rule_context(event)
-
-
-def aws_guardduty_context(event: dict):
-    """Global `aws_guardduty_context` is DEPRECATED.
-    Instead, use `from panther_aws_helpers import aws_guardduty_context`."""
-    return panther_base_helpers_old.aws_guardduty_context(event)
-
-
-def eks_panther_obj_ref(event):
-    """Global `eks_panther_obj_ref` is DEPRECATED.
-    Instead, use `from panther_aws_helpers import eks_panther_obj_ref`."""
-    return panther_base_helpers_old.eks_panther_obj_ref(event)
-
-
-def get_binding_deltas(event):
-    """Global `get_binding_deltas` is DEPRECATED.
-    Instead, use `from panther_gcp_helpers import get_binding_deltas`."""
-    return panther_base_helpers_old.get_binding_deltas(event)
-
-
-def msft_graph_alert_context(event):
-    """Global `msft_graph_alert_context` is DEPRECATED.
-    Instead, use `from panther_msft_helpers import msft_graph_alert_context`."""
-    return panther_base_helpers_old.msft_graph_alert_context(event)
-
-
-def m365_alert_context(event):
-    """Global `m365_alert_context` is DEPRECATED.
-    Instead, use `from panther_msft_helpers import m365_alert_context`."""
-    return panther_base_helpers_old.m365_alert_context(event)