Add support for AlertConfig

Callers may provide an alertConfig object as part of either a synchronous plaintext scan, or an asynchronous file scan to fan alerts out to any of { slack, email, and webhook}.

Author: evanfuller

nightfall/alerts.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass
+
+from typing import List, Tuple, Optional
+
+@dataclass
+class SlackAlert:
+    """SlackAlert contains the configuration required to allow clients to send asynchronous alerts to a Slack
+       workspace when findings are detected. Note that in order for Slack alerts to be delivered to your workspace,
+       you must use authenticate Nightfall to your Slack workspace under the Settings menu on the Nightfall Dashboard.
+
+       Currently, Nightfall supports delivering alerts to public channels, formatted like "#general".
+       Alerts are only sent if findings are detected.
+    Attributes:
+        target (str): the channel name, formatted like "#general".
+    """
+    target: str
+
+    def as_dict(self):
+        return {"target": self.target}
+
+@dataclass
+class EmailAlert:
+    """EmailAlert contains the configuration required to allow clients to send an asynchronous email message
+       when findings are detected. The findings themselves will be delivered as a file attachment on the email.
+       Alerts are only sent if findings are detected.
+    Attributes:
+        address (str): the email address to which alerts should be sent.
+    """
+    address: str
+
+    def as_dict(self):
+        return {"address": self.address}
+
+@dataclass
+class WebhookAlert:
+    """WebhookAlert contains the configuration required to allow clients to send a webhook event to an
+       external URL when findings are detected. The URL provided must (1) use the HTTPS scheme, (2) have a
+       route defined on the HTTP POST method, and (3) return a 200 status code upon receipt of the event.
+        
+       In contrast to other platforms, when using the file scanning APIs, an alert is also sent to this webhook
+       *even when there are no findings*.
+    Attributes:
+        address (str): the URL to which alerts should be sent.
+    """
+    address: str
+
+    def as_dict(self):
+        return {"address": self.address}
+
+@dataclass
+class AlertConfig:
+    """AlertConfig allows clients to specify where alerts should be delivered when findings are discovered as
+       part of a scan. These alerts are delivered asynchronously to all destinations specified in the object instance.
+    Attributes:
+        slack (SlackAlert): Send alerts to a Slack workspace when findings are detected.
+        email (EmailAlert): Send alerts to an email address when findings are detected.
+        url (WebhookAlert): Send an HTTP webhook event to a URL when findings are detected.
+    """
+    slack: Optional[SlackAlert] = None
+    email: Optional[EmailAlert] = None
+    url: Optional[WebhookAlert] = None
+
+    def as_dict(self):
+        result = {}
+        if self.slack:
+            result["slack"] = {"target": self.slack.target}
+        if self.email:
+            result["email"] = {"address": self.email.address}
+        if self.url:
+            result["url"] = {"address": self.url.address}
+        return result
+

nightfall/api.py

@@ -15,6 +15,7 @@
 from requests.adapters import HTTPAdapter
 from urllib3 import Retry
 
+from nightfall.alerts import AlertConfig
 from nightfall.detection_rules import DetectionRule, RedactionConfig
 from nightfall.exceptions import NightfallUserError, NightfallSystemError
 from nightfall.findings import Finding
@@ -57,7 +58,7 @@ def __init__(self, key: Optional[str] = None, signing_secret: Optional[str] = No
 
     def scan_text(self, texts: List[str], policy_uuids: List[str] = None, detection_rules: Optional[List[DetectionRule]] = None,
                   detection_rule_uuids: Optional[List[str]] = None, context_bytes: Optional[int] = None,
-                  default_redaction_config: Optional[RedactionConfig] = None) ->\
+                  default_redaction_config: Optional[RedactionConfig] = None, alert_config: Optional[AlertConfig] = None) ->\
             Tuple[List[List[Finding]], List[str]]:
         """Scan text with Nightfall.
 
@@ -83,6 +84,8 @@ def scan_text(self, texts: List[str], policy_uuids: List[str] = None, detection_
         :param default_redaction_config: The default redaction configuration to apply to all detection rules, unless
             there is a more specific config within a detector.
         :type default_redaction_config: RedactionConfig or None
+        :param alert_config: Configures external destinations to fan out alerts to in the event that findings are detected.
+        :type alert_config: AlertConfig or None
         :returns: list of findings, list of redacted input texts
         """
 
@@ -132,7 +135,8 @@ def _scan_text_v3(self, data: dict):
     def scan_file(self, location: str, webhook_url: Optional[str] = None, policy_uuid: Optional[str] = None,
                   detection_rules: Optional[List[DetectionRule]] = None,
                   detection_rule_uuids: Optional[List[str]] = None,
-                  request_metadata: Optional[str] = None) -> Tuple[str, str]:
+                  request_metadata: Optional[str] = None,
+                  alert_config: Optional[AlertConfig] = None) -> Tuple[str, str]:
         """Scan file with Nightfall.
         At least one of policy_uuid, detection_rule_uuids or detection_rules is required.
 
@@ -146,6 +150,8 @@ def scan_file(self, location: str, webhook_url: Optional[str] = None, policy_uui
         :type detection_rule_uuids: List[str] or None
         :param request_metadata: additional metadata that will be returned with the webhook response
         :type request_metadata: str or None
+        :param alert_config: Configures external destinations to fan out alerts to in the event that findings are detected.
+        :type alert_config: AlertConfig or None
         :returns: (scan_id, message)
         """