Add policyUUIDs to text scan endpoint

Add policyUUIDs to text scan endpoint

Author: evanfuller

nightfall/api.py

@@ -55,19 +55,24 @@ def __init__(self, key: Optional[str] = None, signing_secret: Optional[str] = No
             'Authorization': f'Bearer {self.key}',
         }
 
-    def scan_text(self, texts: List[str], detection_rules: Optional[List[DetectionRule]] = None,
+    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) ->\
             Tuple[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.
 
+        A caller must provide exactly one of the following:
+            * a non-empty policy_uuids list (current maximum supported length = 1)
+            * at least one of detection_rule_uuids or detection_rules
 
         :param texts: List of strings to scan.
         :type texts: List[str]
+        :param policy_uuids: List of policy UUIDs to scan each text with.
+            These can be created in the Nightfall UI.
+        :type policy_uuids: List[str] or None
         :param detection_rules: List of detection rules to scan each text with.
         :type detection_rules: List[DetectionRule] or None
         :param detection_rule_uuids: List of detection rule UUIDs to scan each text with.
@@ -81,22 +86,26 @@ def scan_text(self, texts: List[str], detection_rules: Optional[List[DetectionRu
         :returns: list of findings, list of redacted input texts
         """
 
-        if not detection_rule_uuids and not detection_rules:
-            raise NightfallUserError("at least one of detection_rule_uuids or detection_rules required", 40001)
+        if not policy_uuids and not detection_rule_uuids and not detection_rules:
+            raise NightfallUserError("at least one of policy_uuids, detection_rule_uuids, or detection_rules is required", 40001)
 
-        config = {}
+        policy = {}
         if detection_rule_uuids:
-            config["detectionRuleUUIDs"] = detection_rule_uuids
+            policy["detectionRuleUUIDs"] = detection_rule_uuids
         if detection_rules:
-            config["detectionRules"] = [d.as_dict() for d in detection_rules]
+            policy["detectionRules"] = [d.as_dict() for d in detection_rules]
         if context_bytes:
-            config["contextBytes"] = context_bytes
+            policy["contextBytes"] = context_bytes
         if default_redaction_config:
-            config["defaultRedactionConfig"] = default_redaction_config.as_dict()
+            policy["defaultRedactionConfig"] = default_redaction_config.as_dict()
+
         request_body = {
-            "payload": texts,
-            "config": config
+            "payload": texts
         }
+        if policy:
+            request_body["policy"] = policy
+        if policy_uuids:
+            request_body["policyUUIDs"] = policy_uuids
         response = self._scan_text_v3(request_body)
 
         _validate_response(response, 200)

tests/test_api.py

@@ -224,7 +224,7 @@ def test_scan_text():
             [
                 "4916-6734-7572-5015 is my credit card number, 489-36-8350 ssn"
             ],
-        "config":
+        "policy":
             {
                 "detectionRules":
                     [
@@ -332,8 +332,92 @@ def test_scan_text():
     assert len(redactions) == 1
     assert redactions[0] == "491👀-👀👀👀👀-👀👀👀👀-👀👀👀👀 is my credit card number, [REDACTED] ssn"
 
+@responses.activate
+def test_scan_text_with_policy_uuids():
+    nightfall = Nightfall("NF-NOT_REAL")
+    responses.add(responses.POST, 'https://api.nightfall.ai/v3/scan',
+                  json={
+                      "findings":
+                          [
+                              [
+                                  {
+                                      "finding": "4916-6734-7572-5015",
+                                      "redactedFinding": "491👀-👀👀👀👀-👀👀👀👀-👀👀👀👀",
+                                      "afterContext": " is my cre",
+                                      "detector":
+                                          {
+                                              "name": "Credit Card Number",
+                                              "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
+                                          },
+                                      "confidence": "VERY_LIKELY",
+                                      "location":
+                                          {
+                                              "byteRange":
+                                                  {
+                                                      "start": 0,
+                                                      "end": 19
+                                                  },
+                                              "codepointRange":
+                                                  {
+                                                      "start": 0,
+                                                      "end": 19
+                                                  }
+                                          },
+                                      "redactedLocation":
+                                          {
+                                              "byteRange":
+                                                  {
+                                                      "start": 0,
+                                                      "end": 19
+                                                  },
+                                              "codepointRange":
+                                                  {
+                                                      "start": 0,
+                                                      "end": 19
+                                                  }
+                                          },
+                                      "matchedDetectionRuleUUIDs":
+                                          ["0d8efd7b-b87a-478b-984e-9cf5534a46bc"],
+                                      "matchedDetectionRules":
+                                          []
+                                  },
+                              ]
+                          ],
+                      "redactedPayload":
+                          [
+                              "491👀-👀👀👀👀-👀👀👀👀-👀👀👀👀 is my credit card number, [REDACTED] ssn"
+                          ]
+                  })
+    result, redactions = nightfall.scan_text(
+        ["4916-6734-7572-5015 is my credit card number, 489-36-8350 ssn"],
+        policy_uuids=["2388f83f-cd31-4689-971b-4ee94f798281"]
+    )
+
+    assert len(responses.calls) == 1
+    assert responses.calls[0].request.headers.get("Authorization") == "Bearer NF-NOT_REAL"
+    assert json.loads(responses.calls[0].request.body) == {
+        "payload":
+            [
+                "4916-6734-7572-5015 is my credit card number, 489-36-8350 ssn"
+            ],
+        "policyUUIDs": ["2388f83f-cd31-4689-971b-4ee94f798281"]
+    }
+
+    assert len(result) == 1
+    assert len(result[0]) == 1
+    assert result[0][0] == Finding(
+        "4916-6734-7572-5015",
+        '491👀-👀👀👀👀-👀👀👀👀-👀👀👀👀',
+        None, " is my cre",
+        "Credit Card Number",
+        result[0][0].detector_uuid,
+        Confidence.VERY_LIKELY,
+        Range(0, 19), Range(0, 19), "",
+        ["0d8efd7b-b87a-478b-984e-9cf5534a46bc"], [])
+    assert len(redactions) == 1
+    assert redactions[0] == "491👀-👀👀👀👀-👀👀👀👀-👀👀👀👀 is my credit card number, [REDACTED] ssn"
 
-def test_scan_text_no_detection_rules():
+def test_scan_text_no_detection_rules_or_policy_uuids():
     nightfall = Nightfall("NF-NOT_REAL")
     with pytest.raises(NightfallUserError):
         nightfall.scan_text(texts=["will", "fail"])