DLP APIs - Native SaaS Apps
Last updated
Was this helpful?
Last updated
Was this helpful?
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 DLP APIs - Firewall for AI Platform section.
Fetch a list of violations for a period
Unix timestamp in seconds, filters records created ≥ the value, defaults to -90 days UTC
Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC
Unix timestamp in seconds, filters records updated > the value
The maximum number of records to be returned in the response
50
Cursor for getting the next page of results
Fetch a violation by ID
The UUID of the violation to fetch
Fetch a list of violations based on some filters
Unix timestamp in seconds, filters records created ≥ the value, defaults to -90 days UTC
Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC
Unix timestamp in seconds, filters records updated > the value
The maximum number of records to be returned in the response
50
Cursor for getting the next page of results
Sort key and direction, defaults to descending order by creation time
TIME_DESC
Possible values: The query containing filter clauses
Query structure and terminology
A query clause
consists of a field
followed by an operator
followed by a value
:
term | value |
---|---|
clause | user_email:"amy@rocketrides.io" |
field | user_email |
operator | : |
value | amy@rocketrides.io |
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:john@example.com
user_name:"John Doe"
Special Characters
+ - && || ! ( ) { } [ ] ^ " ~ * ? :
are special characters need to be escaped using \
. For example:
(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 |
Get findings for a specific violation
The UUID of the violation
Cursor for getting the next page of results
Number of findings to fetch in one page (max 1000)
1000
Fetch an annotation by ID
The UUID of the annotation to fetch
Remove the annotation for a finding
The UUID of the finding to unannotate
No content
Perform an action on a list of violations. If an action can't be performed on a violation, that violation is ignored. Depending on the action, it could be processed immediately or queued.
The UUIDs of the violations to perform the action on
The action to perform on the violations
Annotate a finding
The UUID of the finding to annotate
The annotation type
The comment to add to the annotation
Whether the annotation applies to all findings of this sensitive data (defaults to true)
true