1 of 78

Developer APIs

Welcome to Developer APIs Documentation

Welcome to the amazing world of the Nightfall Developer APIs (formerly known as Firewall for AI). Here you can find all the information about Nightfall's APIs, and SDKs, and also usage examples of these APIs and SDKs.

Introduction to Developer APIs

Overview

Welcome to Nightfall's Firewall for AI Developers Scan and Workflow APIs documentation. This documentation helps developers leverage Nightfall AI's industry-leading detection engine to identify and protect sensitive customer and corporate data anywhere. It prevents unauthorized access and data breaches and allows you to focus on innovation.

Scan APIs

Scan prompts, text, documents, spreadsheets, logs, zips, JSON, images, etc., for PII, PHI, PCI, banking information, API keys, passwords, and network information with the highest accuracy and lightning-fast response times. Redact sensitive findings with customizable formatting.

Authentication and Security

The Nightfall API uses API keys to authenticate requests. You can create and view your API keys in the Nightfall app on the Manage API Keys page.

Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, or anywhere else that would compromise their secrecy. If you believe one of your API Keys has been compromised, you should delete it through the Dashboard.

All API requests must be made over HTTPS.

Calls made over plain HTTP will fail.

API requests without authentication will fail.

Key Concepts

Entities and Terms to Know

This section describes the terms you will need to know when using the API.

Detectors

Detectors provide the logic to find potentially sensitive pieces of data.

When this logic detects such data, the Detector is considered "triggered."

Nightfall's has numerous pre-built Detectors that are trained via machine learning. Detectors may also be defined with regular expressions or dictionaries. Their accuracy may be further refined with exclusion rules and context rules. Whether a Detector is triggered may be controlled by a minimum confidence threshold per Detector and minimum number of findings per Detector as set on a Detection Rule.

The built-in set of Detectors cover a number of different categories of data, including:

