add findings result object

Author: Dan Hertz

nightfall/api.py

@@ -14,6 +14,7 @@
 
 from nightfall.detection_rules import DetectionRule
 from nightfall.exceptions import NightfallUserError, NightfallSystemError
+from nightfall.findings import Finding
 
 
 class Nightfall:
@@ -48,16 +49,13 @@ def __init__(self, key: str = None, signing_secret: str = None):
         self.logger = logging.getLogger(__name__)
 
     def scan_text(self, texts: list[str], detection_rule_uuids: list[str] = None,
-                  detection_rules: list[DetectionRule] = None):
+                  detection_rules: list[DetectionRule] = None) -> [list[list[Finding]], list[str]]:
         """Scan text with Nightfall.
 
         This method takes the specified config and then makes
         one or more requests to the Nightfall API for scanning.
+        At least one of detection_rule_uuids or detection_rules is required.
 
-        Either detection_rule_uuids or DetectionRule is required.
-        ::
-            detection_rule_uuids: ["uuid",]
-            detection_rules: [DetectionRule,]
 
         :param texts: List of strings to scan.
         :type texts: list[str]
@@ -70,8 +68,7 @@ def scan_text(self, texts: list[str], detection_rule_uuids: list[str] = None,
         """
 
         if not detection_rule_uuids and not detection_rules:
-            raise NightfallUserError("Need to supply detection rule ids list or detection rules dict with \
-                key 'detection_rule_uuids' or 'detection_rules' respectively", 40001)
+            raise NightfallUserError("at least one of detection_rule_uuids or detection_rules required", 40001)
 
         config = {}
         if detection_rule_uuids:
@@ -88,7 +85,9 @@ def scan_text(self, texts: list[str], detection_rule_uuids: list[str] = None,
 
         parsed_response = response.json()
 
-        return parsed_response["findings"], parsed_response["redactedPayload"]
+        findings = [[Finding.from_dict(f) for f in item_findings] for item_findings in parsed_response["findings"]]
+        return findings, parsed_response.get("redactedPayload")
+
 
     def _scan_text_v3(self, data):
         response = requests.post(
@@ -131,8 +130,8 @@ def scan_file(self, location: str, webhook_url: str, policy_uuid: str = None,
         """
 
         if not policy_uuid and not detection_rule_uuids and not detection_rules:
-            raise NightfallUserError("Need to supply policy id or detection rule ids list or detection rules dict with \
-                key 'policy_uuid', 'detection_rule_uuids', 'detection_rules' respectively", 40001)
+            raise NightfallUserError("at least one of policy_uuid, detection_rule_uuids or detection_rules required",
+                                     40001)
 
         response = self._file_scan_initialize(location)
         _validate_response(response, 200)

nightfall/detection_rules.py

@@ -68,7 +68,9 @@ class ExclusionRule:
     candidate finding from triggering a detector match.
     """
     def __init__(self, match_type: str, regex: Regex = None, word_list: WordList = None):
-        """Instantiate an ExclusionRule object
+        """Instantiate an ExclusionRule object.
+        One of regex or word_list is required.
+
         :param match_type: the match type. One of "FULL" or "PARTIAL".
         :type match_type: str
         :param regex: The regular expression configuration to run on a candidate finding.
@@ -141,7 +143,9 @@ def __init__(
             infotype_substitution: bool = False,
             public_key: str = None
     ):
-        """Instantiate a RedactionConfig object
+        """Instantiate a RedactionConfig object.
+        One of mask_config, substitution_phrase, infotype_substitution or public_key is required.
+
         :param remove_finding: Whether the original finding should be omitted in responses from the API.
         :type remove_finding: bool
         :param mask_config: Build a redaction config with masking.
@@ -194,7 +198,9 @@ def __init__(
             exclusion_rules: list[ExclusionRule] = None,
             redaction_config: RedactionConfig = None
     ):
-        """Instantiate a Detector object
+        """Instantiate a Detector object.
+        One of nightfall_detector, regex, word_list or uuid required.
+
         :param min_confidence: The minimum confidence threshold for the detector trigger a finding.
         :type min_confidence: str
         :param min_num_findings: The minimum number of occurrences of the detector required to trigger a finding.

nightfall/findings.py

@@ -0,0 +1,82 @@
+class Range:
+    """An object representing where a finding was discovered in content."""
+    def __init__(self, start: int, end: int):
+        """Instantiate a Range object.
+        :param start: The start of the range.
+        :type start: int
+        :param end: The end of the range.
+        :type end: int
+        """
+        self.start = start
+        self.end = end
+
+
+class Finding:
+    """An object representing an occurrence of a configured detector (i.e. finding) in the provided data."""
+    def __init__(self,
+                 finding: str,
+                 redacted_finding: str,
+                 before_context: str,
+                 after_context: str,
+                 detector_name: str,
+                 detector_uuid: str,
+                 confidence: str,
+                 byte_range: Range,
+                 codepoint_range: Range,
+                 matched_detection_rule_uuids: list[str],
+                 matched_detection_rules: list[str]):
+        """Instantiate a Finding object.
+        :param finding: The data that triggered a detector match.
+
+        :type finding: str
+        :param redacted_finding: The redacted finding if redaction was configured, None otherwise.
+        :type redacted_finding: str
+        :param before_context: The data that immediately preceded the finding if configured, None otherwise.
+        :type before_context: str
+        :param after_context: The data that immediately succeeded the finding if configured, None otherwise.
+        :type after_context: str
+        :param detector_name: The the name of the detector, if configured, None otherwise.
+        :type detector_name: str
+        :param detector_uuid: The ID that uniquely identifies this detector.
+        :type detector_uuid: str
+        :param confidence: The confidence that the data contained in Finding is an instance of the matched detector.
+        :type confidence: str
+        :param byte_range: The byte range in which a finding was detected within the item.
+        :type byte_range: Range
+        :param codepoint_range: The codepoint range in which a finding was detected within the item. This differs
+            from byte range since a codepoint may contain multiple bytes.
+        :type codepoint_range: Range
+        :param matched_detection_rule_uuids: The list of detection rule UUIDs that contained a detector that triggered a
+            match.
+        :type matched_detection_rule_uuids: list[str]
+        :param matched_detection_rules: The list of inline detection rules that contained a detector that triggered a
+            match.
+        :type matched_detection_rules: list[str]
+        """
+        self.finding = finding
+        self.redacted_finding = redacted_finding
+        self.before_context = before_context
+        self.after_context = after_context
+        self.detector_name = detector_name
+        self.detector_uuid = detector_uuid
+        self.confidence = confidence
+        self.byte_range = byte_range
+        self.codepoint_range = codepoint_range
+        self.matched_detection_rule_uuids = matched_detection_rule_uuids
+        self.matched_detection_rules = matched_detection_rules
+
+    @classmethod
+    def from_dict(cls, resp: dict) -> "Finding":
+        return cls(
+            resp["finding"],
+            resp.get("redactedFinding"),
+            resp.get("beforeContext"),
+            resp.get("afterContext"),
+            resp["detector"].get("name"),
+            resp["detector"].get("uuid"),
+            resp["confidence"],
+            Range(resp["location"]["byteRange"]["start"], resp["location"]["byteRange"]["end"]),
+            Range(resp["location"]["codepointRange"]["start"], resp["location"]["codepointRange"]["end"]),
+            resp["matchedDetectionRuleUUIDs"],
+            resp["matchedDetectionRules"]
+        )