Python

This guide describes how to use Nightfall with the Python 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 Python SDK.

To request the Nightfall API you will need:

• A Nightfall API key

• An existing Nightfall Detection Rule

• Data to scan. Note that the API interprets data as plaintext, so you may pass it in any structured or unstructured format.

You can read more about obtaining a Nightfall API key or about our available data detectors in the linked reference guides.

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

We recommend you first set up a virtual environment. You can learn more about that here.

You can download the Nightfall SDK from PyPi like this:

We will be using the built-in os library to help run this sample API script. This will be used to help extract the API Key from the OS as an environment variable.

import os

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

Next, we extract our API Key, and abstract a nightfall class from the SDK, for it. In this example, we have our API key set via an environment variable called NIGHTFALL_API_KEY. Your API key should never be hard-coded directly into your script.

nightfall = Nightfall(os.environ['NIGHTFALL_API_KEY'])

Next we define the Detection Rule with which we wish to scan our data. The Detection Rule can be pre-made in the Nightfall web app and referenced by UUID.

detection_rule_uuid = os.environ.get('DETECTION_RULE_UUID')

In this example, we will use some example data in the payload List.

🚧Payload Limit

Payloads must be under 500 KB when using the Scan API. If your file is larger than the limit, consider using the file api, which is also available via the Python SDK.

We will ignore the second parameter as we do not have redaction configured for this request.

With the Nightfall API, you can redact and mask your findings. You can add a Redaction Config, as part of your Detection Rule. For more information on how to use redaction, and its specific options, please refer to the guide here.

Using Detection Rule UUIDs

payload = [
    "The customer social security number is 458-02-6124",
    "No PII in this string",
    "My credit card number is 4916-6734-7572-5015"
]

result, _ = nightfall.scan_text(
        payload,
        detection_rule_uuids=[detection_rule_uuid]
    )

Using Detection Rules Inline

payload = [
    "The customer social security number is 458-02-6124",
    "No PII in this string",
    "My credit card number is 4916-6734-7572-5015"
]

result, _ = nightfall.scan_text(
    payload,
    detection_rules=[
        DetectionRule(
            name="Sample_Detection_Rule",
            logical_op=LogicalOp.ANY,
            detectors=[
                Detector(
                    min_confidence=Confidence.LIKELY,
                    min_num_findings=1,
                    display_name="Credit Card",
                    nightfall_detector="CREDIT_CARD_NUMBER",
                ),
                Detector(
                    min_confidence=Confidence.LIKELY,
                    min_num_findings=1,
                    display_name="Social",
                    nightfall_detector="US_SOCIAL_SECURITY_NUMBER",
                )
            ]
        )
    ]
)

Reviewing Results

Now we are ready to review the results from the Nightfall SDK to check if there is any sensitive data in our file. Since the results will be in a dataclass, we can use the built-in __repr__ functions to format the results in a user-friendly and readable manner.

All data and sample findings shown below are validated, non-sensitive, examples of sample data.

If there are no sensitive findings in our payload, the response will be as shown in the 'empty response' pane below:

Positive Response - Using Detection Rule UUID

[
    [Finding(finding='458-02-6124', redacted_finding=None, before_context=None, after_context=None, detector_name='US social security number (SSN)', detector_uuid='e30d9a87-f6c7-46b9-a8f4-16547901e069', confidence=<Confidence.VERY_LIKELY: 'VERY_LIKELY'>, byte_range=Range(start=39, end=50), codepoint_range=Range(start=39, end=50), matched_detection_rule_uuids=['c67e3dd7-560e-438f-8c72-6ec54979396f'], matched_detection_rules=[])],
    [],
    [Finding(finding='4916-6734-7572-5015', redacted_finding=None, before_context=None, after_context=None, detector_name='Credit card number', detector_uuid='74c1815e-c0c3-4df5-8b1e-6cf98864a454', confidence=<Confidence.VERY_LIKELY: 'VERY_LIKELY'>, byte_range=Range(start=25, end=44), codepoint_range=Range(start=25, end=44), matched_detection_rule_uuids=['c67e3dd7-560e-438f-8c72-6ec54979396f'], matched_detection_rules=[])]
]

Positive Response - Using Detection Rules Inline

[
    [Finding(finding='458-02-6124', redacted_finding=None, before_context=None, after_context=None, detector_name='Social', detector_uuid='e30d9a87-f6c7-46b9-a8f4-16547901e069', confidence=<Confidence.VERY_LIKELY: 'VERY_LIKELY'>, byte_range=Range(start=39, end=50), codepoint_range=Range(start=39, end=50), matched_detection_rule_uuids=[], matched_detection_rules=['Sample_Detection_Rule'])],
    [],
    [Finding(finding='4916-6734-7572-5015', redacted_finding=None, before_context=None, after_context=None, detector_name='Credit Card', detector_uuid='74c1815e-c0c3-4df5-8b1e-6cf98864a454', confidence=<Confidence.VERY_LIKELY: 'VERY_LIKELY'>, byte_range=Range(start=25, end=44), codepoint_range=Range(start=25, end=44), matched_detection_rule_uuids=[], matched_detection_rules=['Sample_Detection_Rule'])],
]

Empty Response

[[], [], []]

And that's it 🎉

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

---