Standard PII (e.g. social security number, driver's license number, ID card image)
PCI (Credit Card Number, credit card image)
Healthcare (e.g. PHI, US Medicare Beneficiary Number)

The full set is enumerated in the .

Custom Detectors

Nightfall also supports and word lists for any custom detectors that you may want to implement.

Over time, we've aggregated the following , which you're welcome to select from to save you some time. Please note that a regular expression is an established yet limited method that searches for pre-defined patterns, so your mileage may vary.

You can test regular expressions .

You can input custom detectors in two ways: directly in the Nightfall by navigating to Detectors → New Detector → Regular expression, or

Exclusion Rules

An exclusion rule is a regular expression or word list that will be used once a Detector is triggered by its primary expression or word list to eliminate false positives.

For instance, you may have a Detector designed to detect phone numbers. However, you may have a particular set of phone numbers that you use for testing purposes that are known not to be valid (e.g. they start with the prefix 555) and this should be ignored. Adding an exclusion rule would allow you to prevent those matches from being returned by the API.

See:

Context Rules

Context Rules are additional matching expressions for a Detector that may be used to adjust the confidence score of a match.

You may provide a regular expression and the number of leading or trailing characters within which a match of that expression must occur in order to adjust the confidence level to a particular level.

For instance, if you found a sequence that appeared to be a social security number based on its length or formatting, you might boost the confidence score if it was preceded by the text like “SSN” or “Social Security Number.”

Returning Surrounding Context

You may request that a sequence of bytes of a given length be provided from before and after the text that triggers a Detection Rule.

This information can help you better understand whether or not something is an actual violation by observing the circumstances within which the detected text was found.

You are limited to a maximum of 40 bytes of this context text preceding and trailing the match for a total of 80 bytes overall.

See:

Detection Rules

Detection Rules are aggregations of Detectors that are assigned a minimum confidence level. The identifiers of Detection Rules are used as a parameter to the API.

You may create Detection Rules as described in the section and use their identifier as part of API calls to scan content.

Alternatively you may specify Detection Rules in each API call, as described in the scan method documentation below.

A Detection Rule is composed of a list of Detectors with which you wish to scan each request payload, where any or all Detectors may be satisfied in order to trigger the rule. You can add up to 50 total Detectors with a limit of 30 regular expression type custom detectors.

Additionally, each Detector in the Detection Rule is assigned a “minimum confidence” level (see and a minimum number of findings to determine if the Detection Rule should be considered triggered.

Confidence Levels

Detection results will be returned with one of the following confidence values.

In practice, the API will only return detections assigned a POSSIBLE or higher confidence level.

VERY_LIKELY (recommended)
LIKELY
POSSIBLE
UNLIKELY

Learn more about what different confidence levels mean and how to choose the right minimum confidence level for your detection rule .

Policies

Policies allow you to create templates for the most common workflows by unifying a set of Detection Rules with the actions to be taken when those rules are triggered, including:

automated actions such as redaction of findings
alerting through webhooks

Once defined, a Policy may be used in requests to the Nightfall API, such as calls to scan file uploads, though automated redactions are not available for uploaded files at this time.

Setting Up Nightfall

Before you use the scan endpoint, there are a number of actions to do within the Nightfall dashboard to get your environment set up properly.

See Creating an API Key to see how to create the necessary Authentication token for making API calls.
See Creating a Detector for how to define your own custom logic for detecting sensitive data
See for how to aggregate Detectors for use in the scan endpoint
See for how to set up common workflows that combine your Detection Rules with remediation actions such as alerting.

Creating API Key

The API expects an API Key to be passed via the Authorization: Bearer <key> HTTP header.

To create and manage API keys:

Log in to Nightfall.
Click Overview under the DEVELOPER APIS section.
Click Create key.

The Generate API Key window is displayed.

Enter a name for the API key and click Create.

The API key is generated and displayed. Click the copy button to copy the API key and store it in a. secure location. Once you click the Got it button, you cannot retrieve the API key again.

🚧Be Sure to Record the API Key's Value
For security reasons, after closing the window, you will not be able to recover the key's value.

Once you close the window, the Your API Keys section will display your newly generated key, with the majority of the Key redacted.

You can click the Create Key button to create new keys (assuming your license allows you to generate additional keys). You can click the Delete icon against an API key to delete the key.

Creating Policies

This document applies only to the Nightfall Developer APIs customers. If you are a Nightfall SaaS application customer, refer to .

Policies allow customers to create templates for their most common workflows by unifying a set of Detection Rules with the actions to be taken when those rules are triggered, including:

automated actions such as redaction of findings

Scanning Text

The scan endpoint allows you to apply Policies and Detection Rules to a list of text strings provided as a payload.

You may use Pre-Configured Detection Rules or Create Inline Detection Rules

Text scanning supports the use of Exclusion Rules, Context Rules, and Redaction as well as other Scanning Features.

For scanning files, see Scanning Files.

Note that you must generate an API key to send requests to the Nightfall API.

Scanning Files

Nightfall’s file scan API allows a user to upload a file in chunks, then to scan it with Detection Rules once the upload is complete.

The scan will then be processed asynchronously before sending the results to the webhook URL that is provided along with your Detection Rules.

The following sequence diagram illustrates the full process for scanning a binary file with Nightfall.

For a detailed walkthrough of the API calls necessary to upload and scan a file and full script that shows the entire process, see Uploading and Scanning Files .

Prerequisites

In order to utilize the File Scanning API you need the following:

An active API Key authorized for file scanning passed via the header Authorization: Bearer <key> — see
A Nightfall Detection Policy associated with a webhook URL
A web server configured to listen for file scanning results (detailed information to follow)

File scanning also support Nightfall's functionality for and as part of your scan requests.

Webhooks and Asynchronous Notifications

The Nightfall API supports the ability to send asynchronous notifications when findings are detected as part of a scan request.

The supported destinations for these notifications include external platforms, such as Slack, email, or url to a SIEM log collector as well as to a webhook server.

Nightfall issues notifications under the following scenarios:

to notify a client about the results of a file scan request. File scans themselves are always performed asynchronously because of complexity relating to text extraction and data volume.
to notify a client about results from a text scan request. Although results are already delivered synchronously in the response object, clients may configure the request to forward results to other platforms such a webhook, SIEM endpoint, or email through a

To create a webhook you will need to and then set up a

For more information on how webhooks and asynchronous notifications are used please see our guides on:

Accessing Your Webhook Signing Key

In order to accept requests from Nightfall, a Webhook server must use a signing key to verify requests.

To access or generate your Webhook signing key, start by logging in to the Nightfall .

Select the Developer Platform > Manage API Keys using the navigation bar on the left side of the page. You will see the Webhook signing section:

Unlike the API Key, it is possible to reveal the signature via the "eye" icon furtherest to the left of the three icons displayed.

You may copy the current value to your clipboard with the "copy" icon in the center of the three icons displayed.

You may also regenerate the key with the circular arrow icon furthest to the right.

Scanning Features

Nightfall offers many useful features beyond its detectors, including:

The ability to use and to narrow the scope of matches.

The ability to create in a way that is highly configurable so that sensitive data is appropriately obfuscated.

The ability to create that determine how leaks of sensitive information should be mitigated (i.e. through alerts sent to email or Slack).

Scanning Images for patterns using Custom Regex Detectors

Using regex to identify long patterns in images can be challenging because OCR systems. In such cases, even Nightfall may not achieve 100% character-by-character accuracy. To improve results, you must introduce higher levels of flexibility into your regex patterns to accommodate common OCR inconsistencies. Here are some typical OCR challenges to keep in mind:

Spell-check noise: Spell-checking tools can add artifacts like red underlines, which may interfere with text recognition.
Character ambiguity:
- The digit 0 may be misinterpreted as the letter O (or vice versa), depending on the font.
- The character l (lowercase L) may be read as the digit 1.
- The letter B may appear as the digit 8.
Underscore handling: An underscore (_) is sometimes interpreted as a space, particularly when spell-check artifacts are present.
Line wrapping: OCR may introduce unexpected newlines when text wraps across multiple lines.
Periods and punctuation: Spell-check artifacts or font issues may result in extraneous periods (.) or other punctuation being added to the output. En dash (–) and hyphens (-) may be interchanged.

For reference, OCR tools like Tesseract typically achieve 85-98% character accuracy for similar input, and our system operates within a similar range. Given this, tuning your regex to be more forgiving (e.g., allowing for optional characters or slight variations) can significantly improve detection rates.

Example Regex (original and loosened)

original: ATATT3xFfGF0[A-Za-z0-9=_\-]*[=A-Za-z0-9]{9}

loosened: ATATT[A-Za-z0-9_\-– @.\n=]*[A-Za-z0-9_\- @.\n]{7,11}

shortened the literal match prefix
excluded the the literal zero (0) from the prefix
added period (.) and newline () chars

PHI Detection Rules

Protected health information (PHI), also referred to as personal health information, describes a patient's medical history — including ailments, various treatments, and outcomes. PHI may include:

demographic information
test and laboratory results
mental health conditions
insurance information

The Health Insurance Portability and Accountability Act (HIPAA) of 1996 is the primary law that oversees the use of, access to, and disclosure of PHI in the United States. HIPAA lists 18 different personal information identifiers (PII) that, when paired with health information, become PHI. In order to more accurately detect potential PHI, Nightfall has introduced specific new detectors that allow for specialized combinations.

These HIPAA PII and PHI-specific detectors intelligently aggregate Nightfall's built-in detector to ensure compliance with governing law. For example, finding a patient's name in a document or message is not considered HIPAA PII as it does not uniquely identify an individual, many people can share the same name. However, the information would be considered HIPAA PII if the patient's name and address were in the same message.

Specific PHI and HIPAA PII can be detected with greater confidence, especially as they relate to specific medical codes or terms in association with specific logical combinations of other PII. For instance when the patient's name and date of birth or a person's name and street address or any of a set of particular PII (phone number email, SSN, etc) it would be considered HIPAA PII.

If the combined detectors all match with a confidence of "Very Likely" it would match our "HIPAA PII Very Likely" Detection Rule. Otherwise if these detectors match with a confidence of "Likely" it would match our "HIPAA PII Likely" Detection Rule.

Alternatively when any of the above PII options are found in conjunction with a specific set of medical related codes or terms (IDC Codes, FDA Drug Names or Codes, Procedures), that finding could be flagged as PHI.

When all the detectors within these PHI Detection Rules make findings that have a confidence of "Very Likely," that would match our "PHI Very Likely" Detection Rule, while if some are all are met with a confidence of "Likely" that would match our "PHI Likely" Detection Rule.

Our PHI Detectors may be used just like other Detectors with or .

Test Datasets

The following sample datasets can be used to test Nightfall's advanced AI-based detection capabilities.

This data has been fully de-identified and can be used to test any data loss prevention (DLP) platform.

Errors

While using Nightfall's Scan API, you may encounter some of the common errors outlined below. Try following the provided troubleshooting steps.

If problems persist, please contact Nightfall Support for further assistance.

HTTP Error Codes

The following error codes are returned as part of a standard HTTP response.

HTTP Error Code

Description

Troubleshooting

Nightfall Playground

The Nightfall Developer Playground () is a sample app that you may use to test out API functionality before writing any code.

Our playground environment allows you to:

Test Detectors and Detection Rules. Here are some .
Generate sample data for DLP testing.

Nightfall APIs

DLP APIs - Firewall for AI Platform

Firewall for AI DLP APIs enables developers to write custom code to sanitize data anywhere–RAG data sets, analytics data stores, data pipelines, and unsupported SaaS applications.

Rate Limits for Firewall APIs

To prevent misuse and ensure the stability of our platform, we enforce a rate limit on an API Key and endpoint basis, similar to the way many other APIs enforce rate limits.

When operating under our Free plan, accounts and their corresponding API Keys have a rate limit of 5 requests per second on average, with support for bursts of 15 requests per second. If you upgrade to a paid plan – the Enterprise plan – this rate increases to a limit of 10 requests per second on average and bursts of 50 requests per second.

Plan

Requests Per Second (Avg)

Burst

DLP APIs - Native SaaS Apps

The native SaaS app APIs can be utilized by customers using Nightfall’s SaaS apps, supported natively, to fetch violations, search violations by app meta-data attributes, and fetch findings within violations. These DLP APIs do not provide access to violations for apps scanned via the developer platform. These APIs require you to create an API key as outlined in the . However, to use these APIs, you need not create any detectors, detection rules, and policies in the developer platform.

If you are using Nightfall SaaS apps, you can use APIs to fetch violations, search through the violations, and fetch specific findings within the Violations. To scan data in any custom apps or cloud infrastructure services like AWS S3, you must use the APIs in the section.

Rate Limits for Native SaaS app APIs

To prevent misuse and ensure the stability of our platform, we enforce a rate limit on an API Key and endpoint basis, similar to the way many other APIs enforce rate limits.

Plan

Requests Per Second (Avg)

Burst

Policy Update APIs

Exfiltration Prevention APIs

You can use the exfiltration APIs to search exfiltration events, fetch exfiltration events and also event details. Additionally, you can also view details of the user (actor) whose actions triggered an event, and details of the asset that triggered an event.

Posture Management APIs

You can use the posture management APIs to search posture events, fetch posture events and also event details. Additionally, you can also view details of the user (actor) whose actions triggered an event, and details of the asset that triggered an event.

SaaS App and Device Management APIs

APIs to monitor and manager integrations

Nightfall Model Context Protocol (MCP) Server

The Nightfall MCP (Model Context Protocol) server enables AI assistants like Claude, ChatGPT, and Cursor to interact directly with your Nightfall security data. Instead of navigating dashboards or running API queries manually, you can use natural language to investigate violations, search for exfiltration events, review security posture, and take remediation actions.

Key Benefits

Natural Language Interface: Ask questions in plain English instead of learning complex query syntax
Faster Investigations

Common Use Cases

Here are real-world scenarios where the Nightfall MCP server delivers immediate value:

Security Investigations

Example: "Show me all active high-risk violations from GitHub in the last week"

The AI automatically uses search_violations with appropriate filters and returns results in seconds. You can then ask follow-up questions like "Which repository has the most violations?" or "Show me the sensitive data found in violation abc-123" without manually constructing queries.

Insider Threat Response

Example: "What has user been doing in the last 30 days?"

Get a complete timeline of user activity including file downloads, permission changes, and policy violations. The AI summarizes patterns and flags anomalies automatically.

Bulk Remediation

Example: "Resolve all pending Slack violations from the #general channel"

Instead of manually processing violations one by one, describe the action in natural language. The AI finds matching violations and executes the appropriate remediation action.

Compliance Reporting

Example: "Generate a summary of all HIPAA violations this quarter grouped by department"

The AI retrieves relevant data, performs grouping and aggregation, and creates a formatted report—all from a single request.

Data Exfiltration Detection

Example: "Are there any exfiltration events involving bulk downloads from Google Drive?"

Quickly identify potential data theft attempts by searching for specific event patterns across your cloud storage integrations.

Permission Audits

Example: "List all posture events with permission changes this month"

Monitor access control changes across your environment to identify security configuration drift or policy violations.

Query Examples

These examples demonstrate the flexibility of natural language queries. You don't need to memorize syntax - just describe what you need.

Basic Searches

"Show me today's violations"

Troubleshooting

Connection Issues

Problem: "Unauthorized" or 401 errors

Solutions:

Verify your API key is correctly pasted in the configuration file (no extra spaces)
Check that the API key hasn't expired or been revoked in the Nightfall dashboard
Ensure you're using "Bearer YOUR_KEY" format, not just "YOUR_KEY"
Restart your AI client after updating the configuration

Problem: MCP server not appearing in client

Solutions:

Verify the configuration file is in the correct location for your operating system
Check JSON syntax is valid (use a JSON validator if needed)
For Claude Desktop: ensure npx is installed (requires Node.js)

Query Issues

Problem: No results returned

Solutions:

Broaden your time range (data may be older than expected)
Check filter criteria aren't too restrictive
Verify the integration or resource name is spelled correctly

Problem: Rate limit errors (429)

Solutions:

Wait for the duration specified in the Retry-After header
Reduce query frequency or batch similar requests
Contact Nightfall support if hitting limits during normal usage

Performance

Problem: Slow query responses

Solutions:

Use more specific filters to reduce result set size
Limit date ranges to recent periods when possible
Request paginated results for large datasets

Support & Resources

Getting Help

If you encounter issues not covered in this guide:

Email Support: [email protected]

Providing Feedback

We continuously improve the MCP server based on customer feedback. Please share:

Feature requests for new query capabilities
Use cases we should highlight in documentation
Integration challenges or configuration pain points

Additional Learning Resources

Model Context Protocol Specification:
Nightfall API Documentation:
Webinars:

Nightfall Software Development Kit (SDK)

Overview

Leverage our software development kits (SDKs) to enable easier, faster, and more stable engagement with the Nightfall APIs. Nightfall has a growing library of language specific SDKs including for:

Language Specific Guides

Overview

Nightfall provides you the flexibility to easily integrate into applications using programming languages. The supported languages are as follows.

Tutorials

Nightfall Use Cases

Overview

This section consists of use case tutorials for various scenarios of Firewall for AI. The tutorials explained in this section are as follows.

FAQs

What Can I do with the Firewall for AI How quickly can I get started with Firewall for AI?What types of data can I scan with API?What types of detectors are supported out of the box?Can I customize or bring my own detectors?What is the pricing model?How do I know my data is secure?How do I get in touch with you?Can I test out the detection and my own detection rules before writing any code?How does Nightfall support custom data types?How does Nightfall's Firewall for AI differs from other solutions?

What Can I do with the Firewall for AI

Firewall for AI is a powerful API that acts as a middleware layer or client wrapper to protect your AI models from consuming sensitive data. By integrating Firewall for AI into your application via API calls, you can proactively prevent data leaks and maintain compliance without disrupting your existing workflows or model updates.

How quickly can I get started with Firewall for AI?

You can start scanning for sensitive data in just a few minutes. Our developer-friendly API and comprehensive documentation make it easy to integrate Firewall for AI into your application. Follow our Quickstart guide at this link for step-by-step instructions on setting up the API, configuring detectors, and making your first API call.

What types of data can I scan with API?

Firewall for AI provides a flexible and extensible API that allows you to scan a wide variety of data types, including plain text, structured and unstructured files, and even images. Our API can handle data in various formats such as JSON, XML, CSV, and more. Visit our detector glossary at docs.nightfall.ai/docs/detector-glossary to explore the comprehensive list of supported data types and file formats

What types of detectors are supported out of the box?

Firewall for AI offers a rich set of pre-built detectors that can identify many different types of sensitive data, including personally identifiable information (PII), payment card industry data (PCI), protected health information (PHI), secrets, and credentials. These detectors are powered by advanced machine learning models and can be easily integrated into your application with just a few lines of code. Refer to our detector glossary at docs.nightfall.ai/docs/detector-glossary for a complete list of available detectors.

Can I customize or bring my own detectors?

Absolutely! In addition to the pre-built detectors, Firewall for AI allows you to create custom detectors tailored to your specific requirements. You can either fine-tune one of our pre-configured detection rules or build your own detector from scratch using our intuitive API. Nightfall supports many traditional detector types such as regular expressions, exact data matching, and word list/dictionaries. Check out our dedicated guide on creating custom detectors for more information.

What is the pricing model?

We offer a free tier that allows you to sign up and start using Firewall for AI with zero upfront costs or commitments. This tier provides a generous data scanning capacity and access to all the core features.

We offer enterprise pricing plans for advanced requirements such as higher data volumes, custom rate limits, and dedicated support. More information on pricing...

Contact our team at [email protected] or via the contact form on our website to discuss your specific needs and get a tailored pricing quote.

How do I get in touch with you?

Don't hesitate to get in touch with us directly via email at [email protected] or through the contact form on our website.

We host Nightfall Developer Office Hours on Wednesdays at 12 pm PT to help answer questions, talk through any ideas, and chat about data security. We would love to see you there!

Can I test out the detection and my own detection rules before writing any code?

Yes, you can test out the detection engine, including 70+ pre-built detectors without writing any code or having to sign up in our .

How does Nightfall support custom data types?

In two ways:

Nightfall’s out of the box detectors can be modified with context rules and exclusion rules.
Nightfall also supports inputting custom regular expressions or word lists (i.e. dictionaries) as detectors in the RE2 standard as documented .

Contact Us

Schedule a Demo

You can schedule a demo or a meeting with our sales/solutions engineering team directly via Calendly here. If you don't see a suitable time, please email us at [email protected].

Email Us

For support inquiries, please email us at .

For sales inquiries, please email us at .

Best Practices - Security Investigation Workflows

The following workflows represent best practices for common security tasks. These step-by-step patterns guide you through effective multi-tool investigations.

Workflow 1: Incident Investigation

Purpose: Conduct an end-to-end security incident investigation

Steps:

Identify the scope: Search for related events using search_violations, search_exfiltration_events, or search_posture_events with your search criteria
Gather details: For each relevant result, use get_violation, get_exfiltration_event, or get_posture_event to get full context including affected assets, actors, and risk levels
Review findings: For violations, use get_violation_findings to see exactly what sensitive data was detected
Check activity timeline: Use the appropriate activity tools to understand what remediation has already been attempted
Assess user behavior: If an actor is identified, use get_actor_activity to check their recent activity across all event types
Summarize and recommend: Provide a structured incident summary with scope, affected assets, actors involved, risk assessment, and specific remediation actions

Example Conversation:

"Investigate the incident involving repository finance-api"
"Show me the findings for violation abc-123"
"What has user [email protected] been doing recently?"

Workflow 2: Violation Triage

Purpose: Prioritize and triage active DLP violations for remediation

Steps:

Fetch active violations: Use search_violations with query state:ACTIVE sorted by RISK_DESC to get highest-risk violations first
Categorize by severity: Group violations by risk_label (CRITICAL, HIGH, MEDIUM, LOW) and integration

Example Conversation:

"Triage all active violations, prioritize by risk"
"Show me details for the top 5 high-risk violations"
"What are the findings for these violations?"

Workflow 3: Compliance Reporting

Purpose: Generate security compliance summary across time periods

Steps:

Gather violation statistics: Use list_violations with createdAfter timestamp for your reporting period
Gather exfiltration statistics: Use list_exfiltration_events with the same time range

Example Conversation:

"Generate a compliance report for the last 90 days"
"Break down violations by integration and severity"
"Show me the top 10 incidents with details"

Workflow 4: User Risk Assessment

Purpose: Assess security risk profile for a specific user

Steps:

Find violations: Use search_violations with query user_email:[email] to find all DLP violations
Find exfiltration events: Use search_exfiltration_events with query actor_email:[email]

Example Conversation:

"Assess the risk profile for user [email protected]"
"Show me all violations and events involving this user"
"What patterns emerge from their behavior?"

Workflow 5: Guided Remediation

Purpose: Execute remediation actions on specific violations

Steps:

Review violation details: Use get_violation to understand context and available actions
Check findings: Use get_violation_findings to see what data is at risk
Verify appropriate action: Confirm the remediation action matches the violation severity and context

Example Conversation:

"Show me details for violation xyz-789"
"What are the available remediation actions?"
"Resolve this violation and document the action"

Multi-Step Tool Chaining

"Search for GitHub violations, get details on the top 3, and show me the sensitive findings"
"Find all violations by [email protected], check her recent activity, and assess her risk profile"
"List exfiltration events from last week, get details on any involving bulk downloads, and summarize the risk"

Multi-Tool Investigation Patterns

The most effective investigations use multiple tools in sequence. Follow these patterns:

Basic Investigation Pattern:

Search → Get Details → Analyze → Recommend

Deep Investigation Pattern:

Search → Get Details → Get Findings → Check Activity → Assess Actor → Recommend

Remediation Pattern:

Search → Get Details → Verify Context → Take Action → Confirm

When asking complex questions, the AI will automatically chain tools in the optimal order. You can also explicitly request multi-step workflows: "Search for high-risk violations, review the top 5, and create a remediation plan."

Effective Communication with AI

Be specific about time ranges: "last 7 days" is clearer than "recently"
Use exact usernames or email addresses when investigating specific actors
Ask follow-up questions to drill deeper: "Show me the findings" after reviewing a violation

Security

Store API keys in secure credential managers, never in code or configuration files committed to version control
Rotate API keys quarterly or immediately if compromise is suspected
Use dedicated API keys for each integration rather than sharing across systems

Effective Communication with AI

Be specific about time ranges: "last 7 days" is clearer than "recently"
Use exact usernames or email addresses when investigating specific actors
Ask follow-up questions to drill deeper: "Show me the findings" after reviewing a violation

Workflow Integration

Set up dedicated Slack/Teams channels for security alerts and use MCP to investigate directly from your collaboration tool
Create saved prompts for common investigations to maintain consistency across your security team
Document investigation procedures that leverage MCP for faster onboarding of new analysts

Supported File Types

The file scan API has first-class support for text extraction and scanning on all MIME types enumerated below.

Certain file types receive special handling, such as tabular data and archives of Git repositories, that results in more precise information about the location of findings within the source file.

Handling of MIME Types Not Listed

Files with a MIME type not listed below are processed using an unoptimized text extractor. As a result, the quality of the text extraction for unrecognized types may vary.

Accepted Text and Derivatives

application/json
application/x-ndjson
application/x-php
text/calendar

Accepted Office Formats

application/pdf
application/vnd.openxmlformats-officedocument.presentationml.presentation
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (treated as )

Accepted Archive and Compressed File Types

application/bzip2
application/ear
application/gzip
application/jar

Accepted Image File Types

image/apng
image/avif
image/gif
image/jpeg

Rejected MIME Types

The file scan API explicitly rejects requests with MIME types that are not conducive to extracting or scanning text. Sample rejected MIME types include:

application/photoshop
audio/midi
audio/wav
video/mp4

Spreadsheets and Tabular Data

File scans of Microsoft Office, Apache parquet, csv, and tab separated files will provide additional properties to locate findings within the document beyond the standard byteRange, codepointRange, and lineRange properties.

Findings will contain a columnRange and a rowRange that will allow you to identify the specific row and column within the tabular data wherein the finding is present.

This functionality is applicable to the following mime types:

text/csv
text/tab-separated-values
text/tsv
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

data files are also accepted.

Below is a sample match of a spreadsheet containing dummy PII where a SSN was detected in the 2nd column and 55th row.

Redacting CSV Files

Findings within csv files may be redacted.

To enable redaction in files, set the enableFileRedaction flag of your policy to "true"

The csv file will be redacted based on the configuration of the defaultRedactionConfig of the policy

Below is an example curl request for a csv file that has already been .

When results are sent to the location specified in the alertConfig (in this case an email address) a redactedFile property will be set with a fileURL in addition the findingsURL

This redacted file will be a modified version of the original csv file.

Below is an example of a redacted csv file.

Git Repositories

Nightfall provides special handling for archives of Git repositories.

Nightfall will scan the repository history to discover findings in particular checkin, returning the hash for the checkin.

In order to scan the repository, you will need to create a clone, i.e.

git clone https://github.com/nightfallai/nightfall-go-sdk.git

This creates a clone of the Nightfall go SDK.

You will then need to create an archive that can be uploaded using Nightfall's file scanning sequence.

zip -r directory.zip directory

Note that in order to work, the hidden directory .github must be included in the archive.

When you initiate the with this file, you will receive scan results that contain the commitHash property filled in.

Using the Nightfall go SDK archive created above, a simple example would be to scan for URLs (i.e. strings starting with http:// or https://), which will send results such as the following:

Support for Large Repositories

Currently, processing is limited to repositories with a total number of commits lower than 5000.

Large repositories result in a large volume of data sent at once. We are working on changes to allow these and other large surges of data to be processed in a more controlled manner, and will increase the limit or remove it altogether once those changes are complete.

Sensitive Data in GitHub Repositories

If the finding in a GitHub repository is considered to be sensitive, it should be considered compromised and appropriate mitigation steps (i.e. secrets should be rotated).

To retrieve the specific checkout, you will need to clone the repository, i.e.

git clone https://github.com/nightfallai/nightfall-go-sdk.git

You can then checkout the specific commit using the commit hash returned by Nightfall.

Note that you are in a when workin with this sort of check out of a repository.

File Scanning Limitations

CSV Files: Only the first 250,000 rows will be scanned.
Spreadsheet Files: Up to 100,000 rows per sheet will be scanned, with a maximum of 1 million rows across all tabs in multi-sheet spreadsheets.
PDF Files: Scanning is limited to the first 100 pages, including a maximum of 50 images within those pages.

Uploading and Scanning API Calls

Nightfall's upload process is built to accommodate files of any size. Once files are uploaded, they may be scanned with Detection Rules and Policies to detect potential violations.

Many users will find it more convenient to use our our native language SDKs to complete the upload process.

Uploading files using Client SDK libraries requires fewer steps as all the required API operations are wrapped in a single function call. Furthermore these SDKs handle all the programmatic logic necessary to send files in smaller chunks to Nightfall.

For users that are looking to understand the entire upload process end-to-end, that is also outlined in this document. We will walk you through the order of operations necessary to upload the file.

Using Nightfall's SDKs to Upload Files

Rather than implementing the for the upload functionality yourself, the Nightfall’s provide a single method that wraps the steps required to upload your file.

Below is an example of uploading a file from our and our .

To run the node sample script you must compile it as TypesScript. Save it as a .ts file and run

tsc <yourfilename>.ts -lib ES2015,DOM

You can then run the resulting JavaScript file:

NIGHTFALL_API_KEY=<YourApiKey> node yourscriptname.js

Note that these examples use an email address to receive the results for simplicity.

You may also want to use a webhook. See for additional information on how to set up Webhook server to receive these results.

The Upload Process

The upload process consists of 3 stages:

Once the upload is complete, you may initiate the

After we discuss each API call in the sequence, you will find a script that walks through the at the end of this guide.

Initializing Phase

POST /v3/upload

The first step in the process of scanning a binary file is to initiate an upload in order to get a fileId through the Initiate a .

As part of the initialization you must provide the total byte size of the file being uploaded.

You may also provide the mime-type, otherwise the system will attempt to determine it once the upload is complete.

The id of the returned JSON object will be used as the fileId in subsequent requests.

The chunkSize is the maximum number of bytes to upload during the uploading phase.

Uploading Phase

Use the endpoint to upload the file contents in chunks.

The size of these chunks are determined by the chunkSize value returned by POST /upload endpoint used in the previous step.

Below is a simple example where the file is less than the chunkSize so may safely be uploaded with one call to the upload endpoint.

If your file's size exceeds the chunkSize, to upload the complete file you will need to send iterative requests as you read portions of the file's contents. This means you will send multiple requests to the upload endpoint as shown above. As you do so, you will be updating the value of the X-Upload-Offset header based on the portion of the file being sent.

Each request should send a chunk of the file exactly chunkSize bytes long except for the final uploaded chunk. The final uploaded chunk is allowed to contain fewer bytes as the remainder of the file may be less than the chunkSize returned by the initialization step.

The request body should be the contents of the chunk being uploaded.

The value of the X-UPLOAD-OFFSET header should be the byte offset specifying where to insert the data into the file as an integer. This byte offset is zero-indexed.

Successful calls to this endpoint return an empty response with an HTTP status code of 204

See the below for an illustration as to how this upload process can be done programmatically.

Completion Phase

POST /v3/upload/<uploadUUID>/finish

Once all chunks are uploaded, mark the upload as completed using the .

When an upload completes successfully, the returned payload will indicate the mimeType the system determined to file to be if it was not provided during upload initialization.

Once a file has been marked as completed, you may initiate a scan of the uploaded file.

Scanning Uploaded Files

After an upload is finalized, it can be scanned against a Detection Policy. A Detection Policy represents a pairing of:

a webhook URL
a set of detection rules to scan data against

The scanning process is asynchronous, with results being delivered to the webhook URL configured on the detection policy. See for more information about creating a Webhook server.

Exactly one policy should be provided in the request body, which includes a webhookURL to which the callback will be made once the file scan has been completed (this must be an HTTPS URL) as well as a Detection Rule as either an a or as a rule that has been .

You may also supply a value to the requestMetadata field to help identify the input file upon receiving a response to your webhook. This field has a maximum length 10 KB.

Webhook Verification

Nightfall will verify that the webhook URL is valid before launching its asynchronous scan by issuing a challenge.

Full Upload Process Example Script

Below is a sample Python script that handles the complete sequence of API calls to upload a file using a path specified as an argument.

Using Policies to Send Alerts

Policies allow customers to create templates for their most common workflows such as sending alerts when detection rules are triggered.

These policies may be created manually through the dashboard or may be defined programmatically.

When defining an a Policy inline, in addition to specifying the Detection Rules (either by referencing the UUID of an existing Detection Rule or defining a Detection Rule and its Detectors inline), you must define an alertConfig which will determine where findings are sent.

The alertConfig can be either:

an email address
a Slack channel
a webhook url
a url to a SIEM host as well authentication and other headers

Below is a simple example of a payload with a policy that will send alerts to an email address that you would use with our endpoint for .

You will receive the following response:

Note that you may also use a pre-defined policy defined under Developer Platform > Overview > Policies by copying the Policy UUID and sending a request as shown below.

policy vs. policyUUIDs vs. config

The policy object supersedes the config object. The use of config objects will still continue to be supported, but its use should be considered deprecated. If you specify

The following payload will be sent to the given email address with the subject "🚨 Findings Detected by Nightfall! 🚨" as an attachment with the name nightfall-findings.json:

This attachment has the same content as the response payload to the initial request.

Note that the sender address will be [email protected]

This email address will not respond to messages sent to it.

Using Webhooks with Policies

Policies also allow you to send findings to a callback designated URL using the url property of the alertConfig object.

This mechanism allows you to programmatically consume findings and the data sent will contain sensitive information as well as additional metadata like the location of the findings in the payload. For this reason the URL must be an HTTPS URL and the service backing it be implemented to properly respond with your and act as a

Below is what Webhook URL should like in your policy's alertConfig in a payload sent to our endpoint used for scanning plain text.

Using Slack Channels With Policies

Another option supported by Policies is sending finding data to a designated Slack channel.

This feature requires that you have configured the .

Below is a sample payload for scanning plain text.

Below is an example as to how the violation will appear in Slack.

See the section on Slack in the overview on for more details.

Sending Alerts to SIEMs and other HTTP Event Collectors

SIEM (pronounced “sim”) is a combination of security information management (SIM) and security event management systems. SIEM technology collects event log data for analysis in order to provide visibility into network activity.

It is possible to send findings from a policy to a SIEM service such as LogRhythm, SumoLogic, or Splunk using the siem alertConfig.

This configuration will require a URL to a collector that uses an HTTPS endpoint.

Note that the URL for the siem alertConfig must:

use the HTTPS scheme
be able to accept requests made with the POST verb
respond with a 200 status code upon receipt of the event

See the documentation for your SIEM service for how to set up this URL.

Unlike the url alertConfig option, the siem alertConfig does not require that the endpoint for the service implement a custom challenge response. Events sent to the siem alertConfig endpoint contain a subset of what is sent to the url alertConfig. Furthermore the findings are sent in a redacted form similar to Slack or email alerts.

In addition to the URL, you may provide headers such as those that are used for authorization.

The headers in the SIEM alertConfig are divided into sensitiveHeaders and plainTextHeaders header mappings.

The sensitiveHeaders field is specifically for header values like authentication. Nightfall ensures that these header values are always hidden in our service. They are never logged or saved in analytic events.

You can use plainTextHeaders for all other type of information you would like passed along with Nightfall alerts to you HTTP endpoint. Nightfall assumes that the values stored plainTextHeaders do not contain any sensitive information so we do not take any action to hide or protect these values.

Below is an example of a payload using a siem alertConfig.

Other Policy Features

Using Redaction Within a Policy

A policy may be configured with default redaction rules as a defaultRedactionConfig that will affect the content of the redactedPayload field of the content that is sent to the alert locations specified in the policy alertConfig. Note that this redaction does not affect the findings themselves.

These redaction rules will be applied to Detection Rules that do not have a specified redaction configuration.

The redactionConfig specified must be one and only one of the four available redaction types:

maskConfig
infoTypeSubstitutionConfig
substitutionConfig
cryptoConfig

For more information on Redactions see:

Below is a simple example of a payload for using a policy set up to use a defaultRedactionConfig

Using Context Bytes Within a Policy

In additional to a defaultRedactionConfig it is possible to set the number of bytes to include as before and after a given finding as the contextBytes. This context can provide meaning to how the finding appears within the text to allow human readers to better understand the meaning of the finding. The maximum value for contextBytes is 40.

Using Redaction

The Nightfall API is capable of returning a redacted version of your scanned text when a Detector is triggered.

This functionality allows you to hide potentially sensitive information while retaining the original context in which that information appeared.

Specifying a RedactionConfig

In order to redact content, when you call the scan endpoint you must provide a RedactionConfig as part of the definition of your Detection Rule.

You may specify one of the following different methods to redact content:

apply (e.g. asterisks)
substitute a
substitute the triggered (referred to as "InfoType substitution")

A RedactionConfig is defined per Detector in a Detection Rule, allowing you to specify a different redaction method for each type of Detector in the rule.

By default, the redaction feature will return both the sensitive finding and the redacted version of that finding. You may set the removeFinding field to true if you want only the redacted version of the finding returned in the response.

Masking Characters

Specifying a MaskConfig as part of your RedactionConfig substitutes a character for each character in the matched text. By default the masking character is an asterisk (*). You may specify an alternate character to use instead (maskingChar).

You may also choose to only mask a portion of the original text by specifying a number of characters to leave unmasked (numCharsToLeaveUnmasked). For instance, if you want to mask all but the last 4 digits of a credit card number, set this value to 4 so that the redacted finding would be rendered as ***************4242.

In the case where you want to leave characters unmasked at the front of the string you may use the maskLeftToRight flag. This flag determines if masking is applied left to right (*****/1984) instead of right to left (01/01*****). By default, this value is false.

Below is an example of how a RedactionConfig would be configured to redact the text that triggers a DATE_OF_BIRTH Detector such that the text 01/11/1995 becomes ??/??/??95

Phrase Substitution

The SubstitutionConfig substitutes a sensitive finding with the value assigned to the property substitutionPhrase.

If no value is assigned to substitutionPhrase, the finding will be replaced with an empty string.

InfoType Substitution

It is possible to replace a sensitive finding with the name of the NIGHTFALL_DETECTOR that triggered it by using an InfoTypeSubstitutionConfig.

If you use the built in credit card Detector, the string 4242-4242-4242-4242 will be redacted to [CREDIT_CARD_NUMBER]

This config is only valid for Detector's with a detectorType of NIGHTFALL_DETECTOR.

Encryption

A CryptoConfig will encrypt a sensitive finding with a public key (provided as the publicKey property of the config) using RSA encryption.

Note that you are responsible for passing public keys for encryption and handling any decryption of the response payload. Nightfall will not store your keys.

Below is an example of a CryptoConfig being used to redact an EMAIL_ADDRESS detector.

Redactions in the Scan Response

The results of applying redactions are returned in the response payload for requests made to the as both part of an array named redactedPayload as well as additional properties of the finding object.

The original input payload with redactions made inline are returned as a list of strings under the redactedPayload property. Each item in the list of redacted payloads corresponds to the list of strings in the original input payload and, if a Detector was triggered, it will contain a redacted version of that corresponding string.

If an item in the input payload did not have any findings, the entry for that index will be an empty string ("").

The redactedPayload property is omitted if no RedactionConfig was provided.

Additionally, the fields redactedFinding and redactedLocation are added to the finding object when the redaction feature is invoked.

The redactedFinding field contains the redacted version of only the text of the finding without its surrounding context. This is useful when you are masking a portion of the text that triggered a Detector.

The redactedLocation property will be returned as part of the finding that corresponds to an item in the payload. This may be distinct from the location property that is returned for a finding by default.

In the unlikely case where there are findings that overlap, Nightfall will default to replacing the text of the overlapping findings with [REDACTED BY NIGHTFALL].

Example Redaction Call

The following example shows how the redaction functionality may be invoked, with a variety of different redaction methods applied to the different Detectors being used.

You can see in the response how the RedactionConfig associated with the various Detectors affects the different findings.

Note that because the 2nd item the payload matches multiple detectors, the redacted text in the redactedPayload property becomes [REDACTED BY NIGHTFALL]

Deploy a File Scanner for Sensitive Data in 40 Lines of Code

The service ingests a local file, scans it for sensitive data with Nightfall, and displays the results in a simple table UI.

We'll deploy the server on Render (a PaaS Heroku alternative) so that you can serve your application publicly in production instead of running it off your local machine. You'll build familiarity with the following tools and frameworks: Python, Flask, Nightfall, Ngrok, Jinja, Render.

Key Concepts

Before we get started on our implementation, start by familiarizing yourself with how scanning files works with Nightfall, so you're acquainted with the flow we are implementing.

In a nutshell, file scanning is done asynchronously by Nightfall; after you upload a file to Nightfall and trigger the scan, we perform the scan in the background. When the scan completes, Nightfall delivers the results to you by making a request to your webhook server. This asynchronous behavior allows Nightfall to scan files of varying sizes and complexities without requiring you to hold open a long synchronous request, or continuously poll for updates. The impact of this pattern is that you need a webhook endpoint that can receive inbound notifications from Nightfall when scans are completed - that's what we are building in this tutorial.

Getting Started

You can fork the sample repo and view the complete code , or follow along below. If you're starting from scratch, create a new GitHub repository.

Setting Up Dependencies

First, let's start by installing our dependencies. We'll be using Nightfall for data classification, the web framework in Python, and as our web server. Create requirements.txt and add the following to the file:

Then run pip install -r requirements.txt to do the installation.

Configuring Detection with Nightfall

Next, we'll need our Nightfall API Key and Webhook Signing Secret; the former authenticates us to the Nightfall API, while the latter authenticates that incoming webhooks are originating from Nightfall. You can retrieve your API Key and Webhook Signing Secret from the Nightfall . Complete the Nightfall Quickstart for a more detailed walk-through. for a free Nightfall account if you don't have one.

These values are unique to your account and should be kept safe. This means that we will store them as environment variables and should not store them directly in code or commit them into version control. If these values are ever leaked, be sure to visit the Nightfall Dashboard to re-generate new values for these secrets.

Setting Up Our Server

Let's start writing our Flask server. Create a file called app.py. We'll start by importing our dependencies and initializing the Flask and Nightfall clients:

Next, we'll add our first route, which will display "Hello World" when the client navigates to /ping simply as a way to validate things are working:

Run gunicorn app:app on the command line to fire up your server, and navigate to your local server in your web browser. You'll see where the web browser is hosted in the Gunicorn logs, typically it will be 127.0.0.1:8000 aka localhost:8000.

To expose our local webhook server via a public tunnel that Nightfall can send requests to, we'll use ngrok. Download and install ngrok via their quickstart documentation . We'll create an ngrok tunnel as follows:

After running this command, ngrok will create a tunnel on the public internet that redirects traffic from their site to your local machine. Copy the HTTPS tunnel endpoint that ngrok has created: we can use this as the webhook URL when we trigger a file scan.

Let's set this HTTPS endpoint as a local environment variable so we can reference it later:

Tip: With a Pro ngrok account, you can create a subdomain so that your tunnel URL is consistent, instead of randomly generated each time you start the tunnel.

Handling an Inbound Webhook

Before you send a file scan request to Nightfall, let's add logic for our incoming webhook endpoint, so that when Nightfall finishes scanning a file, it can successfully send the sensitive findings to us.

First, what does it mean to have findings? If a file has findings, this means that Nightfall identified sensitive data in the file that matched the detection rules you configured. For example, if you told Nightfall to look for credit card numbers, any substring from the request payload that matched our credit card detector would constitute sensitive findings.

We'll host our incoming webhook at /ingest with a POST method.

Nightfall will POST to the webhook endpoint, and in the inbound payload, Nightfall will indicate if there are sensitive findings in the file, and provide a link where we can access the sensitive findings as JSON.

Restart your server so the changes propagate. We'll take a look at the console output of our webhook endpoint and explain what it means in the next section.

Scan a File

Now, we want to trigger a file scan request, so that Nightfall will scan the file and send a POST request to our /ingest webhook endpoint when the scan is complete. We'll write a simple script that sends a file to Nightfall to scan it for . Create a new file called scan.py.

First, we'll establish our dependencies, initialize the Nightfall client, and specify the filepath to the file we wish to scan as well as the webhook endpoint we created above. The filepath is a relative path to any file, in this case we are scanning the sample-pci-xs.csv file which is in the same directory as scan.py. This is a sample CSV file with 10 credit card numbers in it - you can download it in the tutorial's GitHub .

Next, we will initiate the scan request to Nightfall, by specifying our filepath, webhook URL where the scan results should be posted, and our Detection Rule that specifies what sensitive data we are looking for.

In this simple example, we have specified an inline Detection Rule that detects Likely Credit Card Numbers. This Detection Rule is a simple starting point that just scratches the surface of the types of detection you can build with Nightfall. Learn more about building inline detection rules here or how to configure them in the Nightfall .

The scan_id is useful for identifying your scan results later.

View Sensitive Findings

Let's run scan.py to trigger our file scan job.

Once Nightfall has finished scanning the file, we'll see our Flask server receive the request at our webhook endpoint (/ingest). In our code above, we parse the webhook payload, and print the following when there are sensitive findings:

In our output, we are printing two URLs.

The first URL is provided to us by Nightfall. It is the temporary signed S3 URL that we can access to fetch the sensitive findings that Nightfall detected.

The second URL won't work yet, we'll implement it next. This URL a we constructed in our ingest() method above - the URL calls /view and passes the Findings URL above as a URL-escaped query parameter.

Let's add a method to our Flask server that opens this URL and displays the findings in a formatted table so that the results are easier to view than downloading them as JSON.

We'll do this by adding a view method that responds to GET requests to the /view route. The /view route will read the URL to the S3 Findings URL via a query parameter. It will then open the findings URL, parse it as JSON, pass the results to an HTML template, and display the results in a simple HTML table using . Jinja is a simple templating engine in Python.

Add the following to our Flask server in app.py:

Create the Table View

To display the findings in an HTML table, we'll create a new Flask template. Create a folder in your project directory called templates and add a new file within it called view.html.

Our template uses Jinja to iterate through our findings, and create a table row for each sensitive finding.

Now, if we restart our Flask server, trigger a file scan request, and navigate to the "View" URL printed in the server logs, we should see a formatted table with our results! In fact, we can input any Nightfall-provided signed S3 URL (after URL-escaping it) in the findings_url parameter of the /view route to view it.

Deploy on Render

As a longtime Heroku user, I was initially inclined to write this tutorial with instructions to deploy our app on Heroku. However, new PaaS vendors have been emerging and I was curious to try them out and see how they compare to Heroku. One such vendor is Render, which is where we'll deploy our app.

Deploying our service on Render is straightforward. If you're familiar with Heroku, the process is quite similar. Once you've signed up or logged into Render (free), we'll do the following:

Create a new Web Service on Render, and permit Render to access your new repo.
Use the following values during creation:

Environment: Python
Build Command: pip install -r requirements.txt
Start Command: gunicorn app:app

Let's also set our environment variables during creation. These are the same values we set locally.

Scan a file (in production)

Once Render has finished deploying, you'll get the base URL of your application. Set this as your NIGHTFALL_SERVER_URL locally and re-run scan.py - this time, the file scan request is served by your production Flask server running on Render!

To confirm this, navigate to the Logs tab in your Render app console, you'll see the webhook's output of your file scan results:

Navigate to the View link above in your browser to verify that you can see the results formatted in a table on your production site.

Congrats, you've successfully created a file scanning server and deployed it in production! You're now ready to build more advanced business logic around your file scanner. Here are some ideas on how to extend this tutorial:

Use WebSockets to send a notification back from the webhook to the client that initiated the file scan request
Build a more advanced detection rule using pre-built or custom detectors
Add a user interface to add more interactive capabilities, for example allowing users to upload files or read files from URLs

Building Endpoint DLP to Detect PII on Your Machine in Real-Time

Endpoint data loss prevention (DLP) discovers, classifies, and protects sensitive data - like PII, credit card numbers, and secrets - that proliferates onto endpoint devices, like your computer or EC2 machines. This is a way to help keep data safe, so that you can detect and stop occurrences of data exfiltration. Our endpoint DLP application will be composed of two core services that will run locally. The first service will monitor for file system events using the Watchdog package in Python. When a file system event is triggered, such as when a file is created or modified, the service will send the file to Nightfall to be scanned for sensitive data. The second service is a webhook server that will receive scan results from Nightfall, parse the sensitive findings, and write them to a CSV file as output. You'll build familiarity with the following tools and frameworks:

Python
Flask
Nightfall
Ngrok
Watchdog

Key Concepts

Before we get started on our implementation, start by familiarizing yourself with with Nightfall, so you're acquainted with the flow we are implementing.

In a nutshell, file scanning is done asynchronously by Nightfall; after you upload a file to Nightfall and trigger the scan, we perform the scan in the background. When the scan completes, Nightfall delivers the results to you by requesting your webhook server. This asynchronous behavior allows Nightfall to scan files of varying sizes and complexities without requiring you to hold open a long synchronous request, or continuously poll for updates. The impact of this pattern is that you need a webhook endpoint that can receive inbound notifications from Nightfall when scans are completed - that's one of the two services we are building in this tutorial.

Getting Started

You can fork the sample repo and view the complete code , or follow along below. If you're starting from scratch, create a new GitHub repository. This tutorial was developed on a Mac and assumes that's the endpoint operating system you're running, however, this tutorial should work across operating systems with minor modifications. For example, you may wish to extend this tutorial by running endpoint DLP on an EC2 machine to monitor your production systems.

Setting Up Dependencies

First, let's start by installing our dependencies. We'll be using Nightfall for data classification, the web framework in Python, for monitoring file system events, and as our web server. Create requirements.txt and add the following to the file:

Then run pip install -r requirements.txt to do the installation.

Configuring Detection with Nightfall

Monitoring File System Events

Watchdog is a Python module that watches for file system events. Create a file called scanner.py. We'll start by importing our dependencies and setting up a basic event handler. This event handler responds to file change events for file paths that match a given set of regular expressions (regexes). In this case, the .* indicates we are matching on any file path - we'll customize this a bit later. When a file system event is triggered, we'll print a line to the console.

Run python scanner.py and you'll notice lots of lines getting printed to the console. These are all the files that are getting created and changed on your machine in real-time. You'll notice that your operating system and the apps you're running are constantly writing, modifying, and deleting files on disk!

Next, we'll update our event handler so that instead of simply printing to the console, we are sending the file to Nightfall to be scanned. We will initiate the scan request to Nightfall, by specifying the file path of the changed/created file, a webhook URL where the scan results should be sent, and our Detection Rule that specifies what sensitive data we are looking for. If the file scan is initiated successfully, we'll print the corresponding Upload ID that Nightfall provides us to the console. This ID will be useful later when identifying scan results.

Here's our complete scanner.py, explained further below:

We can't run this just yet, since we need to set our webhook URL, which is currently reading from an environment variable that we haven't set yet. We'll create our webhook server and set the webhook URL in the next set of steps.

In this example, we have specified an inline Detection Rule that detects Likely Credit Card Numbers, Social Security Numbers, and API Keys. This Detection Rule is a simple starting point that just scratches the surface of the types of detection you can build with Nightfall. Learn more about building inline detection rules here or how to configure them in the Nightfall .

Also note that we've updated our regex from .* to a set of file paths on Macs that commonly contain user generated files - the Desktop, Documents, and Downloads folders:

You can customize these regexes to whatever file paths are of interest to you. Another option is to write a catch-all regex that ignores/excludes paths to config and temp files:

Setting Up Webhook Server

Next, we'll set up our Flask webhook server, so we can receive file scanning results from Nightfall. Create a file called app.py. We'll start by importing our dependencies and initializing the Flask and Nightfall clients:

Next, we'll add our first route, which will display "Hello World" when the client navigates to /ping simply as a way to validate things are working:

In a second command line window, run gunicorn app:app on the command line to fire up your server, and navigate to your local server in your web browser. You'll see where the web browser is hosted in the Gunicorn logs, typically it will be 127.0.0.1:8000 aka localhost:8000.

Let's set this HTTPS endpoint as a local environment variable so we can reference it later:

With a Pro ngrok account, you can create a subdomain so that your tunnel URL is consistent, instead of randomly generated each time you start the tunnel.

Handling Inbound Webhooks

Before we send a file scan request to Nightfall, let's implement our incoming webhook endpoint, so that when Nightfall finishes scanning a file, it can successfully send the sensitive findings to us.

We'll host our incoming webhook at /ingest with a POST method.

We'll validate the inbound webhook from Nightfall, retrieve the JSON findings from the link provided, and write the findings to a CSV file. First, let's initialize our CSV file where we will write results, and add our /ingest POST method.

You'll notice that when there are sensitive findings, we call the output_results() method. Let's write that next. In output_results(), we are going to parse the findings and write them as rows into our CSV file.

Restart your server so the changes propagate. We'll take a look at the console and CSV output of our webhook endpoint in the next section.

Scan Changed Files in Real-Time

In our previous command line window, we can now turn our attention back to scanner.py. We now have our webhook URL so let's set it here as well and run our scanner.

To trigger a file scan event, download the following . Assuming it automatically downloads to your Downloads folder, this should immediately trigger a file change event and you'll see console log output! If not, you can also download the file with curl into a location that matches your event handler's regex we set earlier.

You'll see the following console output from scanner.py:

And the following console output from our webhook server:

And the following sensitive findings written to results.csv:

Each row in the output CSV will correspond to a sensitive finding. Each row will have the following fields, which you can customize in app.py: the upload ID provided by Nightfall, an incrementing index, timestamp, characters before the sensitive finding (for context), the sensitive finding itself, characters after the sensitive finding (for context), the confidence level of the detection, the byte range location (character indicies) of the sensitive finding in its parent file, and the corresponding detection rules that flagged the sensitive finding.

Note that you may also see events for system files like .DS_Store or errors corresponding to failed attempts to scan temporary versions of files. This is because doing things like downloading a file can trigger multiple file modification events. As an extension to this tutorial, you could consider filtering those out further, though they shouldn't impact our ability to scan files of interest.

If we leave these services running, we'll continue to monitor files for sensitive data and appending to our results CSV when sensitive findings are discovered!

Running Endpoint DLP in the Background

We can run both of our services in the background nohup so that we don't need to leave two command line tabs open indefinitely. We'll pipe console output to log files so that we can always reference the application's output or determine if the services crashed for any reason.

This will return the corresponding process IDs - we can always check on these later with the ps command.

Next Steps

This post is simply of a proof of concept version of endpoint DLP. Building a production-grade endpoint DLP application will have additional complexity and functionality. However, the detection engine is one of the biggest components of an endpoint DLP system, and this example should give you a sense of how easy it is to integrate with Nightfall's APIs and the power of Nightfall's detection engine.

Here are few ideas on how you can extend upon this service further:

Run the scanner on EC2 machines to scan your production machines in real-time
Respond to more system events like I/O of USB drives and external ports
Implement remediation actions like end-user notifications or file deletion

Nightfall MCP Documentation

Overview

Key Benefits

Natural Language Interface: Ask questions in plain English instead of learning complex query syntax
Faster Investigations: Get instant answers to security questions without switching between tools
Workflow Integration: Access Nightfall data directly in your development and collaboration environments

Technical Specifications

Property

Value

Getting Started

Prerequisites

Before connecting to the Nightfall MCP server, ensure you have:

An active Nightfall subscription with appropriate permissions
A Nightfall API key from the Developer Platform
An MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, or custom)

Generating Your API Key

Create or open your Nightfall account

Security Note: Your API key provides full access to your Nightfall data. Never commit it to version control or share it publicly.

Connecting Your AI Client

The Nightfall MCP server supports any MCP-compatible client. Below are configuration examples for popular AI tools.

Claude Desktop

Add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Replace YOUR_NIGHTFALL_API_KEY with your actual API key, then restart Claude Desktop.

Cursor

Open Cursor Settings > MCP and add:

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

Custom Integration

For custom MCP clients, connect using Streamable HTTP transport:

The server operates in stateless mode and returns application/json responses.

Available Tools

The Nightfall MCP server provides 16 specialized tools organized into four categories.

DLP Violations (6 tools)

Work with Data Loss Prevention policy violations detected across your integrations.

Tool Name

Description

Exfiltration Events (4 tools)

Investigate data exfiltration attempts and suspicious file activity.

Tool Name

Description

Security Posture Events (4 tools)

Monitor configuration risks and permission changes.

Tool Name

Description

Activity Tools (2 tools)

Track user and asset activity across all event types.

Tool Name

Description

Common Use Cases

Here are real-world scenarios where the Nightfall MCP server delivers immediate value.

Security Investigations

Example: "Show me all active high-risk violations from GitHub in the last week"

Insider Threat Response

Example: "What has user [email protected] been doing in the last 30 days?"

Get a complete timeline of user activity including file downloads, permission changes, and policy violations. The AI summarizes patterns and flags anomalies automatically.

Bulk Remediation

Example: "Resolve all pending Slack violations from the #general channel"

Instead of manually processing violations one by one, describe the action in natural language. The AI finds matching violations and executes the appropriate remediation action.

Compliance Reporting

Example: "Generate a summary of all HIPAA violations this quarter grouped by department"

The AI retrieves relevant data, performs grouping and aggregation, and creates a formatted report—all from a single request.

Data Exfiltration Detection

Example: "Are there any exfiltration events involving bulk downloads from Google Drive?"

Quickly identify potential data theft attempts by searching for specific event patterns across your cloud storage integrations.

Permission Audits

Example: "List all posture events with permission changes this month"

Monitor access control changes across your environment to identify security configuration drift or policy violations.

Query Examples

These examples demonstrate the flexibility of natural language queries. You don't need to memorize syntax—just describe what you need.

Basic Searches

"Show me today's violations"
"List high-risk violations in the last 7 days"
"Find violations in the engineering-team Slack channel"

User-Specific Queries

"Show violations by [email protected]"
"What files has [email protected] accessed this week?"
"Track user activity for [email protected]"

Integration-Specific

"Find all Salesforce violations in the Sales org"
"Show Google Drive files shared externally"
"List Confluence pages with public links"

Advanced Analysis

"Compare violation trends month over month"
"Identify users with the most violations"
"What types of sensitive data are most commonly exposed?"

Remediation Actions

"Mark these violations as resolved"
"Block access to this file"
"Delete violations in test channels"

Best Practices

Security

Store API keys in secure credential managers, never in code or configuration files committed to version control
Rotate API keys quarterly or immediately if compromise is suspected
Use dedicated API keys for each integration rather than sharing across systems

Query Optimization

Start with broader queries and refine based on results rather than trying to construct perfect queries immediately
Use date ranges to limit result sets when investigating recent incidents
Ask for pagination when dealing with large result sets to avoid overwhelming responses

Effective Communication with AI

Be specific about time ranges: "last 7 days" is clearer than "recently"
Use exact usernames or email addresses when investigating specific actors
Ask follow-up questions to drill deeper: "Show me the findings" after reviewing a violation

Workflow Integration

Set up dedicated Slack/Teams channels for security alerts and use MCP to investigate directly from your collaboration tool
Create saved prompts for common investigations to maintain consistency across your security team
Document investigation procedures that leverage MCP for faster onboarding of new analysts

Troubleshooting

Connection Issues

Problem: "Unauthorized" or 401 errors

Solutions:

Verify your API key is correctly pasted in the configuration file (no extra spaces)
Check that the API key hasn't expired or been revoked in the Nightfall dashboard

Problem: MCP server not appearing in client

Solutions:

Verify the configuration file is in the correct location for your operating system
Check JSON syntax is valid (use a JSON validator if needed)

Query Issues

Problem: No results returned

Solutions:

Broaden your time range (data may be older than expected)
Check filter criteria aren't too restrictive

Problem: Rate limit errors (429)

Solutions:

Wait for the duration specified in the Retry-After header
Reduce query frequency or batch similar requests

Performance

Problem: Slow query responses

Solutions:

Use more specific filters to reduce result set size
Limit date ranges to recent periods when possible

Support and Resources

Getting Help

If you encounter issues not covered in this guide:

Email Support: [email protected]
Documentation: https://docs.nightfall.ai
Dashboard: https://app.nightfall.ai

Providing Feedback

We continuously improve the MCP server based on customer feedback. Please share:

Feature requests for new query capabilities
Use cases we should highlight in documentation
Integration challenges or configuration pain points

Additional Learning Resources

Model Context Protocol Specification: https://modelcontextprotocol.io
Nightfall API Documentation: https://docs.nightfall.ai/reference
Security Best Practices Guide: Available in Nightfall Dashboard > Resources

Appendix: Query Field Reference

This section provides a comprehensive reference of searchable fields across different event types. Use these when constructing advanced queries.

DLP Violation Fields

Core Fields

state: ACTIVE, PENDING, RESOLVED, EXPIRED
integration_name: github, gdrive, slack, confluence, jira, salesforce, teams, onedrive, etc.
risk_label: HIGH, MEDIUM, LOW

Integration-Specific Fields

Slack

slack.channel_name, slack.channel_id, slack.workspace

GitHub

github.org, github.repository, github.repository_owner, github.branch, github.commit, github.author_email

Google Drive

gdrive.drive

Confluence

confluence.space_name, confluence.parent_page_name

Jira

jira.project_name, jira.ticket_number

Salesforce

salesforce.org_name, salesforce.object, salesforce.record_id

Microsoft Teams

teams.team_name, teams.channel_name, teams.channel_type, teams.team_sensitivity, teams.sender, teams.msg_importance, teams.msg_attachment, teams.chat_id, teams.chat_type, teams.chat_topic

OneDrive

onedrive.drive_owner, onedrive.drive_owner_email, onedrive.file_name, onedrive.created_by, onedrive.created_by_email, onedrive.modified_by, onedrive.modified_by_email

Zendesk

zendesk.ticket_status, zendesk.ticket_title, zendesk.ticket_group_assignee, zendesk.current_user_role

Notion

notion.created_by, notion.last_edited_by, notion.page_title, notion.workspace_name

Gmail

gmail.user_name, gmail.from, gmail.to, gmail.cc, gmail.bcc, gmail.thread_id, gmail.subject, gmail.attachment_name, gmail.attachment_type

Exfiltration Event Fields

Core Fields

event_type: file_download, file_upload, permission_change, etc.
state: ACTIVE, PENDING, RESOLVED, EXPIRED
last_actioned_by: NIGHTFALL, ADMIN, END_USER

Actor Fields

actor_name, actor_email
user_name, user_email (backward compatible aliases)

Resource Fields

resource_id, resource_name, resource_owner_name, resource_owner_email, resource_content_type, notes

Endpoint Fields

endpoint.device_id, endpoint.machine_name

Google Drive

gdrive.permission, gdrive.shared_internal_email, gdrive.shared_external_email, gdrive.drive, gdrive.file_owner, gdrive.label_name

Salesforce

salesforce.report.scope, salesforce.report.event_source, salesforce.report.source_ip, salesforce.report.session_level, salesforce.report.operation, salesforce.report.description
salesforce.file.source_ip

Security Posture Event Fields

Security posture events support the same query fields as exfiltration events.

Query Operators

AND: Combine multiple conditions (both must match)
OR: Alternative conditions (either can match)
field:value syntax for exact matches

Example:

Common Query Patterns

Find violations by user and integration:

Search across multiple users:

Filter by channel and state:

Time-based queries:

Error Handling

The MCP server returns structured errors in tool responses:

Error Code

Description

HTTP-level errors from the API gateway:

Status

Description

Pagination

Tools that return lists support cursor-based pagination. When more results are available, the response includes a nextPageToken field. Pass this value as pageToken in your next request to fetch the next page.

Simply ask: "Show me the next page of results"

The AI client handles this automatically when you ask for more results.

Rate Limits

MCP requests share the same rate limits and quotas as the Nightfall REST API. If you receive a 429 response, wait for the duration indicated in the Retry-After header before retrying.

For questions or support: [email protected]

Fetch violations

get

Fetch a list of violations for a period

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

createdAfterintegerOptional

Unix timestamp in seconds, filters records created ≥ the value, defaults to -90 days UTC

createdBeforeintegerOptional

Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC

updatedAfterintegerOptional

Unix timestamp in seconds, filters records updated > the value

limitinteger · max: 100Optional

The maximum number of records to be returned in the response

Default: 50

pageTokenstringOptional

Cursor for getting the next page of results

Responses

200

Successful response

application/json

X-Rate-Limit-RemainingintegerOptional

How many remaining requests you can make within the next second before being throttled

X-Quota-RemainingintegerOptional

How many remaining requests you can make within the next quota period

X-Quota-Period-Endstring · date-timeOptional

When the current quota period expires

idstringOptional

The violation id

integrationstring · enumOptional

The integration name

Possible values:

createdAtintegerOptional

Unix timestamp when the violation was created

updatedAtintegerOptional

Unix timestamp when the violation was updated

itemsstring · enumOptionalPossible values:

statestring · enumOptional

The current state of the violation

Possible values:

resourceLinkstringOptional

The link to the resource on the integration

locationstringOptional

The channel name in case of a message in a channel

locationTypestringOptional

Type of location

usernamestringOptional

User name

userIDstringOptional

ID - user

messagePermalinkstringOptional

Link to message

locationMembersstring[]Optional

Members for the location

locationMemberCountintegerOptional

Count of members for the location

channelIDstringOptional

ID - channel

workspaceNamestringOptional

Name of workspace

itemNamestringOptional

Name of item

itemTypestringOptional

Type of item

isArchivedbooleanOptional

Archived status

createdAtintegerOptional

Unix timestamp

updatedAtintegerOptional

Unix timestamp

labelsstring[]Optional

List of labels

spaceNamestringOptional

Name of space

spaceKeystringOptional

Key of space

spaceNameLinkstringOptional

Link of space

parentPageNamestringOptional

Parent page

authorNamestringOptional

Name of author

authorEmailstringOptional

Email of author

authorNameLinkstringOptional

Link of author name

permalinkstringOptional

Link to resource

confluenceIDstringOptional

ID - Confluence internal

confluenceUserIDstringOptional

ID - Confluence user

itemVersionintegerOptional

Version of item

parentPageIDstringOptional

ID - parent page

parentVersionintegerOptional

Version of parent page

fileIDstringOptional

ID of file

fileNamestringOptional

The name of the file

fileTypestringOptional

Type of file

fileSizestringOptional

File size

fileLinkstringOptional

Link to file

permissionSettingstringOptional

Permissions

sharingExternalUsersstring[]Optional

User list shared with - external

sharingInternalUsersstring[]Optional

User list shared with - internal

canViewersDownloadbooleanOptional

Available for viewers to download

fileOwnerstringOptional

File owner

isInTrashbooleanOptional

In trash

createdAtintegerOptional

Unix timestamp, when the file was created

updatedAtintegerOptional

Unix timestamp, when the file was updated

drivestringOptional

Drive name

updatedBystringOptional

Updated by user

projectNamestringOptional

Name of project

ticketNumberstringOptional

Ticket number

projectTypestringOptional

Type of project

issueIDstringOptional

ID for the issue

projectLinkstringOptional

Link to project

ticketLinkstringOptional

Link to ticket

commentLinkstringOptional

Link to comment

attachmentLinkstringOptional

Link to attachment

branchNamestringOptional

Branch on which violation occurred

organizationstringOptional

Name of the organization or username in case of an individual account

repositorystringOptional

Name of the repository

authorEmailstringOptional

Email of the user who pushed the changes to GitHub

authorUsernamestringOptional

Username of the user who pushed the changes to GitHub

createdAtintegerOptional

Unix timestamp

isRepoPrivatebooleanOptional

Boolean to check if the repo is private or public

filePathstringOptional

Path of the file on which violation occurred

githubPermalinkstringOptional

Permalink to the version of the file where sensitive content was identified

repositoryOwnerstringOptional

Owner of the repository

githubRepoLinkstringOptional

Link to the repository

orgNamestringOptional

Name of the Salesforce organization

recordIDstringOptional

ID of the record

objectNamestringOptional

Name of the object

contentTypestringOptional

Attachment or Object

userIDstringOptional

ID of the user

userNamestringOptional

Salesforce username of the author

updatedAtintegerOptional

Unix timestamp when the object was last updated

fieldsstring[]Optional

Fields of the Object

fileTypestringOptional

File Type

attachmentLinkstringOptional

Link to the attachment

attachmentNamestringOptional

Name of the attachment

objectLinkstringOptional

Link to the object

ticketStatusstringOptional

Status of the ticket

ticketTitlestringOptional

Title of the ticket

ticketRequestorstringOptional

Ticket requested by

ticketGroupAssigneestringOptional

Group the ticket is assigned to

ticketAgentAssigneestringOptional

Agent the ticket is assigned to

currentUserRolestringOptional

User role

ticketIDintegerOptional

ID of the ticket

ticketFollowersstring[]Optional

Followers of the ticket

ticketTagsstringOptional

Tags for the ticket

createdAtintegerOptional

Unix timestamp

UpdatedAtintegerOptional

Unix timestamp

locationstringOptional

Location

subLocationstringOptional

Sub-location

ticketCommentIDintegerOptional

ID - ticket comment

ticketGroupIDintegerOptional

ID - ticket group

ticketGroupLinkstringOptional

Link to the ticket group

ticketAgentIDintegerOptional

ID - ticket agent

ticketAgentLinkstringOptional

Link - ticket agent

ticketEventstringOptional

Ticket event

userRolestringOptional

Role of the user

attachmentNamestringOptional

Name of the attachment

attachmentLinkstringOptional

Link for the attachment

createdBystringOptional

Page creator

updatedBystringOptional

Page update by

workspaceNamestringOptional

Workspace name

workspaceLinkstringOptional

Link to workspace

pageIDstringOptional

ID of the page

pageTitlestringOptional

Title of the page

createdAtintegerOptional

Unix timestamp

updatedAtintegerOptional

Unix timestamp

privatePageLinkstringOptional

Private page link

publicPageLinkstringOptional

Public page link

sharedExternallybooleanOptional

Externally shared state

attachmentIDstringOptional

ID of the attachment

locationstringOptional

Page URL where the extension is launched

subLocationstringOptional

Specific location on the page

browserNamestringOptional

Browser type

userCommentstringOptional

Remediation comment from the user

teamNamestringOptional

Name of the team containing the channel where the message was sent

tenantIDstringOptional

ID of the tenant

tenantDomainstringOptional

Domain name of the tenant

teamIDstringOptional

ID of the team containing the channel where the message was sent

teamVisibilitystringOptional

Visibility of the team containing the channel where the message was sent

teamWebURLstringOptional

Web URL of the team containing the channel where the message was sent

channelIDstringOptional

ID of the channel where the message was sent

channelNamestringOptional

Name of the channel where the message was sent

channelTypestringOptional

Type of the channel where the message was sent

channelWebURLstringOptional

Web URL of the channel where the message was sent

messageIDstringOptional

ID of the message

createdAtintegerOptional

Unix timestamp

updatedAtintegerOptional

Unix timestamp

chatMessageSenderstringOptional

Sender of the chat message

userIDstringOptional

ID of the user who sent the message

userPrincipalNamestringOptional

Principal name of the user who sent the message

attachmentIDstringOptional

ID of the attachment present in the message

attachmentNamestringOptional

Name of the attachment present in the message

attachmentURLstringOptional

URL of the attachment present in the message

chatMessageImportancestringOptional

Importance of the sent message

chatIDstringOptional

ID of the chat conversation

chatTypestringOptional

Type of the chat conversation (one-on-one, group, meeting)

chatTopicstringOptional

Topic or subject of the chat conversation

userIDstringOptional

ID of the user participating in the chat conversation

emailstringOptional

email address of the chat participant

displayNamestringOptional

display name of the chat participant

tenantIDstringOptional

ID of the tenant

tenantDomainstringOptional

Domain name of the tenant

driveItemIDstringOptional

ID of the drive item

driveItemNamestringOptional

Name of the drive item

driveItemURLstringOptional

URL of the drive item

driveItemMimeTypestringOptional

Mime type of the drive item

driveItemSizeintegerOptional

Size of the drive item in bytes

parentPathstringOptional

Path to the drive item relative to the root of the drive

createdByIDstringOptional

ID of the user who created the drive item

updatedByEmailstringOptional

Email of the user who last updated the drive item

updatedByIDstringOptional

ID of the user who last updated the drive item

updatedByNamestringOptional

Name of the user who last updated the drive item

createdAtintegerOptional

Unix timestamp when the drive item was created

updatedAtintegerOptional

Unix timestamp when the drive item was last updated

specialFolderNamestringOptional

Name of the special folder if drive item is inside one

driveIDstringOptional

ID of the drive where the drive item is present

driveOwnerNamestringOptional

Name of user who owns the drive where the drive item is present

driveOwnerEmailstringOptional

Email of user who owns the drive where the drive item is present

driveOwnerIDstringOptional

ID of user who owns the drive where the drive item is present

domainstringOptional

Domain of the company where email was sent from

user_namestringOptional

User Name who sent the email

fromstringOptional

Email of the sender

tostring[]Optional

Recipients of the Email

ccstring[]Optional

Recipients mentioned in the CC field of the Email

bccstring[]Optional

Recipients mentioned in the BCC field of the Email

subjectstringOptional

Subject of the email

sent_atintegerOptional

Unix timestamp of when email was sent

thread_idstringOptional

ThreadID of the email

attachment_namestringOptional

Name of the attachment

attachment_typestringOptional

Type of attachment

fileNamestringOptional

The name of the file

mimeTypestringOptional

The file mime type

permalinkstringOptional

The link to the resource on the integration

policyUUIDsstring[]Optional

Policies violated

detectionRuleUUIDsstring[]Optional

Detection rules triggered

detectorUUIDsstring[]Optional

Detectors triggered

riskstring · enumOptional

The risk label associated to this violation

Possible values:

riskSourcestring · enumOptional

The source of calculation of risk associated to this violation

Possible values:

riskScorenumber · floatOptional

The calculated score of the risk for this violation

usernamestringOptional

Username as on the integration

userEmailstringOptional

User email as on the integration, may be empty

nextPageTokenstringOptional

Next page cursor, omitted if end of results reached

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/violations

Fetch violation

get

Fetch a violation by ID

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

violationIdstring · uuidRequired

The UUID of the violation to fetch

Responses

200

Successful response

application/json

X-Rate-Limit-RemainingintegerOptional

How many remaining requests you can make within the next second before being throttled

X-Quota-RemainingintegerOptional

How many remaining requests you can make within the next quota period

X-Quota-Period-Endstring · date-timeOptional

When the current quota period expires

idstringOptional

The violation id

integrationstring · enumOptional

The integration name

Possible values:

createdAtintegerOptional

Unix timestamp when the violation was created

updatedAtintegerOptional

Unix timestamp when the violation was updated

itemsstring · enumOptionalPossible values:

statestring · enumOptional

The current state of the violation

Possible values:

resourceLinkstringOptional

The link to the resource on the integration

locationstringOptional

The channel name in case of a message in a channel

locationTypestringOptional

Type of location

usernamestringOptional

User name

userIDstringOptional

ID - user

messagePermalinkstringOptional

Link to message

locationMembersstring[]Optional

Members for the location

locationMemberCountintegerOptional

Count of members for the location

channelIDstringOptional

ID - channel

workspaceNamestringOptional

Name of workspace

itemNamestringOptional

Name of item

itemTypestringOptional

Type of item

isArchivedbooleanOptional

Archived status

createdAtintegerOptional

Unix timestamp

updatedAtintegerOptional

Unix timestamp

labelsstring[]Optional

List of labels

spaceNamestringOptional

Name of space

spaceKeystringOptional

Key of space

spaceNameLinkstringOptional

Link of space

parentPageNamestringOptional

Parent page

authorNamestringOptional

Name of author

authorEmailstringOptional

Email of author

authorNameLinkstringOptional

Link of author name

permalinkstringOptional

Link to resource

confluenceIDstringOptional

ID - Confluence internal

confluenceUserIDstringOptional

ID - Confluence user

itemVersionintegerOptional

Version of item

parentPageIDstringOptional

ID - parent page

parentVersionintegerOptional

Version of parent page

fileIDstringOptional

ID of file

fileNamestringOptional

The name of the file

fileTypestringOptional

Type of file

fileSizestringOptional

File size

fileLinkstringOptional

Link to file

permissionSettingstringOptional

Permissions

sharingExternalUsersstring[]Optional

User list shared with - external

sharingInternalUsersstring[]Optional

User list shared with - internal

canViewersDownloadbooleanOptional

Available for viewers to download

fileOwnerstringOptional

File owner

isInTrashbooleanOptional

In trash

createdAtintegerOptional

Unix timestamp, when the file was created

updatedAtintegerOptional

Unix timestamp, when the file was updated

drivestringOptional

Drive name

updatedBystringOptional

Updated by user

projectNamestringOptional

Name of project

ticketNumberstringOptional

Ticket number

projectTypestringOptional

Type of project

issueIDstringOptional

ID for the issue

projectLinkstringOptional

Link to project

ticketLinkstringOptional

Link to ticket

commentLinkstringOptional

Link to comment

attachmentLinkstringOptional

Link to attachment

branchNamestringOptional

Branch on which violation occurred

organizationstringOptional

Name of the organization or username in case of an individual account

repositorystringOptional

Name of the repository

authorEmailstringOptional

Email of the user who pushed the changes to GitHub

authorUsernamestringOptional

Username of the user who pushed the changes to GitHub

createdAtintegerOptional

Unix timestamp

isRepoPrivatebooleanOptional

Boolean to check if the repo is private or public

filePathstringOptional

Path of the file on which violation occurred

githubPermalinkstringOptional

Permalink to the version of the file where sensitive content was identified

repositoryOwnerstringOptional

Owner of the repository

githubRepoLinkstringOptional

Link to the repository

orgNamestringOptional

Name of the Salesforce organization

recordIDstringOptional

ID of the record

objectNamestringOptional

Name of the object

contentTypestringOptional

Attachment or Object

userIDstringOptional

ID of the user

userNamestringOptional

Salesforce username of the author

updatedAtintegerOptional

Unix timestamp when the object was last updated

fieldsstring[]Optional

Fields of the Object

fileTypestringOptional

File Type

attachmentLinkstringOptional

Link to the attachment

attachmentNamestringOptional

Name of the attachment

objectLinkstringOptional

Link to the object

ticketStatusstringOptional

Status of the ticket

ticketTitlestringOptional

Title of the ticket

ticketRequestorstringOptional

Ticket requested by

ticketGroupAssigneestringOptional

Group the ticket is assigned to

ticketAgentAssigneestringOptional

Agent the ticket is assigned to

currentUserRolestringOptional

User role

ticketIDintegerOptional

ID of the ticket

ticketFollowersstring[]Optional

Followers of the ticket

ticketTagsstringOptional

Tags for the ticket

createdAtintegerOptional

Unix timestamp

UpdatedAtintegerOptional

Unix timestamp

locationstringOptional

Location

subLocationstringOptional

Sub-location

ticketCommentIDintegerOptional

ID - ticket comment

ticketGroupIDintegerOptional

ID - ticket group

ticketGroupLinkstringOptional

Link to the ticket group

ticketAgentIDintegerOptional

ID - ticket agent

ticketAgentLinkstringOptional

Link - ticket agent

ticketEventstringOptional

Ticket event

userRolestringOptional

Role of the user

attachmentNamestringOptional

Name of the attachment

attachmentLinkstringOptional

Link for the attachment

createdBystringOptional

Page creator

updatedBystringOptional

Page update by

workspaceNamestringOptional

Workspace name

workspaceLinkstringOptional

Link to workspace

pageIDstringOptional

ID of the page

pageTitlestringOptional

Title of the page

createdAtintegerOptional

Unix timestamp

updatedAtintegerOptional

Unix timestamp

privatePageLinkstringOptional

Private page link

publicPageLinkstringOptional

Public page link

sharedExternallybooleanOptional

Externally shared state

attachmentIDstringOptional

ID of the attachment

locationstringOptional

Page URL where the extension is launched

subLocationstringOptional

Specific location on the page

browserNamestringOptional

Browser type

userCommentstringOptional

Remediation comment from the user

teamNamestringOptional

Name of the team containing the channel where the message was sent

tenantIDstringOptional

ID of the tenant

tenantDomainstringOptional

Domain name of the tenant

teamIDstringOptional

ID of the team containing the channel where the message was sent

teamVisibilitystringOptional

Visibility of the team containing the channel where the message was sent

teamWebURLstringOptional

Web URL of the team containing the channel where the message was sent

channelIDstringOptional

ID of the channel where the message was sent

channelNamestringOptional

Name of the channel where the message was sent

channelTypestringOptional

Type of the channel where the message was sent

channelWebURLstringOptional

Web URL of the channel where the message was sent

messageIDstringOptional

ID of the message

createdAtintegerOptional

Unix timestamp

updatedAtintegerOptional

Unix timestamp

chatMessageSenderstringOptional

Sender of the chat message

userIDstringOptional

ID of the user who sent the message

userPrincipalNamestringOptional

Principal name of the user who sent the message

attachmentIDstringOptional

ID of the attachment present in the message

attachmentNamestringOptional

Name of the attachment present in the message

attachmentURLstringOptional

URL of the attachment present in the message

chatMessageImportancestringOptional

Importance of the sent message

chatIDstringOptional

ID of the chat conversation

chatTypestringOptional

Type of the chat conversation (one-on-one, group, meeting)

chatTopicstringOptional

Topic or subject of the chat conversation

userIDstringOptional

ID of the user participating in the chat conversation

emailstringOptional

email address of the chat participant

displayNamestringOptional

display name of the chat participant

tenantIDstringOptional

ID of the tenant

tenantDomainstringOptional

Domain name of the tenant

driveItemIDstringOptional

ID of the drive item

driveItemNamestringOptional

Name of the drive item

driveItemURLstringOptional

URL of the drive item

driveItemMimeTypestringOptional

Mime type of the drive item

driveItemSizeintegerOptional

Size of the drive item in bytes

parentPathstringOptional

Path to the drive item relative to the root of the drive

createdByIDstringOptional

ID of the user who created the drive item

updatedByEmailstringOptional

Email of the user who last updated the drive item

updatedByIDstringOptional

ID of the user who last updated the drive item

updatedByNamestringOptional

Name of the user who last updated the drive item

createdAtintegerOptional

Unix timestamp when the drive item was created

updatedAtintegerOptional

Unix timestamp when the drive item was last updated

specialFolderNamestringOptional

Name of the special folder if drive item is inside one

driveIDstringOptional

ID of the drive where the drive item is present

driveOwnerNamestringOptional

Name of user who owns the drive where the drive item is present

driveOwnerEmailstringOptional

Email of user who owns the drive where the drive item is present

driveOwnerIDstringOptional

ID of user who owns the drive where the drive item is present

domainstringOptional

Domain of the company where email was sent from

user_namestringOptional

User Name who sent the email

fromstringOptional

Email of the sender

tostring[]Optional

Recipients of the Email

ccstring[]Optional

Recipients mentioned in the CC field of the Email

bccstring[]Optional

Recipients mentioned in the BCC field of the Email

subjectstringOptional

Subject of the email

sent_atintegerOptional

Unix timestamp of when email was sent

thread_idstringOptional

ThreadID of the email

attachment_namestringOptional

Name of the attachment

attachment_typestringOptional

Type of attachment

fileNamestringOptional

The name of the file

mimeTypestringOptional

The file mime type

permalinkstringOptional

The link to the resource on the integration

policyUUIDsstring[]Optional

Policies violated

detectionRuleUUIDsstring[]Optional

Detection rules triggered

detectorUUIDsstring[]Optional

Detectors triggered

riskstring · enumOptional

The risk label associated to this violation

Possible values:

riskSourcestring · enumOptional

The source of calculation of risk associated to this violation

Possible values:

riskScorenumber · floatOptional

The calculated score of the risk for this violation

usernamestringOptional

Username as on the integration

userEmailstringOptional

User email as on the integration, may be empty

400

Invalid request parameters

application/json

401

Authentication failure

application/json

404

Violation does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/violations/{violationId}

Search violations

get

Fetch a list of violations based on some filters

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

createdAfterintegerOptional

Unix timestamp in seconds, filters records created ≥ the value, defaults to -90 days UTC

createdBeforeintegerOptional

Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC

updatedAfterintegerOptional

Unix timestamp in seconds, filters records updated > the value

limitinteger · max: 100Optional

The maximum number of records to be returned in the response

Default: 50

pageTokenstringOptional

Cursor for getting the next page of results

sortstring · enumOptional

Sort key and direction, defaults to descending order by creation time

Default: TIME_DESCPossible values:

querystringRequired

The query containing filter clauses

Search query language

Query structure and terminology

A query clause consists of a field followed by an operator followed by a value:

term	value
clause	user_email:"[email protected]"
field	user_email
operator	:
value	[email protected]

You can combine multiple query clauses in a search by separating them with a space.

Field types, substring matching, and numeric comparators

Every search field supports exact matching with a :. Certain fields such as user_email and user_name support substring matching.

Quotes

You may use quotation marks around string values. Quotation marks are required in case the value contains spaces. For example:

user_mail:[email protected]
user_name:"John Doe"

Special Characters

+ - && || ! ( ) { } [ ] ^ " ~ * ? : are special characters need to be escaped using \. For example:

a value like (1+1):2 should be searched for using \(1\+1)\:2

Search Syntax

The following table lists the syntax that you can use to construct a query.

SYNTAX	USAGE	DESCRIPTION	EXAMPLES
`:`	field:value	Exact match operator (case insensitive)	`state:"pending"` returns records where the currency is exactly `"PENDING"` in a case-insensitive comparison
(space)	field1:value1 field2:value2	The query returns only records that match both clauses	`state:active slack.channel_name:general`
`OR`	field:(value1 OR value2)	The query returns records that match either of the values (case insensitive)	`state:(active OR pending)`

Query Fields

param	description
state	the violation states to filter on
user_email	the emails of users updating the resource resulting in the violation
user_name	the usernames of users updating the resource resulting in the violation
integration_name	the integration to filter on
confidence	one or more likelihoods/confidences
policy_id	one or more policy IDs
detection_rule_id	one or more detection rule IDs
detector_id	one or more detector IDs
risk_label	the risk label to filter on
risk_source	the risk determination source to filter on
slack.channel_name	the slack channel names to filter on
slack.channel_id	the slack channel IDs to filter on
slack.workspace	the slack workspaces to filter on
confluence.parent_page_name	the names of the parent pages in confluence to filter on
confluence.space_name	the names of the spaces in confluence to filter on
gdrive.drive	the drive names in gdrive to filter on
jira.project_name	the jira project names to filter on
jira.ticket_number	the jira ticket numbers to filter on
salesforce.org_name	the salesforce organization names to filter on
salesforce.object	the salesforce object names to filter on
salesforce.record_id	the salesforce record IDs to filter on
github.author_email	the github author emails to filter on
github.branch	the github branches to filter on
github.commit	the github commit ids to filter on
github.org	the github organizations to filter on
github.repository	the github repositories to filter on
github.repository_owner	the github repository owners to filter on
teams.team_name	the m365 teams team names to filter on
teams.channel_name	the m365 teams channels to filter on
teams.channel_type	the m365 teams channel types to filter on
teams.team_sensitivity	the m365 teams sensitivities to filter on
teams.sender	the m365 teams senders to filter on
teams.msg_importance	the m365 teams importance to filter on
teams.msg_attachment	the m365 teams attachment names to filter on
teams.chat_id	the m365 teams chat ID to filter on
teams.chat_type	the m365 teams chat type to filter on
teams.chat_topic	the m365 teams chat topic to filter on
teams.chat_participant	the m365 teams chat participant's display name to filter on
onedrive.drive_owner	drive owner's display name to filter on
onedrive.drive_owner_email	drive owner's email to filter on
onedrive.file_name	the file name to filter on
onedrive.created_by	the m365 user, who created the file in the drive, display name to filter on
onedrive.created_by_email	the m365 users, who created the file in the drive, email to filter on
onedrive.modified_by	the m365 users, who last modified the file in the drive, display name to filter on
onedrive.modified_by_email	the m365 users, who last modified the file in the drive, email to filter on
zendesk.ticket_status	the zendesk ticket status to filter on
zendesk.ticket_title	the zendesk ticket titles to filter on
zendesk.ticket_group_assignee	the zendesk ticket assignee groups to filter on
zendesk.current_user_role	the zendesk ticket current assignee user's roles to filter on
notion.created_by	the names of the users creating a resource in notion to filter on
notion.last_edited_by	the names of the users editing a resource in notion to filter on
notion.page_title	the page names in notion to filter on
notion.workspace_name	the workspace names in notion to filter on
gmail.user_name	the names of the sender to filter on
gmail.from	the email of sender to filter on
gmail.to	the email or name of recipients to filter on
gmail.cc	the email or name of cc to filter on
gmail.bcc	the email or name of bcc to filter on
gmail.thread_id	the thread id of email to filter on
gmail.subject	the subject of email to filter on
gmail.attachment_name	the name of attachment to filter on
gmail.attachment_type	the type of attachment to filter on
last_actioned_by	the entity that performed the last action on the violation, can be one of NIGHTFALL, ADMIN or END_USER

Responses

200

Successful response

application/json

X-Rate-Limit-RemainingintegerOptional

How many remaining requests you can make within the next second before being throttled

X-Quota-RemainingintegerOptional

How many remaining requests you can make within the next quota period

X-Quota-Period-Endstring · date-timeOptional

When the current quota period expires

idstringOptional

The violation id

integrationstring · enumOptional

The integration name

Possible values:

createdAtintegerOptional

Unix timestamp when the violation was created

updatedAtintegerOptional

Unix timestamp when the violation was updated

itemsstring · enumOptionalPossible values:

statestring · enumOptional

The current state of the violation

Possible values:

resourceLinkstringOptional

The link to the resource on the integration

locationstringOptional

The channel name in case of a message in a channel

locationTypestringOptional

Type of location

usernamestringOptional

User name

userIDstringOptional

ID - user

messagePermalinkstringOptional

Link to message

locationMembersstring[]Optional

Members for the location

locationMemberCountintegerOptional

Count of members for the location

channelIDstringOptional

ID - channel

workspaceNamestringOptional

Name of workspace

itemNamestringOptional

Name of item

itemTypestringOptional

Type of item

isArchivedbooleanOptional

Archived status

createdAtintegerOptional

Unix timestamp

updatedAtintegerOptional

Unix timestamp

labelsstring[]Optional

List of labels

spaceNamestringOptional

Name of space

spaceKeystringOptional

Key of space

spaceNameLinkstringOptional

Link of space

parentPageNamestringOptional

Parent page

authorNamestringOptional

Name of author

authorEmailstringOptional

Email of author

authorNameLinkstringOptional

Link of author name

permalinkstringOptional

Link to resource

confluenceIDstringOptional

ID - Confluence internal

confluenceUserIDstringOptional

ID - Confluence user

itemVersionintegerOptional

Version of item

parentPageIDstringOptional

ID - parent page

parentVersionintegerOptional

Version of parent page

fileIDstringOptional

ID of file

fileNamestringOptional

The name of the file

fileTypestringOptional

Type of file

fileSizestringOptional

File size

fileLinkstringOptional

Link to file

permissionSettingstringOptional

Permissions

sharingExternalUsersstring[]Optional

User list shared with - external

sharingInternalUsersstring[]Optional

User list shared with - internal

canViewersDownloadbooleanOptional

Available for viewers to download

fileOwnerstringOptional

File owner

isInTrashbooleanOptional

In trash

createdAtintegerOptional

Unix timestamp, when the file was created

updatedAtintegerOptional

Unix timestamp, when the file was updated

drivestringOptional

Drive name

updatedBystringOptional

Updated by user

projectNamestringOptional

Name of project

ticketNumberstringOptional

Ticket number

projectTypestringOptional

Type of project

issueIDstringOptional

ID for the issue

projectLinkstringOptional

Link to project

ticketLinkstringOptional

Link to ticket

commentLinkstringOptional

Link to comment

attachmentLinkstringOptional

Link to attachment

branchNamestringOptional

Branch on which violation occurred

organizationstringOptional

Name of the organization or username in case of an individual account

repositorystringOptional

Name of the repository

authorEmailstringOptional

Email of the user who pushed the changes to GitHub

authorUsernamestringOptional

Username of the user who pushed the changes to GitHub

createdAtintegerOptional

Unix timestamp

isRepoPrivatebooleanOptional

Boolean to check if the repo is private or public

filePathstringOptional

Path of the file on which violation occurred

githubPermalinkstringOptional

Permalink to the version of the file where sensitive content was identified

repositoryOwnerstringOptional

Owner of the repository

githubRepoLinkstringOptional

Link to the repository

orgNamestringOptional

Name of the Salesforce organization

recordIDstringOptional

ID of the record

objectNamestringOptional

Name of the object

contentTypestringOptional

Attachment or Object

userIDstringOptional

ID of the user

userNamestringOptional

Salesforce username of the author

updatedAtintegerOptional

Unix timestamp when the object was last updated

fieldsstring[]Optional

Fields of the Object

fileTypestringOptional

File Type

attachmentLinkstringOptional

Link to the attachment

attachmentNamestringOptional

Name of the attachment

objectLinkstringOptional

Link to the object

ticketStatusstringOptional

Status of the ticket

ticketTitlestringOptional

Title of the ticket

ticketRequestorstringOptional

Ticket requested by

ticketGroupAssigneestringOptional

Group the ticket is assigned to

ticketAgentAssigneestringOptional

Agent the ticket is assigned to

currentUserRolestringOptional

User role

ticketIDintegerOptional

ID of the ticket

ticketFollowersstring[]Optional

Followers of the ticket

ticketTagsstringOptional

Tags for the ticket

createdAtintegerOptional

Unix timestamp

UpdatedAtintegerOptional

Unix timestamp

locationstringOptional

Location

subLocationstringOptional

Sub-location

ticketCommentIDintegerOptional

ID - ticket comment

ticketGroupIDintegerOptional

ID - ticket group

ticketGroupLinkstringOptional

Link to the ticket group

ticketAgentIDintegerOptional

ID - ticket agent

ticketAgentLinkstringOptional

Link - ticket agent

ticketEventstringOptional

Ticket event

userRolestringOptional

Role of the user

attachmentNamestringOptional

Name of the attachment

attachmentLinkstringOptional

Link for the attachment

createdBystringOptional

Page creator

updatedBystringOptional

Page update by

workspaceNamestringOptional

Workspace name

workspaceLinkstringOptional

Link to workspace

pageIDstringOptional

ID of the page

pageTitlestringOptional

Title of the page

createdAtintegerOptional

Unix timestamp

updatedAtintegerOptional

Unix timestamp

privatePageLinkstringOptional

Private page link

publicPageLinkstringOptional

Public page link

sharedExternallybooleanOptional

Externally shared state

attachmentIDstringOptional

ID of the attachment

locationstringOptional

Page URL where the extension is launched

subLocationstringOptional

Specific location on the page

browserNamestringOptional

Browser type

userCommentstringOptional

Remediation comment from the user

teamNamestringOptional

Name of the team containing the channel where the message was sent

tenantIDstringOptional

ID of the tenant

tenantDomainstringOptional

Domain name of the tenant

teamIDstringOptional

ID of the team containing the channel where the message was sent

teamVisibilitystringOptional

Visibility of the team containing the channel where the message was sent

teamWebURLstringOptional

Web URL of the team containing the channel where the message was sent

channelIDstringOptional

ID of the channel where the message was sent

channelNamestringOptional

Name of the channel where the message was sent

channelTypestringOptional

Type of the channel where the message was sent

channelWebURLstringOptional

Web URL of the channel where the message was sent

messageIDstringOptional

ID of the message

createdAtintegerOptional

Unix timestamp

updatedAtintegerOptional

Unix timestamp

chatMessageSenderstringOptional

Sender of the chat message

userIDstringOptional

ID of the user who sent the message

userPrincipalNamestringOptional

Principal name of the user who sent the message

attachmentIDstringOptional

ID of the attachment present in the message

attachmentNamestringOptional

Name of the attachment present in the message

attachmentURLstringOptional

URL of the attachment present in the message

chatMessageImportancestringOptional

Importance of the sent message

chatIDstringOptional

ID of the chat conversation

chatTypestringOptional

Type of the chat conversation (one-on-one, group, meeting)

chatTopicstringOptional

Topic or subject of the chat conversation

userIDstringOptional

ID of the user participating in the chat conversation

emailstringOptional

email address of the chat participant

displayNamestringOptional

display name of the chat participant

tenantIDstringOptional

ID of the tenant

tenantDomainstringOptional

Domain name of the tenant

driveItemIDstringOptional

ID of the drive item

driveItemNamestringOptional

Name of the drive item

driveItemURLstringOptional

URL of the drive item

driveItemMimeTypestringOptional

Mime type of the drive item

driveItemSizeintegerOptional

Size of the drive item in bytes

parentPathstringOptional

Path to the drive item relative to the root of the drive

createdByIDstringOptional

ID of the user who created the drive item

updatedByEmailstringOptional

Email of the user who last updated the drive item

updatedByIDstringOptional

ID of the user who last updated the drive item

updatedByNamestringOptional

Name of the user who last updated the drive item

createdAtintegerOptional

Unix timestamp when the drive item was created

updatedAtintegerOptional

Unix timestamp when the drive item was last updated

specialFolderNamestringOptional

Name of the special folder if drive item is inside one

driveIDstringOptional

ID of the drive where the drive item is present

driveOwnerNamestringOptional

Name of user who owns the drive where the drive item is present

driveOwnerEmailstringOptional

Email of user who owns the drive where the drive item is present

driveOwnerIDstringOptional

ID of user who owns the drive where the drive item is present

domainstringOptional

Domain of the company where email was sent from

user_namestringOptional

User Name who sent the email

fromstringOptional

Email of the sender

tostring[]Optional

Recipients of the Email

ccstring[]Optional

Recipients mentioned in the CC field of the Email

bccstring[]Optional

Recipients mentioned in the BCC field of the Email

subjectstringOptional

Subject of the email

sent_atintegerOptional

Unix timestamp of when email was sent

thread_idstringOptional

ThreadID of the email

attachment_namestringOptional

Name of the attachment

attachment_typestringOptional

Type of attachment

fileNamestringOptional

The name of the file

mimeTypestringOptional

The file mime type

permalinkstringOptional

The link to the resource on the integration

policyUUIDsstring[]Optional

Policies violated

detectionRuleUUIDsstring[]Optional

Detection rules triggered

detectorUUIDsstring[]Optional

Detectors triggered

riskstring · enumOptional

The risk label associated to this violation

Possible values:

riskSourcestring · enumOptional

The source of calculation of risk associated to this violation

Possible values:

riskScorenumber · floatOptional

The calculated score of the risk for this violation

usernamestringOptional

Username as on the integration

userEmailstringOptional

User email as on the integration, may be empty

nextPageTokenstringOptional

Next page cursor, omitted if end of results reached

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/violations/search

The request body of the /v3/scan endpoint

policyUUIDsstring[]Optional

A list of UUIDs referring to policies to use to scan the request payload. Policies can be built in the Nightfall Dashboard. Maximum 1.

detectionRuleUUIDsstring[]Optional

A list of UUIDs referring to detection rules to use to scan the request payload. Detection rules can be built in the Nightfall dashboard. Maximum 20.

namestringOptional

An optional name for the detection rule.

logicalOpstring · enumOptional

Supported values ALL or ANY. Applies a logical "AND" or "OR" (respectively) to the list of detectors to decide when a finding should be surfaced.

Possible values:

minNumFindingsintegerOptional

The minimum number of findings required in order for this detector to be reported.

minConfidencestring · enumOptional

The confidence level of a finding.

Possible values:

detectorUUIDstringOptional

The UUID of a pre-existing detector to use. If this value is provided, all below fields are ignored.

displayNamestringOptional

The display name for this detector's findings in the response.

detectorTypestring · enumOptional

The type of detector.

Possible values:

nightfallDetectorstring · enumOptional

The name for a Nightfall detector.

Possible values:

patternstringOptional

The regex pattern to match on.

isCaseSensitivebooleanOptional

The case sensitivity for the regex pattern.

valuesstring[]Optional

A list of words for wordList.

isCaseSensitivebooleanOptional

The case sensitivity for words in the wordList. If false, ignore the case of findings.

patternstringOptional

The regex pattern to match on.

isCaseSensitivebooleanOptional

The case sensitivity for the regex pattern.

windowBeforeintegerOptional

The number of leading characters to include as context before the finding itself.

windowAfterintegerOptional

The number of trailing characters to include as context after the finding itself.

fixedConfidencestring · enumOptional

The confidence level of a finding.

Possible values:

matchTypestring · enumOptional

The type of match for a pattern.

Possible values:

exclusionTypestring · enumOptional

The type of exclusion rule.

Possible values:

patternstringOptional

The regex pattern to match on.

isCaseSensitivebooleanOptional

The case sensitivity for the regex pattern.

valuesstring[]Optional

A list of words for wordList.

isCaseSensitivebooleanOptional

The case sensitivity for words in the wordList. If false, ignore the case of findings.

maskingCharstring · min: 1 · max: 1Optional

The UTF-8 character used to mask a finding. If not provided, we will mask with an asterisk "*". Other examples include "#", "X", "🙅🏽", "🙈", etc.

charsToIgnorestring[] · max: 100Optional

A list of characters that will not be masked. For example, you could set this field to ["-","@"] to preserve formatting context that is typically present in credit cards or emails (e.g. --- versus *********, or ***************** versus @).

numCharsToLeaveUnmaskedinteger · max: 1000Optional

The number of characters that will be left unmasked. For instance, if you want to mask all but the last 4 digits of a credit card number, set this value to 4 so that the redacted finding would look like ***************4242.

maskLeftToRightbooleanOptional

Determines if masking is applied left to right (/1984) instead of right to left (01/01). By default, this value is false.

infoTypeSubstitutionConfigobject · nullableOptional

A config that substitutes a sensitive finding with the name of the NIGHTFALL_DETECTOR that triggered it. This config is only valid for detector's with detectorType NIGHTFALL_DETECTOR. e.g. '4242-4242-4242-4242' can be configured to be redacted to '[CREDIT_CARD_NUMBER]'.

substitutionPhrasestring · max: 1000Optional

The value that will replace a sensitive finding. e.g. '<oh no!🙈>'

publicKeystringOptional

The PEM formatted public key block that will be used to encrypt findings. Currently, only RSA encryption is supported.

Here's an example PEM formatted public key block:

removeFindingbooleanOptional

Determines if the response object will contain the un-redacted sensitive finding that was triggered by the scan. Defaults to false.

scopestring · enumOptional

The scope to run the detector over. Setting any detector to File will cause it to run against the file name.

Possible values:

contextBytesintegerOptional

The number of bytes to include as before / after context when a finding is returned. Maximum 40.

maskingCharstring · min: 1 · max: 1Optional

The UTF-8 character used to mask a finding. If not provided, we will mask with an asterisk "*". Other examples include "#", "X", "🙅🏽", "🙈", etc.

charsToIgnorestring[] · max: 100Optional

numCharsToLeaveUnmaskedinteger · max: 1000Optional

maskLeftToRightbooleanOptional

Determines if masking is applied left to right (/1984) instead of right to left (01/01). By default, this value is false.

infoTypeSubstitutionConfigobject · nullableOptional

substitutionPhrasestring · max: 1000Optional

The value that will replace a sensitive finding. e.g. '<oh no!🙈>'

publicKeystringOptional

The PEM formatted public key block that will be used to encrypt findings. Currently, only RSA encryption is supported.

Here's an example PEM formatted public key block:

removeFindingbooleanOptional

Determines if the response object will contain the un-redacted sensitive finding that was triggered by the scan. Defaults to false.

targetstringOptional

The name of the Slack conversation to which alerts should be sent. Currently, Nightfall supports sending alerts to public channels, formatted like "#general".

addressstringOptional

The email address to which alerts should be sent.

addressstringOptional

The URL to which alerts should be sent. This URL must (1) use the HTTPS scheme, (2) be able to accept requests made with the POST verb, and (3) respond with a 200 status code upon receipt of the event.

addressstringOptional

Other propertiesstringOptional

payloadstring[]Optional

The text sample(s) you wish to scan. This data is passed as a string list, so you may choose to segment your text into multiple items for better granularity. The aggregate size of your text (summed across all items in the list) must not exceed 500 KB for any individual request, and the number of items in that list may not exceed 50,000.

policyUUIDstring · uuidOptional

the UUID of the Detection Policy to be used with this scan. Exactly one of this field or "policy" should be provided.

webhookURLstringOptionalDeprecated

the URL that Nightfall shall deliver webhooks to when the scan completes. The URL must use the HTTPS scheme. This field has been deprecated in favor of the more general 'alertConfig'.

detectionRuleUUIDsstring · uuid[]Optional

A list of pre-existing detection rule UUIDs to scan a file against. These UUIDs can be fetched from the Nightfall Dashboard.

namestringOptional

An optional name for the detection rule.

logicalOpstring · enumOptional

Supported values ALL or ANY. Applies a logical "AND" or "OR" (respectively) to the list of detectors to decide when a finding should be surfaced.

Possible values:

minNumFindingsintegerOptional

The minimum number of findings required in order for this detector to be reported.

minConfidencestring · enumOptional

The confidence level of a finding.

Possible values:

detectorUUIDstringOptional

The UUID of a pre-existing detector to use. If this value is provided, all below fields are ignored.

displayNamestringOptional

The display name for this detector's findings in the response.

detectorTypestring · enumOptional

The type of detector.

Possible values:

nightfallDetectorstring · enumOptional

The name for a Nightfall detector.

Possible values:

patternstringOptional

The regex pattern to match on.

isCaseSensitivebooleanOptional

The case sensitivity for the regex pattern.

valuesstring[]Optional

A list of words for wordList.

isCaseSensitivebooleanOptional

The case sensitivity for words in the wordList. If false, ignore the case of findings.

patternstringOptional

The regex pattern to match on.

isCaseSensitivebooleanOptional

The case sensitivity for the regex pattern.

windowBeforeintegerOptional

The number of leading characters to include as context before the finding itself.

windowAfterintegerOptional

The number of trailing characters to include as context after the finding itself.

fixedConfidencestring · enumOptional

The confidence level of a finding.

Possible values:

matchTypestring · enumOptional

The type of match for a pattern.

Possible values:

exclusionTypestring · enumOptional

The type of exclusion rule.

Possible values:

patternstringOptional

The regex pattern to match on.

isCaseSensitivebooleanOptional

The case sensitivity for the regex pattern.

valuesstring[]Optional

A list of words for wordList.

isCaseSensitivebooleanOptional

The case sensitivity for words in the wordList. If false, ignore the case of findings.

maskingCharstring · min: 1 · max: 1Optional

The UTF-8 character used to mask a finding. If not provided, we will mask with an asterisk "*". Other examples include "#", "X", "🙅🏽", "🙈", etc.

charsToIgnorestring[] · max: 100Optional

numCharsToLeaveUnmaskedinteger · max: 1000Optional

maskLeftToRightbooleanOptional

Determines if masking is applied left to right (/1984) instead of right to left (01/01). By default, this value is false.

infoTypeSubstitutionConfigobject · nullableOptional

substitutionPhrasestring · max: 1000Optional

The value that will replace a sensitive finding. e.g. '<oh no!🙈>'

publicKeystringOptional

The PEM formatted public key block that will be used to encrypt findings. Currently, only RSA encryption is supported.

Here's an example PEM formatted public key block:

removeFindingbooleanOptional

Determines if the response object will contain the un-redacted sensitive finding that was triggered by the scan. Defaults to false.

scopestring · enumOptional

The scope to run the detector over. Setting any detector to File will cause it to run against the file name.

Possible values:

targetstringOptional

The name of the Slack conversation to which alerts should be sent. Currently, Nightfall supports sending alerts to public channels, formatted like "#general".

addressstringOptional

The email address to which alerts should be sent.

addressstringOptional

Other propertiesstringOptional

maskingCharstring · min: 1 · max: 1Optional

The UTF-8 character used to mask a finding. If not provided, we will mask with an asterisk "*". Other examples include "#", "X", "🙅🏽", "🙈", etc.

charsToIgnorestring[] · max: 100Optional

numCharsToLeaveUnmaskedinteger · max: 1000Optional

maskLeftToRightbooleanOptional

Determines if masking is applied left to right (/1984) instead of right to left (01/01). By default, this value is false.

infoTypeSubstitutionConfigobject · nullableOptional

substitutionPhrasestring · max: 1000Optional

The value that will replace a sensitive finding. e.g. '<oh no!🙈>'

publicKeystringOptional

The PEM formatted public key block that will be used to encrypt findings. Currently, only RSA encryption is supported.

Here's an example PEM formatted public key block:

removeFindingbooleanOptional

Determines if the response object will contain the un-redacted sensitive finding that was triggered by the scan. Defaults to false.

enableFileRedactionbooleanOptional

Determines if a redacted version of the file will be returned, if available for the mime type. Current supported mime types are CSV and TSV. Defaults to false.

requestMetadatastringOptional

A string containing arbitrary metadata. Callers may opt to use this to help identify their input file upon receiving a webhook response. Maximum length 10 KB.

Search posture events

get

Fetch a list of posture events based on some filters

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

createdAfterintegerOptional

Unix timestamp in seconds, filters records created ≥ the value, defaults to -180 days UTC

createdBeforeintegerOptional

Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC

updatedAfterintegerOptional

Unix timestamp in seconds, filters records updated > the value

limitinteger · max: 100Optional

The maximum number of records to be returned in the response

Default: 50

pageTokenstringOptional

Cursor for getting the next page of results

sortstring · enumOptional

Sort key and direction, defaults to descending order by creation time

Default: TIME_DESCPossible values:

querystringRequired

The query containing filter clauses

Search query language

Query structure and terminology

A query clause consists of a field followed by an operator followed by a value:

term	value
clause	user_email:"[email protected]"
field	user_email
operator	:
value	[email protected]

You can combine multiple query clauses in a search by separating them with a space.

Field types, substring matching, and numeric comparators

Every search field supports exact matching with a :. Certain fields such as user_email and user_name support substring matching.

Quotes

You may use quotation marks around string values. Quotation marks are required in case the value contains spaces. For example:

user_mail:[email protected]
user_name:"John Doe"

Special Characters

+ - && || ! ( ) { } [ ] ^ " ~ * ? : are special characters need to be escaped using \. For example:

a value like (1+1):2 should be searched for using \(1\+1)\:2

Search Syntax

The following table lists the syntax that you can use to construct a query.

SYNTAX	USAGE	DESCRIPTION	EXAMPLES
`:`	field:value	Exact match operator (case insensitive)	`state:"pending"` returns records where the currency is exactly `"PENDING"` in a case-insensitive comparison
(space)	field1:value1 field2:value2	The query returns only records that match both clauses	`state:active slack.channel_name:general`
`OR`	field:(value1 OR value2)	The query returns records that match either of the values (case insensitive)	`state:(active OR pending)`

Query Fields

param	description
event_id	the unique identifier of the posture event to filter on
integration_name	the name of the integration to filter on
state	the state of the event to filter on (active, pending, resolved, expired)
event_type	the type of posture event to filter on
actor_name	the name of the actor who performed the action to filter on
actor_email	the email of the actor who performed the action to filter on
user_name	the username of the user to filter on (backward compatibility)
user_email	the email of the user to filter on (backward compatibility)
notes	the comment or notes associated with the event to filter on
policy_id	the unique identifier of the policy to filter on
policy_name	the name of the policy to filter on
resource_id	the identifier of the resource to filter on
resource_name	the name of the resource to filter on
resource_owner_name	the name of the resource owner to filter on
resource_owner_email	the email of the resource owner to filter on
resource_content_type	the content type of the resource to filter on
endpoint.device_id	the device identifier for endpoint events to filter on
endpoint.machine_name	the machine name for endpoint events to filter on
gdrive.permission	the permission setting for Google Drive files to filter on
gdrive.shared_internal_email	the internal emails with which the file is shared to filter on
gdrive.shared_external_email	the external emails with which the file is shared to filter on
gdrive.drive	the Google Drive name to filter on
gdrive.file_owner	the owner of the Google Drive file to filter on
gdrive.label_name	the label name applied to Google Drive files to filter on
salesforce.report.scope	the scope of the Salesforce report to filter on
salesforce.report.event_source	the event source of the Salesforce report to filter on
salesforce.report.source_ip	the source IP address of the Salesforce report to filter on
salesforce.report.session_level	the session level of the Salesforce report to filter on
salesforce.report.operation	the operation type of the Salesforce report to filter on
salesforce.report.description	the description of the Salesforce report to filter on
salesforce.file.source_ip	the source IP address for Salesforce file events to filter on
salesforce.file.session_level	the session level for Salesforce file events to filter on

Responses

200

Successful response

application/json

X-Rate-Limit-RemainingintegerOptional

How many remaining requests you can make within the next second before being throttled

X-Quota-RemainingintegerOptional

How many remaining requests you can make within the next quota period

X-Quota-Period-Endstring · date-timeOptional

When the current quota period expires

idstring · uuidOptional

Unique identifier for the posture event

integrationstringOptional

Integration type that generated the event (e.g., GDRIVE, ES_WINDOWS, ES_MAC)

createdAtintegerOptional

Unix timestamp in seconds indicating when the event was created

statestringOptional

Current state of the event (e.g., ACTIVE, RESOLVED, EXPIRED, PENDING)

eventTypestringOptional

Type of exfiltration event (e.g., PERMISSION_CHANGE, ADD_EXTERNAL_USER)

policyUUIDsstring · uuid[]Optional

List of policy UUIDs that triggered the event

assetsCountintegerOptional

Number of assets involved in the posture event

usernamestringOptional

Username of the associated user

userEmailstring · emailOptional

Email of the associated user

userProfileLinkstring · uriOptional

Link to the user's profile

deviceIdstringOptional

Device identifier for endpoint events

machineNamestringOptional

Machine name for endpoint events

isExternalbooleanOptional

Whether the user is external to the organization

idstringOptional

Identifier of the application

namestringOptional

Name of the application

nextPageTokenstringOptional

Next page cursor, omitted if end of results reached

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/events/search

Fetch posture event details

get

Fetch an posture event details by ID

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

eventIdstring · uuidRequired

The UUID of the event to fetch

Responses

200

Successful response

application/json

X-Rate-Limit-RemainingintegerOptional

How many remaining requests you can make within the next second before being throttled

X-Quota-RemainingintegerOptional

How many remaining requests you can make within the next quota period

X-Quota-Period-Endstring · date-timeOptional

When the current quota period expires

idstringOptional

Unique identifier for the asset

namestringOptional

Name of the asset

pathstringOptional

Path to the asset

sizeBytesintegerOptional

Size of the asset in bytes

mimetypestringOptional

MIME type of the asset

idstringOptional

Unique identifier for the actor in Nightfall

emailstring · emailOptional

Email of the actor

commentstringOptional

Comment or notes associated with the event

userBelongsToGroupsstring[]Optional

Groups the user belongs to

isAdminbooleanOptional

Whether the user is an admin

isSuspendedbooleanOptional

Whether the user is suspended

createdAtinteger · nullableOptional

Timestamp when the user was created

salesforceobjectOptional

Salesforce user metadata (currently empty as per spec)

commentstringOptional

Comment or notes associated with the asset

ddrViolationIDsarrayOptional

array to strings to DDR violations ids associated with the resource

fileIDstringOptional

ID of the file

fileNamestringOptional

Name of the file

fileSizestringOptional

Size of the file

fileLinkstringOptional

Link to the file

permissionSettingstringOptional

Permission setting for the file

sharingExternalUsersstring[]Optional

External users with whom the file is shared

sharingInternalUsersstring[]Optional

Internal users with whom the file is shared

canViewersDownloadbooleanOptional

Whether viewers can download the file

fileOwnerstringOptional

Owner of the file

isInTrashbooleanOptional

Whether the file is in trash

createdAtinteger · nullableOptional

Timestamp when the file was created

updatedAtinteger · nullableOptional

Timestamp when the file was last updated

drivestringOptional

Drive where the file is located

labelsstring[]Optional

Labels associated with the file

filePermissionTypestringOptional

Type of file permission

resourceTypestringOptional

Type of Salesforce resource

fileActionstringOptional

Action performed on the file

sourceIPstringOptional

Source IP address

sessionLevelstringOptional

Level of the session

descriptionstringOptional

Description of the report

displayEntityFieldsstring[]Optional

Entity fields displayed in the report

dashboardNamestringOptional

Name of the dashboard

scopestringOptional

Scope of the report

operationstringOptional

Operation performed

recordCountinteger · int64Optional

Number of records

queriedEntitiesstring[]Optional

Entities queried in the report

groupedColumnHeadersstring[]Optional

Grouped column headers

columnCountinteger · int64Optional

Number of columns

processedRowCountinteger · int64Optional

Number of rows processed

sourceIPstringOptional

Source IP address

eventSourcestringOptional

Source of the event

sessionLevelstringOptional

Level of the session

querystringOptional

Query executed

eventIdentifierstringOptional

Identifier of the event

sourceIPstringOptional

Source IP address

sessionKeystringOptional

Key of the session

sessionLevelstringOptional

Level of the session

idstringOptional

Unique identifier for the actor in Nightfall

emailstring · emailOptional

Email of the actor

commentstringOptional

Comment or notes associated with the event

userBelongsToGroupsstring[]Optional

Groups the user belongs to

isAdminbooleanOptional

Whether the user is an admin

isSuspendedbooleanOptional

Whether the user is suspended

createdAtinteger · nullableOptional

Timestamp when the user was created

salesforceobjectOptional

Salesforce user metadata (currently empty as per spec)

typestring · enumOptional

Type of the event

Possible values:

timestampintegerOptional

Timestamp of the event

originatingAppIdstringOptional

ID of the originating app

originatingAppNamestringOptional

Name of the originating app

isClientSyncEventbooleanOptional

Whether this is a client sync event

sourceIPstringOptional

Source IP address

sessionLevelstringOptional

Level of the session

sessionKeystringOptional

Key of the session

sfUserIdstringOptional

Salesforce user ID

assetIDsarrayOptional

array to string with asset IDs associated with the event

400

Invalid request parameters

application/json

401

Authentication failure

application/json

404

Event does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/events/{eventId}

Search exfiltration events

get

Fetch a list of exfiltration events based on some filters

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

createdAfterintegerOptional

Unix timestamp in seconds, filters records created ≥ the value, defaults to -180 days UTC

createdBeforeintegerOptional

Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC

updatedAfterintegerOptional

Unix timestamp in seconds, filters records updated > the value

limitinteger · max: 100Optional

The maximum number of records to be returned in the response

Default: 50

pageTokenstringOptional

Cursor for getting the next page of results

sortstring · enumOptional

Sort key and direction, defaults to descending order by creation time

Default: TIME_DESCPossible values:

querystringRequired

The query containing filter clauses

Search query language

Query structure and terminology

A query clause consists of a field followed by an operator followed by a value:

term	value
clause	user_email:"[email protected]"
field	user_email
operator	:
value	[email protected]

You can combine multiple query clauses in a search by separating them with a space.

Field types, substring matching, and numeric comparators

Every search field supports exact matching with a :. Certain fields such as user_email and user_name support substring matching.

Quotes

You may use quotation marks around string values. Quotation marks are required in case the value contains spaces. For example:

user_mail:[email protected]
user_name:"John Doe"

Special Characters

+ - && || ! ( ) { } [ ] ^ " ~ * ? : are special characters need to be escaped using \. For example:

a value like (1+1):2 should be searched for using \(1\+1)\:2

Search Syntax

The following table lists the syntax that you can use to construct a query.

SYNTAX	USAGE	DESCRIPTION	EXAMPLES
`:`	field:value	Exact match operator (case insensitive)	`state:"pending"` returns records where the currency is exactly `"PENDING"` in a case-insensitive comparison
(space)	field1:value1 field2:value2	The query returns only records that match both clauses	`state:active slack.channel_name:general`
`OR`	field:(value1 OR value2)	The query returns records that match either of the values (case insensitive)	`state:(active OR pending)`

Query Fields

param	description
event_id	the unique identifier of the exfiltration event to filter on
integration_name	the name of the integration to filter on
state	the state of the event to filter on (active, pending, resolved, expired)
event_type	the type of exfiltration event to filter on
actor_name	the name of the actor who performed the action to filter on
actor_email	the email of the actor who performed the action to filter on
user_name	the username of the user to filter on (backward compatibility)
user_email	the email of the user to filter on (backward compatibility)
notes	the comment or notes associated with the event to filter on
policy_id	the unique identifier of the policy to filter on
policy_name	the name of the policy to filter on
resource_id	the identifier of the resource to filter on
resource_name	the name of the resource to filter on
resource_owner_name	the name of the resource owner to filter on
resource_owner_email	the email of the resource owner to filter on
resource_content_type	the content type of the resource to filter on
endpoint.device_id	the device identifier for endpoint events to filter on
endpoint.machine_name	the machine name for endpoint events to filter on
gdrive.permission	the permission setting for Google Drive files to filter on
gdrive.shared_internal_email	the internal emails with which the file is shared to filter on
gdrive.shared_external_email	the external emails with which the file is shared to filter on
gdrive.drive	the Google Drive name to filter on
gdrive.file_owner	the owner of the Google Drive file to filter on
gdrive.label_name	the label name applied to Google Drive files to filter on
salesforce.report.scope	the scope of the Salesforce report to filter on
salesforce.report.event_source	the event source of the Salesforce report to filter on
salesforce.report.source_ip	the source IP address of the Salesforce report to filter on
salesforce.report.session_level	the session level of the Salesforce report to filter on
salesforce.report.operation	the operation type of the Salesforce report to filter on
salesforce.report.description	the description of the Salesforce report to filter on
salesforce.file.source_ip	the source IP address for Salesforce file events to filter on
salesforce.file.session_level	the session level for Salesforce file events to filter on
last_actioned_by	the entity that performed the last action on the violation, can be one of NIGHTFALL, ADMIN or END_USER

Responses

200

Successful response

application/json

X-Rate-Limit-RemainingintegerOptional

How many remaining requests you can make within the next second before being throttled

X-Quota-RemainingintegerOptional

How many remaining requests you can make within the next quota period

X-Quota-Period-Endstring · date-timeOptional

When the current quota period expires

idstring · uuidOptional

Unique identifier for the exfiltration event

integrationstringOptional

Integration type that generated the event (e.g., GDRIVE, ES_WINDOWS, ES_MAC)

createdAtintegerOptional

Unix timestamp in seconds indicating when the event was created

statestringOptional

Current state of the event (e.g., ACTIVE, RESOLVED, EXPIRED, PENDING)

eventTypestringOptional

Type of exfiltration event (e.g., DOWNLOAD, ENDPOINTDLP_BROWSER_UPLOAD)

policyUUIDsstring · uuid[]Optional

List of policy UUIDs that triggered the event

assetsCountintegerOptional

Number of assets involved in the exfiltration event

usernamestringOptional

Username of the associated user

userEmailstring · emailOptional

Email of the associated user

userProfileLinkstring · uriOptional

Link to the user's profile

deviceIdstringOptional

Device identifier for endpoint events

machineNamestringOptional

Machine name for endpoint events

isExternalbooleanOptional

Whether the user is external to the organization

idstringOptional

Identifier of the application

namestringOptional

Name of the application

nextPageTokenstringOptional

Next page cursor, omitted if end of results reached

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/events/search

Fetch exfiltration event details

get

Fetch an exfiltration event details by ID

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

eventIdstring · uuidRequired

The UUID of the event to fetch

Responses

200

Successful response

application/json

X-Rate-Limit-RemainingintegerOptional

How many remaining requests you can make within the next second before being throttled

X-Quota-RemainingintegerOptional

How many remaining requests you can make within the next quota period

X-Quota-Period-Endstring · date-timeOptional

When the current quota period expires

idstringOptional

Unique identifier for the asset

namestringOptional

Name of the asset

pathstringOptional

Path to the asset

sizeBytesintegerOptional

Size of the asset in bytes

mimetypestringOptional

MIME type of the asset

idstringOptional

Unique identifier for the actor in Nightfall

emailstring · emailOptional

Email of the actor

commentstringOptional

Comment or notes associated with the event

userBelongsToGroupsstring[]Optional

Groups the user belongs to

isAdminbooleanOptional

Whether the user is an admin

isSuspendedbooleanOptional

Whether the user is suspended

createdAtinteger · nullableOptional

Timestamp when the user was created

salesforceobjectOptional

Salesforce user metadata (currently empty as per spec)

deviceIDstringOptional

ID of the device

machineNamestringOptional

Name of the machine/device

commentstringOptional

Comment or notes associated with the asset

ddrViolationIDsstring · uuid[]Optional

DDR violations IDs associated with the resource

fileIDstringOptional

ID of the file

fileNamestringOptional

Name of the file

fileSizestringOptional

Size of the file

fileLinkstringOptional

Link to the file

permissionSettingstringOptional

Permission setting for the file

sharingExternalUsersstring[]Optional

External users with whom the file is shared

sharingInternalUsersstring[]Optional

Internal users with whom the file is shared

canViewersDownloadbooleanOptional

Whether viewers can download the file

fileOwnerstringOptional

Owner of the file

isInTrashbooleanOptional

Whether the file is in trash

createdAtinteger · nullableOptional

Timestamp when the file was created

updatedAtinteger · nullableOptional

Timestamp when the file was last updated

drivestringOptional

Drive where the file is located

labelsstring[]Optional

Labels associated with the file

filePermissionTypestringOptional

Type of file permission

resourceTypestringOptional

Type of Salesforce resource

fileActionstringOptional

Action performed on the file

sourceIPstringOptional

Source IP address

sessionLevelstringOptional

Level of the session

descriptionstringOptional

Description of the report

displayEntityFieldsstring[]Optional

Entity fields displayed in the report

dashboardNamestringOptional

Name of the dashboard

scopestringOptional

Scope of the report

operationstringOptional

Operation performed

recordCountinteger · int64Optional

Number of records

queriedEntitiesstring[]Optional

Entities queried in the report

groupedColumnHeadersstring[]Optional

Grouped column headers

columnCountinteger · int64Optional

Number of columns

processedRowCountinteger · int64Optional

Number of rows processed

sourceIPstringOptional

Source IP address

eventSourcestringOptional

Source of the event

sessionLevelstringOptional

Level of the session

querystringOptional

Query executed

eventIdentifierstringOptional

Identifier of the event

sourceIPstringOptional

Source IP address

sessionKeystringOptional

Key of the session

sessionLevelstringOptional

Level of the session

mediumstring · enumOptional

Medium used

Possible values:

mediumNamestringOptional

Name of the medium

userstringOptional

User of the endpoint agent

idstringOptional

Unique identifier for the actor in Nightfall

emailstring · emailOptional

Email of the actor

commentstringOptional

Comment or notes associated with the event

userBelongsToGroupsstring[]Optional

Groups the user belongs to

isAdminbooleanOptional

Whether the user is an admin

isSuspendedbooleanOptional

Whether the user is suspended

createdAtinteger · nullableOptional

Timestamp when the user was created

salesforceobjectOptional

Salesforce user metadata (currently empty as per spec)

deviceIDstringOptional

ID of the device

machineNamestringOptional

Name of the machine/device

typestring · enumOptional

Type of the event

Possible values:

timestampintegerOptional

Timestamp of the event

browserNamestringOptional

Name of the browser

browserVersionstringOptional

Version of the browser

domainstringOptional

Domain where the upload occurred

browserTabURLstringOptional

URL of the active browser tab

browserTabTitlestringOptional

Title of the active browser tab

uploadStartTimeintegerOptional

Unix timestamp when the upload started

uploadEndTimeintegerOptional

Unix timestamp when the upload ended

fileNamestringOptional

Name of the uploaded file

timestampintegerOptional

Unix timestamp of the origin event

browserNamestringOptional

Name of the browser

browserVersionstringOptional

Version of the browser

domainstringOptional

Domain where the download occurred

browserTabURLstringOptional

URL of the browser tab

browserTabTitlestringOptional

Title of the browser tab

downloadStartTimeinteger · int64Optional

Unix timestamp when the download started

downloadEndTimeinteger · int64Optional

Unix timestamp when the download ended

contentTypestring · enumOptional

Type of content copied to clipboard

Possible values:

browserNamestringOptional

Name of the browser

browserVersionstringOptional

Version of the browser

domainstringOptional

Domain of the browser

browserTabURLstringOptional

URL of the browser tab

browserTabTitlestringOptional

Title of the browser tab

appstringOptional

Cloud sync application

accountTypestringOptional

Type of account

accountNamestringOptional

Name of the account

emailstringOptional

Email associated with the account

destinationFilePathstringOptional

Path where the file was synced

uploadStartTimeintegerOptional

Unix timestamp when the upload started

uploadEndTimeintegerOptional

Unix timestamp when the upload ended

fileNamestringOptional

Name of the synced file

contentTypestringOptional

Type of content in the clipboard

timestampintegerOptional

Unix timestamp of the origin event

browserNamestringOptional

Name of the browser

browserVersionstringOptional

Version of the browser

domainstringOptional

Domain where the download occurred

browserTabURLstringOptional

URL of the browser tab

browserTabTitlestringOptional

Title of the browser tab

downloadStartTimeinteger · int64Optional

Unix timestamp when the download started

downloadEndTimeinteger · int64Optional

Unix timestamp when the download ended

contentTypestring · enumOptional

Type of content copied to clipboard

Possible values:

browserNamestringOptional

Name of the browser

browserVersionstringOptional

Version of the browser

domainstringOptional

Domain of the browser

browserTabURLstringOptional

URL of the browser tab

browserTabTitlestringOptional

Title of the browser tab

browserNamestringOptional

Name of the browser

browserVersionstringOptional

Version of the browser

domainstringOptional

Domain of the browser

browserTabURLstringOptional

URL of the browser tab

browserTabTitlestringOptional

Title of the browser tab

originatingAppIdstringOptional

ID of the originating app

originatingAppNamestringOptional

Name of the originating app

isClientSyncEventbooleanOptional

Whether this is a client sync event

sourceIPstringOptional

Source IP address

sessionLevelstringOptional

Level of the session

sessionKeystringOptional

Key of the session

sfUserIdstringOptional

Salesforce user ID

assetIDsstring[]Optional

asset IDs associated with the event

400

Invalid request parameters

application/json

401

Authentication failure

application/json

404

Event does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/events/{eventId}

Developer APIs

Welcome to Developer APIs Documentation

Introduction to Developer APIs

Overview

hashtagScan APIs

Authentication and Security

Key Concepts

Entities and Terms to Know

hashtagDetectors

hashtagCustom Detectors

hashtagExclusion Rules

hashtagContext Rules

hashtagReturning Surrounding Context

hashtagDetection Rules

hashtagConfidence Levels

hashtagPolicies

Setting Up Nightfall

Creating API Key

hashtag🚧Be Sure to Record the API Key's Value

Creating Policies

Scanning Text

Scanning Files

hashtagPrerequisites

Webhooks and Asynchronous Notifications

Accessing Your Webhook Signing Key

Scanning Features

Scanning Images for patterns using Custom Regex Detectors

PHI Detection Rules

Test Datasets

Errors

hashtagHTTP Error Codes

Nightfall Playground

Nightfall APIs

DLP APIs - Firewall for AI Platform

Rate Limits for Firewall APIs

DLP APIs - Native SaaS Apps

Rate Limits for Native SaaS app APIs

Policy Update APIs

Exfiltration Prevention APIs

Posture Management APIs

SaaS App and Device Management APIs

Nightfall Model Context Protocol (MCP) Server

Common Use Cases

hashtagSecurity Investigations

hashtagInsider Threat Response

hashtagBulk Remediation

hashtagCompliance Reporting

hashtagData Exfiltration Detection

hashtagPermission Audits

Query Examples

hashtagBasic Searches

Troubleshooting

hashtagQuery Issues

hashtagPerformance

Support & Resources

hashtagGetting Help

hashtagProviding Feedback

hashtagAdditional Learning Resources

Nightfall Software Development Kit (SDK)

Overview

Language Specific Guides

Overview

Tutorials

Nightfall Use Cases

Overview

FAQs

What Can I do with the Firewall for AI

How quickly can I get started with Firewall for AI?

What types of data can I scan with API?

What types of detectors are supported out of the box?

Can I customize or bring my own detectors?

What is the pricing model?

How do I get in touch with you?

Can I test out the detection and my own detection rules before writing any code?

How does Nightfall support custom data types?

Contact Us

hashtagSchedule a Demo

hashtagEmail Us

Authentication and Security

Welcome to Developer APIs Documentation

Scan APIs

Detectors

Custom Detectors

Exclusion Rules

Context Rules

Returning Surrounding Context

Detection Rules

Confidence Levels

Policies

🚧Be Sure to Record the API Key's Value

Prerequisites

HTTP Error Codes

Security Investigations

Insider Threat Response

Bulk Remediation

Compliance Reporting

Data Exfiltration Detection

Permission Audits

Basic Searches

Query Issues

Performance

Getting Help

Providing Feedback

Additional Learning Resources

Schedule a Demo

Email Us

Scan APIs

Key Features

Customizable and Built-in Machine Learning-based Detectors

A Flexible Data Security Solution

Using the API

Where to Go From Here

Detectors

Custom Detectors

Exclusion Rules

Context Rules

Returning Surrounding Context

Detection Rules

Confidence Levels

Policies

🚧Be Sure to Record the API Key's Value

Prerequisites

HTTP Error Codes

Security Investigations

Insider Threat Response

Bulk Remediation

Compliance Reporting

Data Exfiltration Detection

Permission Audits

Query Issues

Performance

Getting Help

Providing Feedback

Additional Learning Resources

Schedule a Demo

Email Us