Using Pre-Configured Detection Rules

🚧
After 18th August 2024, this page would permanently be moved to a new location. You can access this page from a new URL which is present here. If you have saved or bookmarked the current URL, kindly update it with the new URL, since there will be no 301 redirect from the current URL to the new URL.

In this example, we'll walk through making a request to the scan endpoint.

The endpoint inspects the data you provide via the request body and reports any detected occurrences of the sensitive data types you are searching for.

Please refer to the API reference of the scan endpoint for more detailed information on the request and response schemas.

In this sample request, we provide two main fields:

a policy and its detection rules that we want to use when scanning the text payload
a list of text strings to scan

In the example below we will use a Detection Rule that has been configured in the user interface by supplying its UUID.

The aggregate length of all strings in payload list must not exceed 500 KB, and the number of items in the payload may not exceed 50,000.

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": {
          "detectionRuleUUIDs": [
               "950833c9-8608-4c66-8a3a-0734eac11157"
          ]
     },
     "payload": [
          "4916-6734-7572-5015 is my credit card number",
          "This string does not have any sensitive data",
          "my api key is yr+ZWwIZp6ifFgaHV8410b2BxbRt5QiAj1EZx1qj and my 💳 credit card number 💰 is 30204861594838"
     ]
}
'

Alternatively you may define your policy in code by using a built in Nightfall detector from the Detector Glossary as follows:

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": [
                         {
                              "nightfallDetector": "CREDIT_CARD_NUMBER",
                              "detectorType": "NIGHTFALL_DETECTOR",
                              "minConfidence": "POSSIBLE",
                              "minNumFindings": 1
                         }
                    ],
                    "logicalOp": "ALL"
               }
          ]
     },
     "payload": [
          "4916-6734-7572-5015 is my credit card number",
          "This string does not have any sensitive data",
          "my api key is yr+ZWwIZp6ifFgaHV8410b2BxbRt5QiAj1EZx1qj and my 💳 credit card number 💰 is 30204861594838"
     ]
}
'

See Creating an Inline Detection Rule for more information about how policies and detection rules may be defined through code.

Executing the curl request will yield a response as follows.

{
    "findings": [
        [
            {
                "finding": "4916-6734-7572-5015",
                "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
                    }
                },
                "matchedDetectionRuleUUIDs": [
                    "950833c9-8608-4c66-8a3a-0734eac11157"
                ],
                "matchedDetectionRules": []
            }
        ],
        [],
        [
            {
                "finding": "30204861594838",
                "detector": {
                    "name": "Phone number",
                    "uuid": "d08edfc4-b5e2-420a-a5fe-3693fb6276c4"
                },
                "confidence": "LIKELY",
                "location": {
                    "byteRange": {
                        "start": 94,
                        "end": 108
                    },
                    "codepointRange": {
                        "start": 88,
                        "end": 102
                    }
                },
                "matchedDetectionRuleUUIDs": [
                    "950833c9-8608-4c66-8a3a-0734eac11157"
                ],
                "matchedDetectionRules": []
            },
            {
                "finding": "30204861594838",
                "detector": {
                    "name": "Credit card number",
                    "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
                },
                "confidence": "LIKELY",
                "location": {
                    "byteRange": {
                        "start": 94,
                        "end": 108
                    },
                    "codepointRange": {
                        "start": 88,
                        "end": 102
                    }
                },
                "matchedDetectionRuleUUIDs": [
                    "950833c9-8608-4c66-8a3a-0734eac11157"
                ],
                "matchedDetectionRules": []
            }
        ]
    ]
}
 
      "location": {
        "byteRange": {
          "start": 94,
          "end": 108
        },
        "codepointRange": {
          "start": 88,
          "end": 102
        }
      },
      "matchedDetectionRuleUUIDs": [
        "950833c9-8608-4c66-8a3a-0734eac11157"
      ],
      "matchedDetectionRules": []
    },
    {
      "finding": "30204861594838",
      "detector": {
        "name": "Credit card number",
        "uuid": "74c1815e-c0c3-4df5-8b1e-6cf98864a454"
      },
      "confidence": "LIKELY",
      "location": {
        "byteRange": {
          "start": 94,
          "end": 108
        },
        "codepointRange": {
          "start": 88,
          "end": 102
        }
      },
      "matchedDetectionRuleUUIDs": [
        "950833c9-8608-4c66-8a3a-0734eac11157"
      ],
      "matchedDetectionRules": []
    }
  ]
]

The API call returns a list, where the item at each index is a sublist of matches for the provided detector types.

The indices of the response list correspond directly to the indices of the list provided in the request payload.

In this example, the first item in the response list contains a finding because one credit card number was detected in the first string we provided. The second item in the response list is an empty list because there is no sensitive data in the second input string we provided. The third item in the returned list contains multiple findings as a result of multiple Detectors within the Detection Rule being triggered.

You can read further about the fields in the response object in the API Reference.