This page will get you up and running with the Nightfall API so you can start scanning for sensitive data.

Obtain an API key

The Nightfall API requires a valid API key to authenticate your API requests.

You can create API keys in the Dashboard.

Learn more about Authentication and Security.

Make an API Scan Request

Below is an example request to the scan endpoint.

To run this example yourself, replace the API key (NF-rEpLaCe...) with the one you created in the dashboard or set it as the environment variable NIGHTFALL_API_KEY as necessary.

The cURL example may be run from the command line without any additional installation. To run the Python example, you will need to download the corresponding SDK.

curl --request POST \
     --url https://api.nightfall.ai/v3/scan \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer  NF-rEpLaCeM3w1ThYoUrNiGhTfAlLKeY123' \
     --header 'Content-Type: application/json' \
     --data '
{
     "policy": {
          "detectionRules": [
               {
                    "detectors": [
                         {
                              "minNumFindings": 1,
                              "minConfidence": "LIKELY",
                              "displayName": "US Social Security Number",
                              "detectorType": "NIGHTFALL_DETECTOR",
                              "nightfallDetector": "US_SOCIAL_SECURITY_NUMBER"
                         },
                         {
                              "redactionConfig": {
                                   "maskConfig": {
                                        "charsToIgnore": [
                                             "-"
                                        ],
                                        "maskingChar": "#"
                                   }
                              },
                              "minNumFindings": 1,
                              "minConfidence": "LIKELY",
                              "displayName": "Credit Card Number",
                              "detectorType": "NIGHTFALL_DETECTOR",
                              "nightfallDetector": "CREDIT_CARD_NUMBER"
                         }
                    ],
                    "name": "My Match Rule",
                    "logicalOp": "ANY"
               }
          ]
     },
     "payload": [
          "The customer social security number is 458-02-6124",
          "No PII in this string",
          "My credit card number is 5310-2768-6832-9293"
     ]
}
'

// By default, the client reads your API key from the environment variable NIGHTFALL_API_KEY
const nfClient = new Nightfall();

const payload = [
          "The customer social security number is 458-02-6124",
          "No PII in this string",
          "My credit card number is 5310-2768-6832-9293"
     ];
     

const policy = {
		 "detectionRules": [
               {
                    "detectors": [
                         {
                              "minNumFindings": 1,
                              "minConfidence": "LIKELY",
                              "displayName": "US Social Security Number",
                              "detectorType": "NIGHTFALL_DETECTOR",
                              "nightfallDetector": "US_SOCIAL_SECURITY_NUMBER"
                         },
                         {
                              "redactionConfig": {
                                   "maskConfig": {
                                        "charsToIgnore": [
                                             "-"
                                        ],
                                        "maskingChar": "#"
                                   }
                              },
                              "minNumFindings": 1,
                              "minConfidence": "LIKELY",
                              "displayName": "Credit Card Number",
                              "detectorType": "NIGHTFALL_DETECTOR",
                              "nightfallDetector": "CREDIT_CARD_NUMBER"
                         }
                    ],
                    "name": "My Match Rule",
                    "logicalOp": "ANY"
               }
          ]
     };
     
const response = await nfClient.scanText(payload, policy);

if (response.isError) {
  console.log(response.getError());
} else {
  response.data.findings.forEach((finding) => {
    if (finding.length > 0) {
      finding.forEach((result) => {
        console.log(`Finding: ${result.finding}, Confidence: ${result.confidence}`);
      });
    }
  });
}

>>> from nightfall import Confidence, DetectionRule, Detector, Nightfall

>>> # By default, the client reads the API key from the environment variable NIGHTFALL_API_KEY
>>> nightfall = Nightfall()

