Basic Usage (Java)

This guide describes how to use Nightfall with the Java programming language.

The example below will demonstrate how to use Nightfall’s text scanning functionality to verify whether a string contains sensitive PII using the Nightfall Java SDK.

In this tutorial, we will be downloading, setting up, and using the Java SDK provided by Nightfall.

Prerequisites

To make a request to the Nightfall API you will need:

A Nightfall API key
Plaintext data to scan.

You can read more about obtaining a Nightfall API key or about our available (data detectors)[docs:detector-glossary] in the linked reference guides.

Installation

You can add the Nightfall package to your project by adding a dependency to your pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>

     <groupId>com.foo</groupId>
     <artifactId>my-artifact</artifactId>
     <version>1.0.0</version>

     <name>${project.groupId}:${project.artifactId}</name>
     <packaging>jar</packaging>

     <dependencies>
         <dependency>
             <groupId>ai.nightfall</groupId>
             <artifactId>scan-api</artifactId>
             <version>1.0.1</version>
         </dependency>
     </dependencies>
 </project>

Starting an Example Java Program

First add the required imports to the top of the file.

These are the objects we will use from the Nightfall SDK, as well as some collection classes for data handling.

import ai.nightfall.scan.NightfallClient;
 import ai.nightfall.scan.model.Confidence;
 import ai.nightfall.scan.model.DetectionRule;
 import ai.nightfall.scan.model.Detector;
 import ai.nightfall.scan.model.LogicalOp;
 import ai.nightfall.scan.model.NightfallAPIException;
 import ai.nightfall.scan.model.ScanTextConfig;
 import ai.nightfall.scan.model.ScanTextRequest;
 import ai.nightfall.scan.model.ScanTextResponse;

 import java.util.Arrays;
 import java.util.List;

We can then declare some data to scan in a List:

List<String> payload = Arrays.asList(
  "hello", 
  "world", 
  "my data is 4242-4242-4242-4242 but shhhh 🙊 ", 
  "my ssn is 678-99-8212"
);

Create a ScanTextRequest to scan the payload with. First create a new instance of the credit card detector, and set to trigger if there are any findings that are confidence LIKELY or above.

Add a second detector, looking for social security numbers. Set it to be triggered if there is at least a possible finding.

Combine these detectors into a detection rule, which will return findings if either of these detectors are triggered.

Finally, combine the payload and configuration together as a new ScanTextRequest, and return it.

public static ScanTextRequest buildScanTextRequest() {
  	// 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);
    DetectionRule rule = new DetectionRule(Arrays.asList(creditCard, ssn), LogicalOp.ANY);
    ScanTextConfig config = ScanTextConfig.fromDetectionRules(Arrays.asList(rule), 20);

    return new ScanTextRequest(payload, config);
}

Use the ScanTextRequest instance with a NightfallClient to send your request to Nightfall.

The resulting ScanTextResponse may be used to print out the results:

public class Runner {
     public static void main(String[] args) {
         try (NightfallClient c = NightfallClient.Builder.defaultClient()) {
             try {
                 ScanTextResponse response = c.scanText(buildScanTextRequest());
                 System.out.println("response: " + response.getFindings());
             } catch (NightfallAPIException e) {
                 // not a checked exception, just for illustrative purposes
                 System.out.println("got error: " + e);
             }
         }
     }
 }

And that's it!

You are now ready to use the Java SDK for other scenarios.