Add classes for redaction support (#17)

Author: evanfuller

Makefile

@@ -1,11 +1,11 @@
 
 BUILD_DIR=build
 
-VERSION=0.1
+VERSION=1.0.0
 
-NAME=dlp-scan
-ARTIFACT=dlp-scan-$(VERSION).jar
-SHADED=dlp-scan-$(VERSION)-shaded.jar
+NAME=scan-api
+ARTIFACT=$(NAME)-$(VERSION).jar
+SHADED=$(NAME)-$(VERSION)-shaded.jar
 
 all: jar
 

README.md

@@ -69,12 +69,14 @@ try (NightfallClient c = NightfallClient.Builder.defaultClient()) {
 
     // Define some detectors to use to scan your data
     Detector creditCard = new Detector("CREDIT_CARD_NUMBER");
+    creditCard.setMinConfidence(Confidence.LIKELY);
+    creditCard.setMinNumFindings(1);
     Detector ssn = new Detector("US_SOCIAL_SECURITY_NUMBER");
+    ssn.setMinConfidence(Confidence.POSSIBLE);
+    ssn.setMinNumFindings(1);
 
     // A rule contains a set of detectors to scan with
-    DetectionRule rule = new DetectionRule();
-    rule.setDetectors(Arrays.asList(creditCard, ssn));
-    rule.setLogicalOp("ANY");
+    DetectionRule rule = new DetectionRule(Arrays.asList(creditCard, ssn), LogicalOp.ANY);
 
     List<String> payload = Arrays.asList("hello world", "my SSN is 678-99-8212", "4242-4242-4242-4242");
     ScanTextConfig config = ScanTextConfig.fromDetectionRuleUUIDs(Arrays.asList(rule), 20);
@@ -109,12 +111,14 @@ try (NightfallClient c = NightfallClient.Builder.defaultClient()) {
 
     // Define some detectors to use to scan your data
     Detector creditCard = new Detector("CREDIT_CARD_NUMBER");
+    creditCard.setMinConfidence(Confidence.LIKELY);
+    creditCard.setMinNumFindings(1);
     Detector ssn = new Detector("US_SOCIAL_SECURITY_NUMBER");
+    ssn.setMinConfidence(Confidence.POSSIBLE);
+    ssn.setMinNumFindings(1);
 
     // A rule contains a set of detectors to scan with
-    DetectionRule rule = new DetectionRule();
-    rule.setDetectors(Arrays.asList(creditCard, ssn));
-    rule.setLogicalOp("ANY");
+    DetectionRule rule = new DetectionRule(Arrays.asList(creditCard, ssn), LogicalOp.ANY);
 
     // File scans are conducted asynchronously, so provide a webhook route to an HTTPS server to send results to.
     String webhookResponseListenerURL = "https://my-service.com/nightfall/listener";

src/main/java/ai/nightfall/scan/model/Confidence.java

@@ -0,0 +1,12 @@
+package ai.nightfall.scan.model;
+
+/**
+ * Confidence describes the certainty that a piece of content matches a detector.
+ */
+public enum Confidence {
+    VERY_UNLIKELY,
+    UNLIKELY,
+    POSSIBLE,
+    LIKELY,
+    VERY_LIKELY
+}

src/main/java/ai/nightfall/scan/model/ConfidenceAdjustment.java

@@ -9,14 +9,14 @@
  */
 public class ConfidenceAdjustment {
     @JsonProperty("fixedConfidence")
-    private String fixedConfidence;
+    private Confidence fixedConfidence;
 
     /**
      * Create a ConfidenceAdjustment object.
      *
      * @param fixedConfidence the confidence to adjust to if external criteria are met.
      */
-    public ConfidenceAdjustment(String fixedConfidence) {
+    public ConfidenceAdjustment(Confidence fixedConfidence) {
         this.fixedConfidence = fixedConfidence;
     }
 
@@ -25,7 +25,7 @@ public ConfidenceAdjustment(String fixedConfidence) {
      *
      * @return the confidence to adjust to
      */
-    public String getFixedConfidence() {
+    public Confidence getFixedConfidence() {
         return fixedConfidence;
     }
 }

src/main/java/ai/nightfall/scan/model/DetectionRule.java

@@ -16,11 +16,35 @@ public class DetectionRule {
     private List<Detector> detectors;
 
     @JsonProperty("logicalOp")
-    private String logicalOp;
+    private LogicalOp logicalOp;
 
     @JsonProperty("name")
     private String name;
 
+    /**
+     * Create a detection rule with the provided detectors and logicalOp.
+     *
+     * @param detectors a list of detectors
+     * @param logicalOp a logical op: ANY or ALL
+     */
+    public DetectionRule(List<Detector> detectors, LogicalOp logicalOp) {
+        this.detectors = detectors;
+        this.logicalOp = logicalOp;
+    }
+
+    /**
+     * Create a detection rule with the provided detectors and logicalOp.
+     *
+     * @param detectors a list of detectors
+     * @param logicalOp a logical op: ANY or ALL
+     * @param name a name for the detection rule
+     */
+    public DetectionRule(List<Detector> detectors, LogicalOp logicalOp, String name) {
+        this.detectors = detectors;
+        this.logicalOp = logicalOp;
+        this.name = name;
+    }
+
     /**
      * Get the list of detectors.
      *
@@ -44,7 +68,7 @@ public void setDetectors(List<Detector> detectors) {
      *
      * @return the logical op
      */
-    public String getLogicalOp() {
+    public LogicalOp getLogicalOp() {
         return logicalOp;
     }
 
@@ -53,7 +77,7 @@ public String getLogicalOp() {
      *
      * @param logicalOp a logical op; valid values <code>ANY</code> or <code>ALL</code>
      */
-    public void setLogicalOp(String logicalOp) {
+    public void setLogicalOp(LogicalOp logicalOp) {
         this.logicalOp = logicalOp;
     }
 

src/main/java/ai/nightfall/scan/model/Detector.java

@@ -1,5 +1,6 @@
 package ai.nightfall.scan.model;
 
+import ai.nightfall.scan.model.redaction.RedactionConfig;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import java.util.List;
@@ -12,7 +13,7 @@
 public class Detector {
 
     @JsonProperty("minConfidence")
-    private String minConfidence;
+    private Confidence minConfidence;
 
     @JsonProperty("minNumFindings")
     private int minNumFindings;
@@ -41,6 +42,9 @@ public class Detector {
     @JsonProperty("exclusionRules")
     private List<ExclusionRule> exclusionRules;
 
+    @JsonProperty("redactionConfig")
+    private RedactionConfig redactionConfig;
+
     /**
      * Create an instance of a detector based on a pre-built Nightfall detector.
      *
@@ -87,17 +91,16 @@ public Detector(UUID detectorUUID) {
      *
      * @return the minimum confidence threshold required in order for a finding to be triggered
      */
-    public String getMinConfidence() {
+    public Confidence getMinConfidence() {
         return minConfidence;
     }
 
     /**
      * Set the minimum confidence.
      *
-     * @param minConfidence the minimum confidence threshold. Valid values: <code>VERY_UNLIKELY</code>,
-     *                      <code>UNLIKELY</code>, <code>POSSIBLE</code>, <code>LIKELY</code>, <code>VERY_LIKELY</code>.
+     * @param minConfidence the minimum confidence threshold.
      */
-    public void setMinConfidence(String minConfidence) {
+    public void setMinConfidence(Confidence minConfidence) {
         this.minConfidence = minConfidence;
     }
 
@@ -222,6 +225,26 @@ public void setExclusionRules(List<ExclusionRule> exclusionRules) {
         this.exclusionRules = exclusionRules;
     }
 
+    /**
+     * Returns the redaction configuration to-be-applied to this detector. This configuration is currently only
+     * supported for scanning plaintext, not for file scanning.
+     *
+     * @return the redaction configuration
+     */
+    public RedactionConfig getRedactionConfig() {
+        return redactionConfig;
+    }
+
+    /**
+     * Sets the redaction configuration to-be-applied to this detector. This configuration is currently only
+     * supported for scanning plaintext, not for file scanning.
+     *
+     * @param redactionConfig the redaction configuration
+     */
+    public void setRedactionConfig(RedactionConfig redactionConfig) {
+        this.redactionConfig = redactionConfig;
+    }
+
     @Override
     public String toString() {
         return "Detector{"
@@ -235,6 +258,7 @@ public String toString() {
                 + ", wordList=" + wordList
                 + ", contextRules=" + contextRules
                 + ", exclusionRules=" + exclusionRules
+                + ", redactionConfig=" + redactionConfig
                 + '}';
     }
 }

src/main/java/ai/nightfall/scan/model/Finding.java

@@ -12,6 +12,9 @@ public class Finding {
     @JsonProperty("finding")
     private String finding;
 
+    @JsonProperty("redactedFinding")
+    private String redactedFinding;
+
     @JsonProperty("beforeContext")
     private String beforeContext;
 
@@ -27,6 +30,9 @@ public class Finding {
     @JsonProperty("location")
     private Location location;
 
+    @JsonProperty("redactedLocation")
+    private Location redactedLocation;
+
     @JsonProperty("matchedDetectionRuleUUIDs")
     private List<UUID> matchedDetectionRuleUUIDs;
 
@@ -42,6 +48,16 @@ public String getFinding() {
         return finding;
     }
 
+    /**
+     * Returns the redacted finding. This will only be non-empty if redaction configuration was provided
+     * as part of the request payload.
+     *
+     * @return the redacted finding
+     */
+    public String getRedactedFinding() {
+        return redactedFinding;
+    }
+
     /**
      * Get the preceding context.
      *
@@ -81,12 +97,22 @@ public String getConfidence() {
     /**
      * Get the location of the finding.
      *
-     * @return the location where the data was in the original input file
+     * @return the location where the data was in the original content
      */
     public Location getLocation() {
         return location;
     }
 
+    /**
+     * Get the location that the redacted finding would occupy in the original content if it were to replace
+     * the finding.
+     *
+     * @return the location that the data occupies in its redacted form with regard to the original content
+     */
+    public Location getRedactedLocation() {
+        return redactedLocation;
+    }
+
     /**
      * Get the list of matched detection rule UUIDs.
      *
@@ -109,11 +135,13 @@ public List<String> getMatchedDetectionRules() {
     public String toString() {
         return "Finding{"
                 + "finding='" + finding + '\''
+                + ", redactedFinding='" + redactedFinding + '\''
                 + ", beforeContext='" + beforeContext + '\''
                 + ", afterContext='" + afterContext + '\''
                 + ", detector=" + detector
                 + ", confidence='" + confidence + '\''
                 + ", location=" + location
+                + ", redactedLocation=" + redactedLocation
                 + ", matchedDetectionRuleUUIDs=" + matchedDetectionRuleUUIDs
                 + ", matchedDetectionRules=" + matchedDetectionRules
                 + '}';

src/main/java/ai/nightfall/scan/model/LogicalOp.java

@@ -0,0 +1,15 @@
+package ai.nightfall.scan.model;
+
+/**
+ * A modifier that is used to decide when a finding should be surfaced in the context of a detection rule.
+ *
+ * <p>When <code>ALL</code> is specified, all detectors in a detection rule must trigger a match in order for the
+ * finding to be reported. This is the equivalent of a logical "AND" operator.
+ *
+ * <p>When <code>ANY</code> is specified, only one of the detectors in a detection rule must trigger a match in order
+ * for the finding to be reported. This is the equivalent of a logical "OR" operator.
+ */
+public enum LogicalOp {
+    ANY,
+    ALL
+}

src/main/java/ai/nightfall/scan/model/ScanTextResponse.java

@@ -13,6 +13,9 @@ public class ScanTextResponse {
     @JsonProperty("findings")
     private List<List<Finding>> findings;
 
+    @JsonProperty("redactedPayload")
+    private List<String> redactedPayload;
+
     /**
      * Get the findings.
      *
@@ -21,4 +24,22 @@ public class ScanTextResponse {
     public List<List<Finding>> getFindings() {
         return findings;
     }
+
+    /**
+     * Return the original request content with the configured redactions applied. If redaction was not
+     * applied for a given input string, the string at a given index in the array will be empty.
+     *
+     * @return the original content with the configured redactions applied
+     */
+    public List<String> getRedactedPayload() {
+        return redactedPayload;
+    }
+
+    @Override
+    public String toString() {
+        return "ScanTextResponse{"
+                + "findings=" + findings
+                + ", redactedPayload=" + redactedPayload
+                + '}';
+    }
 }

src/main/java/ai/nightfall/scan/model/redaction/CryptoConfig.java

@@ -0,0 +1,47 @@
+package ai.nightfall.scan.model.redaction;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * An object that specifies how findings should be encrypted when returned by the API. Currently, encryption
+ * is only supported for RSA public keys.
+ */
+public class CryptoConfig {
+
+    @JsonProperty("publicKey")
+    private String publicKey;
+
+    /**
+     * Builds a configuration object with the provided PEM-formatted RSA public key.
+     *
+     * @param publicKey a PEM-formatted RSA public key.
+     */
+    public CryptoConfig(String publicKey) {
+        this.publicKey = publicKey;
+    }
+
+    /**
+     * Get the public key.
+     *
+     * @return the public key
+     */
+    public String getPublicKey() {
+        return publicKey;
+    }
+
+    /**
+     * Set the public key.
+     *
+     * @param publicKey the public key
+     */
+    public void setPublicKey(String publicKey) {
+        this.publicKey = publicKey;
+    }
+
+    @Override
+    public String toString() {
+        return "CryptoConfig{"
+                + "publicKey='" + publicKey + '\''
+                + '}';
+    }
+}