>>> # A rule contains a set of detectors to scan with
>>> cc = Detector(min_confidence=Confidence.LIKELY, nightfall_detector="CREDIT_CARD_NUMBER")
>>> ssn = Detector(min_confidence=Confidence.POSSIBLE, nightfall_detector="US_SOCIAL_SECURITY_NUMBER")
>>> detection_rule = DetectionRule([cc, ssn])
>>> payload = ["hello world", "my SSN is 678-99-8212", "4242-4242-4242-4242"]
>>> findings, _ = nightfall.scan_text( payload, detection_rules=[detection_rule])

The Policy (policy) you define indicates what to scan for in your payload with a logical grouped (ANY or ALL) set of Detection Rules (detectionRules).

Detection Rules can be defined two ways:

inline as code, as shown above
in the Nightall app, which you will then reference by UUID.

Learn more about setting up Nightfall in the Nightfall app to create your own Detectors, Detection Rules, and Policies. See Using Pre-Configured Detection Rules for an example as to how to execute queries using an existing Detection Rules UUID.

In the example above, two of Nightfall's native Detectors are being used: US_SOCIAL_SECURITY_NUMBER and CREDIT_CARD_NUMBER.

You can find a full list of native Detectors in the Detector Glossary.

If you don't want to create your Detectors, Detection Rules, and Policies in the Nightfall app, but would prefer to do it in code, it is possible to define Detectors inline with your own regular expressions or word list as well as extend our native Detectors with exclusion and context rules.

When defining a Detection Rule, you configure the minimum confidence level (minConfidence) and minimum number of times the match must be found (minNumFindings) for the rule to be triggered.

Another feature Nightfall offers is the ability to redact sensitive findings. Detectors may be configured (via redactionConfig) to replace the text that triggered them with a variety of customizable masks, including an encrypted version of the text.

In the payload body, you can see that we are submitting a list of three different strings to scan (payload). The first will trigger the U.S. Social Security Detector. The last will trigger the credit card Detector. The middle example will trigger neither.

Example Nightfall API Scan Response

The Nightfall API returns a response with an array (findings) with a length that corresponds to the length of the payload array. In this example, only the first and last items in the request payload triggered the Detectors, so the second element of the array is empty.

In the first element of the array, you can see details about which Detection Rule was triggered and the data that was found (finding). The response also provides a confidence level (confidence), as well as the location within the original text where the data was found either in terms of bytes (byteRange) or characters (codepointRange).

{
  "findings": [
    [
      {
        "finding": "458-02-6124",
        "detector": {
          "name": "US Social Security Number",
          "uuid": "e30d9a87-f6c7-46b9-a8f4-16547901e069"
        },
        "confidence": "VERY_LIKELY",
        "location": {
          "byteRange": {
            "start": 39,
            "end": 50
          },
          "codepointRange": {
            "start": 39,
            "end": 50
          },
          "rowRange": null,
          "columnRange": null,
          "commitHash": ""
        },
        "matchedDetectionRuleUUIDs": [],
        "matchedDetectionRules": [
          "My Match Rule"
        ]
      }
    ],
    [],
    [
      {
        "finding": "5310-2768-6832-9293",
        "redactedFinding": "####-####-####-####",
        "detector": {
          "name": "Credit Card Number",
          "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
        },
        "confidence": "VERY_LIKELY",
        "location": {
          "byteRange": {
            "start": 25,
            "end": 44
          },
          "codepointRange": {
            "start": 25,
            "end": 44
          },
          "rowRange": null,
          "columnRange": null,
          "commitHash": ""
        },
        "redactedLocation": {
          "byteRange": {
            "start": 25,
            "end": 44
          },
          "codepointRange": {
            "start": 25,
            "end": 44
          },
          "rowRange": null,
          "columnRange": null,
          "commitHash": ""
        },
        "matchedDetectionRuleUUIDs": [],
        "matchedDetectionRules": [
          "My Match Rule"
        ]
      }
    ]
  ],
  "redactedPayload": [
    "",
    "",
    "My credit card number is ####-####-####-####"
  ]
}

Congratulations! You have successfully completed the Nightfall Quickstart.

You can modify the Detectors or payload in the example request to get more practice with the Nightfall API.