Merge pull request #59 from JupiterOne/TD-7432

add 5 new input parameters to the alert rule methods

Author: erincrawford

README.md

@@ -905,6 +905,24 @@ complex_rule = j1.create_alert_rule(
     AND u.tag.Role != 'admin'
     """
 )
+
+# Create alert rule with advanced configuration options
+advanced_rule = j1.create_alert_rule(
+    name="Advanced Security Monitoring",
+    description="Comprehensive security monitoring with custom settings",
+    tags=['security', 'monitoring'],
+    polling_interval="ONE_HOUR",
+    severity="HIGH",
+    j1ql="FIND Finding WITH severity = 'HIGH'",
+    query_name="security_findings",  # Custom query name
+    trigger_actions_on_new_entities_only=False,  # Trigger on all entities
+    ignore_previous_results=True,  # Ignore previous evaluation results
+    notify_on_failure=True,  # Notify on evaluation failures
+    templates={  # Custom templates for alert content
+        "AlertSummary": "Security Finding: {{item.displayName}} - Severity: {{item.severity}}",
+        "DetailedReport": "Finding ID: {{item._id}}\nDescription: {{item.description}}\nSeverity: {{item.severity}}"
+    }
+)
 ```
 
 ##### Create Alert Rule with Action Config
@@ -1127,7 +1145,14 @@ updated_rule = j1.update_alert_rule(
     tag_op="OVERWRITE",
     severity="INFO",
     action_configs=alert_rule_config_tag,
-    action_configs_op="OVERWRITE"
+    action_configs_op="OVERWRITE",
+    query_name="updated_findings",  # Update query name
+    trigger_actions_on_new_entities_only=False,  # Update trigger behavior
+    ignore_previous_results=True,  # Update result handling
+    notify_on_failure=False,  # Update notification settings
+    templates={  # Update templates
+        "NewTemplate": "Updated: {{item.displayName}} - {{item.severity}}"
+    }
 )
 
 # Update only tags (overwrite existing)
@@ -1156,6 +1181,24 @@ j1.update_alert_rule(
     polling_interval="THIRTY_MINUTES",
     severity="HIGH"
 )
+
+# Update advanced configuration parameters
+j1.update_alert_rule(
+    rule_id='<id-of-alert-rule>',
+    query_name="custom_query_name",  # Update query name
+    trigger_actions_on_new_entities_only=True,  # Only trigger on new entities
+    ignore_previous_results=False,  # Consider previous results
+    notify_on_failure=True  # Notify on evaluation failures
+)
+
+# Update templates for alert content
+j1.update_alert_rule(
+    rule_id='<id-of-alert-rule>',
+    templates={
+        "SecurityAlert": "Security Issue: {{item.displayName}}",
+        "ComplianceReport": "Compliance Violation: {{item.description}}"
+    }
+)
 ```
 
 ##### Evaluate Alert Rule

examples/05_alert_rules_and_smartclasses.py

@@ -38,6 +38,26 @@ def alert_rule_examples(j1):
     )
     print(f"Created basic alert rule: {basic_rule['id']}\n")
 
+    # 1.5. Advanced alert rule with new parameters
+    print("1.5. Creating an advanced alert rule with new parameters:")
+    advanced_rule = j1.create_alert_rule(
+        name="Advanced Security Monitoring",
+        description="Comprehensive security monitoring with custom settings",
+        tags=['security', 'monitoring'],
+        polling_interval="ONE_HOUR",
+        severity="HIGH",
+        j1ql="FIND Finding WITH severity = 'HIGH'",
+        query_name="security_findings",  # Custom query name
+        trigger_actions_on_new_entities_only=False,  # Trigger on all entities
+        ignore_previous_results=True,  # Ignore previous evaluation results
+        notify_on_failure=True,  # Notify on evaluation failures
+        templates={  # Custom templates for alert content
+            "AlertSummary": "Security Finding: {{item.displayName}} - Severity: {{item.severity}}",
+            "DetailedReport": "Finding ID: {{item._id}}\nDescription: {{item.description}}\nSeverity: {{item.severity}}"
+        }
+    )
+    print(f"Created advanced alert rule: {advanced_rule['id']}\n")
+    
     # 2. Complex alert rule with multiple conditions
     print("2. Creating a complex alert rule:")
     complex_rule = j1.create_alert_rule(
@@ -57,7 +77,7 @@ def alert_rule_examples(j1):
     )
     print(f"Created complex alert rule: {complex_rule['id']}\n")
 
-    return basic_rule, complex_rule
+    return basic_rule, advanced_rule, complex_rule
 
 def alert_rule_with_actions_examples(j1):
     """Demonstrate alert rules with action configurations."""
@@ -206,13 +226,50 @@ def alert_rule_management_examples(j1, rule_id):
             polling_interval="ONE_WEEK",
             tags=['security', 'compliance', 'updated'],
             tag_op="OVERWRITE",
-            severity="INFO"
+            severity="INFO",
+            query_name="updated_findings",  # Update query name
+            trigger_actions_on_new_entities_only=False,  # Update trigger behavior
+            ignore_previous_results=True,  # Update result handling
+            notify_on_failure=False,  # Update notification settings
+            templates={  # Update templates
+                "NewTemplate": "Updated: {{item.displayName}} - {{item.severity}}"
+            }
         )
         print(f"Updated alert rule: {updated_rule['id']}")
     except Exception as e:
         print(f"Error updating alert rule: {e}")
     print()
 
+    # 3.5. Update specific advanced parameters
+    print("3.5. Updating specific advanced parameters:")
+    try:
+        # Update only query name
+        j1.update_alert_rule(
+            rule_id=rule_id,
+            query_name="custom_query_name"
+        )
+        print("Updated query name")
+        
+        # Update trigger behavior
+        j1.update_alert_rule(
+            rule_id=rule_id,
+            trigger_actions_on_new_entities_only=True
+        )
+        print("Updated trigger behavior")
+        
+        # Update templates
+        j1.update_alert_rule(
+            rule_id=rule_id,
+            templates={
+                "SecurityAlert": "Security Issue: {{item.displayName}}",
+                "ComplianceReport": "Compliance Violation: {{item.description}}"
+            }
+        )
+        print("Updated templates")
+    except Exception as e:
+        print(f"Error updating advanced parameters: {e}")
+    print()
+    
     # 4. Evaluate alert rule
     print("4. Evaluating alert rule:")
     try:
@@ -406,7 +463,7 @@ def main():
         print("✓ Client setup successful\n")
 
         # Run examples
-        basic_rule, complex_rule = alert_rule_examples(j1)
+        basic_rule, advanced_rule, complex_rule = alert_rule_examples(j1)
         webhook_rule, multi_action_rule = alert_rule_with_actions_examples(j1)
 
         # Alert rule management (using the basic rule)

jupiterone/client.py

@@ -1032,21 +1032,26 @@ def create_alert_rule(
         j1ql: str = None,
         action_configs: Union[Dict, List[Dict]] = None,
         resource_group_id: str = None,
+        query_name: str = "query0",
+        trigger_actions_on_new_entities_only: bool = True,
+        ignore_previous_results: bool = False,
+        notify_on_failure: bool = True,
+        templates: Dict[str, str] = None,
     ):
         """Create Alert Rule Configuration in J1 account"""
 
         variables = {
             "instance": {
                 "name": name,
                 "description": description,
-                "notifyOnFailure": True,
-                "triggerActionsOnNewEntitiesOnly": True,
-                "ignorePreviousResults": False,
+                "notifyOnFailure": notify_on_failure,
+                "triggerActionsOnNewEntitiesOnly": trigger_actions_on_new_entities_only,
+                "ignorePreviousResults": ignore_previous_results,
                 "operations": [
                     {
                         "when": {
                             "type": "FILTER",
-                            "condition": ["AND", ["queries.query0.total", ">", 0]],
+                            "condition": ["AND", [f"queries.{query_name}.total", ">", 0]],
                         },
                         "actions": [
                             {
@@ -1064,7 +1069,7 @@ def create_alert_rule(
                     "queries": [
                         {
                             "query": j1ql,
-                            "name": "query0",
+                            "name": query_name,
                             "version": "v1",
                             "includeDeleted": False,
                         }
@@ -1073,7 +1078,7 @@ def create_alert_rule(
                 "specVersion": 1,
                 "tags": tags,
                 "labels": labels,
-                "templates": {},
+                "templates": templates if templates is not None else {},
                 "resourceGroupId": resource_group_id,
             }
         }
@@ -1112,6 +1117,11 @@ def update_alert_rule(
         action_configs: Union[Dict, List[Dict]] = None,
         action_configs_op: str = None,
         resource_group_id: str = None,
+        query_name: str = None,
+        trigger_actions_on_new_entities_only: bool = None,
+        ignore_previous_results: bool = None,
+        notify_on_failure: bool = None,
+        templates: Dict[str, str] = None,
     ):
         """Update Alert Rule Configuration in J1 account"""
         # fetch existing alert rule
@@ -1151,6 +1161,13 @@ def update_alert_rule(
             del question_config["__typename"]
             del question_config["queries"][0]["__typename"]
 
+        # update query name if provided
+        if query_name is not None:
+            # update query name in question config
+            question_config["queries"][0]["name"] = query_name
+            # update condition reference to use new query name
+            operations[0]["when"]["condition"] = ["AND", [f"queries.{query_name}.total", ">", 0]]
+
         # update polling_interval if provided
         if polling_interval is not None:
             interval_config = polling_interval
@@ -1171,6 +1188,8 @@ def update_alert_rule(
         # update labels list if provided
         if labels is not None:
             label_config = labels
+        else:
+            label_config = alert_rule_config.get("labels", [])
 
         # update action_configs list if provided
         if action_configs is not None:
@@ -1203,18 +1222,46 @@ def update_alert_rule(
         if severity is not None:
             operations[0]["actions"][0]["targetValue"] = severity
 
+        # update trigger_actions_on_new_entities_only if provided
+        if trigger_actions_on_new_entities_only is not None:
+            trigger_config = trigger_actions_on_new_entities_only
+        else:
+            trigger_config = alert_rule_config["triggerActionsOnNewEntitiesOnly"]
+
+        # update ignore_previous_results if provided
+        if ignore_previous_results is not None:
+            ignore_config = ignore_previous_results
+        else:
+            ignore_config = alert_rule_config["ignorePreviousResults"]
+
+        # update notify_on_failure if provided
+        if notify_on_failure is not None:
+            notify_config = notify_on_failure
+        else:
+            notify_config = alert_rule_config["notifyOnFailure"]
+
+        # update templates if provided
+        if templates is not None:
+            templates_config = templates
+        else:
+            templates_config = alert_rule_config["templates"]
+
         variables = {
             "instance": {
                 "id": rule_id,
                 "version": rule_version,
                 "specVersion": alert_rule_config["specVersion"],
                 "name": alert_name,
                 "description": alert_description,
+                "notifyOnFailure": notify_config,
+                "triggerActionsOnNewEntitiesOnly": trigger_config,
+                "ignorePreviousResults": ignore_config,
                 "question": question_config,
                 "operations": operations,
                 "pollingInterval": interval_config,
                 "tags": tags_config,
                 "labels": label_config,
+                "templates": templates_config,
                 "resourceGroupId": resource_group_id,
             }
         }

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name="jupiterone",
-    version="1.6.1",
+    version="1.7.0",
     description="A Python client for the JupiterOne API",
     license="MIT License",
     author="JupiterOne",