Package: nightfall
Nightfall Python SDKEmbed Nightfall scanning and detection functionality into Python applicationsFeaturesThis SDK provides Python functions for interacting with the Nightfall API. It allows you to add functionality to your
applications to scan plain text and files in order to detect different categories of information. You can leverage any
of the detectors in Nightfall's pre-built library, or you may programmatically define your own custom detectors.Additionally, this library provides convenience features such as encapsulating the steps to chunk and upload files.To obtain an API Key, login to theNightfall dashboardand click the section
titled "Manage API Keys".See ourdeveloper documentationfor more details about
integrating with the Nightfall API.DependenciesThe Nightfall Python SDK requires Python 3.7 or later.For a full list of external dependencies please consultsetup.py.Installationpip install nightfallUsageScanning Plain TextNightfall provides pre-built detector types, covering data types ranging from PII to PHI to credentials. The following
snippet shows an example of how to scan using pre-built detectors.Sample Code>>>fromnightfallimportConfidence,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])>>>findings,_=nightfall.scan_text(["hello world","my SSN is 678-99-8212","4242-4242-4242-4242"],detection_rules=[detection_rule])>>>print(findings)[[],[Finding(finding='678-99-8212',redacted_finding=...)]]Scanning FilesScanning common file types like PDF's or office documents typically requires cumbersome text
extraction methods like OCR.Rather than implementing this functionality yourself, the Nightfall API allows you to upload the
original files, and then we'll handle the heavy lifting.The file upload process is implemented as a series of requests to upload the file in chunks. The library
provides a single method that wraps the steps required to upload your file. Please refer to theAPI Referencefor more details.The file is uploaded synchronously, but as files can be arbitrarily large, the scan itself is conducted asynchronously.
The results from the scan are delivered by webhook; for more information about setting up a webhook server, refer tothe docs.Sample Code>>>fromnightfallimportConfidence,DetectionRule,Detector,Nightfall>>>importos>>># 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])>>># Upload the file and start the scan.>>># These are conducted asynchronously, so provide a webhook route to an HTTPS server to send results to.>>>id,message=nightfall.scan_file("./README.md",os.environ["WEBHOOK_ENDPOINT"],detection_rules=[detection_rule])>>>print("started scan",id,message)startedscan...scaninitiatedContributingContributions are welcome! Open a pull request to fix a bug, or open an issue to discuss a new feature
or change. Please adhere to the linting criteria expected by flake8, and be sure to add unit tests for
any new functionality you add.Refer toCONTRIBUTING.mdfor the full details.LicenseThis code is licensed under the terms of the MIT License. Seeherefor more information.Please create an issue with a description of your problem, or open a pull request with the fix.DevelopmentInstalling Development DependenciesIf you want to hack on this project, you should set up your local development
environment with the following commands:Fork and clone this repo and open a terminal with the root of this repository in your working directory.Create and activate a virtualenvpython3 -m venv venv && source venv/bin/activateInstall development dependencies withpip install -r dev-requirements.txtInstall an editable version of this packagepip install -e .Run Unit TestsUnit and Integration tests can be found in thetests/directory. You can run them withpytest. Be sure to haveNIGHTFALL_API_KEYset as an environment variable before running the tests.View Code CoverageYou can view the code coverage report by runningcoverage htmlandpython3 -m http.server --directory htmlcovafter running the unit tests.Creating a ReleaseReleases are automatically published to PyPI using GitHub Actions. Creating a release in GitHub will trigger a new build that will publish the latest version of this library toPyPI.The steps to do this are:Add what changed to the CHANGELOG fileUpdate the version insetup.pyCommit changes and push to the main branch.Create a new release in the GitHub UI.Observe the release action succeed and see the latest version of this library on PyPI.