feat: investigations methods

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.33.0] - 2026-01-07
+### Added
+- Support for following investigation methods:
+  - List investigations
+  - Get investigation details
+  - Fetch associated investigation
+  - Trigger investigation
+
 ## [0.32.0] - 2026-01-05
 ### Added
 - Support for classify log method

CLI.md

@@ -983,6 +983,58 @@ secops case --ids "case-123,case-456"
 
 > **Note**: The case management uses a batch API that can retrieve multiple cases in a single request. You can provide up to 1000 case IDs separated by commas.
 
+### Investigation Management
+
+Chronicle investigations provide automated analysis and recommendations for alerts and cases. Use these commands to list, retrieve, trigger, and fetch associated investigations.
+
+#### List investigations
+
+```bash
+# List all investigations
+secops investigation list
+
+# List with pagination
+secops investigation list --page-size 50
+
+# List with pagination token
+secops investigation list --page-size 50 --page-token "token"
+```
+
+#### Get investigation details
+
+```bash
+# Get a specific investigation by ID
+secops investigation get --id "inv_123"
+```
+
+#### Trigger investigation for an alert
+
+```bash
+# Trigger an investigation for a specific alert
+secops investigation trigger --alert-id "alert_123"
+```
+
+#### Fetch associated investigations
+
+```bash
+# Fetch investigations associated with specific alerts
+secops investigation fetch-associated \
+  --detection-type "ALERT" \
+  --alert-ids "alert_123,alert_456" \
+  --association-limit 5
+
+# Fetch investigations associated with a case
+secops investigation fetch-associated \
+  --detection-type "CASE" \
+  --case-ids "case_123"
+
+# Fetch with ordering
+secops investigation fetch-associated \
+  --detection-type "ALERT" \
+  --alert-ids "alert_123" \
+  --order-by "createTime desc"
+```
+
 ### Data Export
 
 List available log types for export:

README.md

@@ -1403,6 +1403,92 @@ case = cases.get_case("case-id-1")
 
 > **Note**: The case management API uses the `legacy:legacyBatchGetCases` endpoint to retrieve multiple cases in a single request. You can retrieve up to 1000 cases in a single batch.
 
+### Investigation Management
+
+Chronicle investigations provide automated analysis and recommendations for alerts and cases. The SDK provides methods to list, retrieve, trigger, and fetch associated investigations.
+
+#### List investigations
+
+Retrieve all investigations in your Chronicle instance:
+
+```python
+# List all investigations
+result = chronicle.list_investigations()
+investigations = result.get("investigations", [])
+
+for inv in investigations:
+    print(f"Investigation: {inv['displayName']}")
+    print(f"  Status: {inv.get('status', 'N/A')}")
+    print(f"  Verdict: {inv.get('verdict', 'N/A')}")
+
+# List with pagination
+result = chronicle.list_investigations(page_size=50, page_token="token")
+```
+
+#### Get investigation details
+
+Retrieve a specific investigation by its ID:
+
+```python
+# Get investigation by ID
+investigation = chronicle.get_investigation(investigation_id="inv_123")
+
+print(f"Name: {investigation['displayName']}")
+print(f"Status: {investigation.get('status')}")
+print(f"Verdict: {investigation.get('verdict')}")
+print(f"Confidence: {investigation.get('confidence')}")
+```
+
+#### Trigger investigation for an alert
+
+Create a new investigation for a specific alert:
+
+```python
+# Trigger investigation for an alert
+investigation = chronicle.trigger_investigation(alert_id="alert_123")
+
+print(f"Investigation created: {investigation['name']}")
+print(f"Status: {investigation.get('status')}")
+print(f"Trigger type: {investigation.get('triggerType')}")
+```
+
+#### Fetch associated investigations
+
+Retrieve investigations associated with alerts or cases:
+
+```python
+from secops.chronicle import DetectionType
+
+# Fetch investigations for specific alerts
+result = chronicle.fetch_associated_investigations(
+    detection_type=DetectionType.ALERT,
+    alert_ids=["alert_123", "alert_456"],
+    association_limit_per_detection=5
+)
+
+# Process associations
+associations_list = result.get("associationsList", {})
+for alert_id, data in associations_list.items():
+    investigations = data.get("investigations", [])
+    print(f"Alert {alert_id}: {len(investigations)} investigation(s)")
+
+    for inv in investigations:
+        print(f"  - {inv['displayName']}: {inv.get('verdict', 'N/A')}")
+
+# Fetch investigations for cases
+case_result = chronicle.fetch_associated_investigations(
+    detection_type=DetectionType.CASE,
+    case_ids=["case_123"],
+    association_limit_per_detection=3
+)
+
+# You can also use string values for detection_type
+result = chronicle.fetch_associated_investigations(
+    detection_type="ALERT",  # or "DETECTION_TYPE_ALERT"
+    alert_ids=["alert_123"]
+)
+```
+
 ### Generating UDM Key/Value Mapping
 Chronicle provides a feature to generate UDM key-value mapping for a given row log.
 

api_module_mapping.md

@@ -221,6 +221,10 @@ Following shows mapping between SecOps [REST Resource](https://cloud.google.com/
 |ingestionLogLabels.list                                                       |v1alpha|                                                            |                                       |
 |ingestionLogNamespaces.get                                                    |v1alpha|                                                            |                                       |
 |ingestionLogNamespaces.list                                                   |v1alpha|                                                            |                                       |
+|investigations.fetchAssociated                                                |v1alpha|chronicle.investigations.fetch_associated_investigations    |secops investigation fetch-associated  |
+|investigations.get                                                            |v1alpha|chronicle.investigations.get_investigation                  |secops investigation get               |
+|investigations.list                                                           |v1alpha|chronicle.investigations.list_investigations                |secops investigation list              |
+|investigations.trigger                                                        |v1alpha|chronicle.investigations.trigger_investigation              |secops investigation trigger           |
 |iocs.batchGet                                                                 |v1alpha|                                                            |                                       |
 |iocs.findFirstAndLastSeen                                                     |v1alpha|                                                            |                                       |
 |iocs.get                                                                      |v1alpha|                                                            |                                       |