Ransomware activity alert (#881)

Author: ianfre25

content/guides/events/event-triggers/shield-alert-events.md

@@ -27,6 +27,7 @@ The possible alerts produced by Shield are for:
 2. Suspicious sessions
 3. Anomalous downloads
 4. Malicious content
+5. Ransomware activity (part of Shield Pro)
 
 All Shield threat detection alert events are produced within the
 [enterprise event][events] stream. These events follow the
@@ -339,6 +340,76 @@ The `additional_details` payload will provide the following details:
 }
 ```
 
+### Ransomware activity alert
+
+<!--alex ignore-->
+
+A ransomware activity alert is produced when Box Shield identifies suspicious file extensions that may be indicative of a ransomware attack. It can be identified by the Ransomware Activity value within `additional_details.shield_alert.rule_category`. 
+
+The `additional_details` payload will provide the following details:
+
+<!--alex enable-->
+
+```json
+{
+  "source": null,
+  "created_by": {
+    "type": "user",
+    "id": "2",
+    "name": "Unknown User",
+    "login": ""
+    },
+    "action_by": null,
+    "created_at": "2025-08-19T10:44:26-07:00",
+    "event_id": "5b508973-0e48-4bc1-80b2-a05b5382eb37",
+    "event_type": "SHIELD_ALERT",
+    "ip_address": "1.2.3.4",
+    "type": "event",
+    "session_id": null,
+    "additional_details": {
+      "shield_alert": {
+        "rule_category": "Ransomware Activity",
+        "rule_id": "1234",
+        "rule_name": "Ransomware Detection",
+        "rule_response_action": null,
+          "risk_score": 100,
+          "alert_summary": {
+          "total_files_affected": 42,
+          "ip_details": [
+            {
+             "ip": "1.2.3.4",
+             "registrant": "Microsoft Corporation",
+             "latitude": "37.5555",
+             "longitude": "-120.6789",
+             "city_name": "San Jose",
+             "region_name": "California",
+             "country_code": "US"
+            }
+           ],
+           "suspicious_file_extensions": [
+            "lockbit"
+           ],
+           "anomaly_period": {
+            "date_range": {
+             "start_date": "2009-02-13T23:31:30Z",
+             "end_date": "2009-02-13T23:31:30Z"
+            }
+          }
+        },
+        "alert_id": 1234,
+        "priority": "medium",
+        "user": {
+         "id": 8167630149,
+         "name": "Some user",
+         "email": "[email protected]"
+        },
+        "link": "https://app.box.com/master/shield/alerts/1234",
+        "created_at": "2025-08-19T10:44:26-07:00"
+     }
+   }
+}
+```
+
 <!-- i18n-enable localize-links -->
 [box-shield]: https://www.box.com/shield
 [threatdetect]:https://support.box.com/hc/en-us/articles/360044196113-Using-Threat-Detection