Search Violations

Search violations

Fetch a list of violations based on some filters

GEThttps://api.nightfall.ai/dlp/v1/violations/search

Query parameters

createdAfterinteger

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

createdBeforeinteger

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

updatedAfterinteger

Unix timestamp in seconds, filters records updated > the value

limitinteger

The maximum number of records to be returned in the response

pageTokenstring

Cursor for getting the next page of results

sortViolationSearchSortKey (enum)

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

TIME_ASCTIME_DESCRELEVANCERISK_ASCRISK_DESC

query*string

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:"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:

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

Response

Successful response

Headers

X-Rate-Limit-Remaininginteger

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

X-Quota-Remaininginteger

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

X-Quota-Period-Endstring (date-time)

When the current quota period expires

Body

violationsarray of Violation (object)

idstring

The violation id

integrationIntegration (enum)

SLACKGDRIVEJIRACONFLUENCESALESFORCEZENDESKBROWSERNOTIONGITHUBM365_TEAMSM365_ONEDRIVEINLINE_EMAIL

createdAtinteger

Unix timestamp when the violation was created

updatedAtinteger

Unix timestamp when the violation was updated

possibleActionsarray of Action (enum)

Possible actions for the violation

itemsAction (enum)

ACKNOWLEDGEREDACTQUARANTINEALLOW_QUARANTINEREJECT_QUARANTINEREMOVE_INTERNAL_USERSREMOVE_EXTERNAL_USERSDOMAIN_WIDE_LINKRESTRICTED_LINKDELETEIGNORENOTIFY_SLACKNOTIFY_EMAILUNACKNOWLEDGEDISABLE_DOWNLOADCREATE_JIRA_ISSUEMARK_AS_PRIVATEDELETE_ATTACHMENTMANUAL_UNDORESOLVENOTIFY_TEAMSNOTIFY_GITHUBSOFT_DELETEHARD_DELETERESTRICT_TO_OWNER

stateViolationState (enum)

ACTIVEPENDINGRESOLVEDEXPIRED

resourceLinkstring

The link to the resource on the integration

metadataMetadata (object)

slackMetadataSlackMetadata (object)

locationstring

The channel name in case of a message in a channel

locationTypestring

Type of location

usernamestring

User name

userIDstring

ID - user

messagePermalinkstring

Link to message

locationMembersarray of string

Members for the location

itemsstring

locationMemberCountinteger

Count of members for the location

channelIDstring

ID - channel

workspaceNamestring

Name of workspace

confluenceMetadataConfluenceMetadata (object)

itemNamestring

Name of item

itemTypestring

Type of item

isArchivedboolean

Archived status

createdAtinteger

Unix timestamp

updatedAtinteger

Unix timestamp

labelsarray of string

List of labels

itemsstring

spaceNamestring

Name of space

spaceKeystring

Key of space

spaceNameLinkstring

Link of space

parentPageNamestring

Parent page

authorNamestring

Name of author

authorEmailstring

Email of author

authorNameLinkstring

Link of author name

permalinkstring

Link to resource

confluenceIDstring

ID - Confluence internal

confluenceUserIDstring

ID - Confluence user

itemVersioninteger

Version of item

parentPageIDstring

ID - parent page

parentVersioninteger

Version of parent page

gdriveMetadataGdriveMetadata (object)

fileIDstring

ID of file

fileNamestring

The name of the file

fileTypestring

Type of file

fileSizestring

File size

fileLinkstring

Link to file

permissionSettingstring

Permissions

sharingExternalUsersarray of string

User list shared with - external

itemsstring

sharingInternalUsersarray of string

User list shared with - internal

itemsstring

canViewersDownloadboolean

Available for viewers to download

fileOwnerstring

File owner

isInTrashboolean

In trash

createdAtinteger

Unix timestamp, when the file was created

updatedAtinteger

Unix timestamp, when the file was updated

drivestring

Drive name

updatedBystring

Updated by user

jiraMetadataJiraMetadata (object)

projectNamestring

Name of project

ticketNumberstring

Ticket number

projectTypestring

Type of project

issueIDstring

ID for the issue

projectLinkstring

Link to project

ticketLinkstring

Link to ticket

commentLinkstring

Link to comment

attachmentLinkstring

Link to attachment

githubMetadataGithubMetadata (object)

branchNamestring

Branch on which violation occurred

organizationstring

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

repositorystring

Name of the repository

authorEmailstring

Email of the user who pushed the changes to GitHub

authorUsernamestring

Username of the user who pushed the changes to GitHub

createdAtinteger

Unix timestamp

isRepoPrivateboolean

Boolean to check if the repo is private or public

filePathstring

Path of the file on which violation occurred

githubPermalinkstring

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

repositoryOwnerstring

Owner of the repository

githubRepoLinkstring

Link to the repository

salesforceMetadataSalesforceMetadata (object)

orgNamestring

Name of the Salesforce organization

recordIDstring

ID of the record

objectNamestring

Name of the object

contentTypestring

Attachment or Object

userIDstring

ID of the user

userNamestring

Salesforce username of the author

updatedAtinteger

Unix timestamp when the object was last updated

fieldsarray of string

Fields of the Object

itemsstring

fileTypestring

File Type

attachmentLinkstring

Link to the attachment

attachmentNamestring

Name of the attachment

objectLinkstring

Link to the object

zendeskMetadataZendeskMetadata (object)

ticketStatusstring

Status of the ticket

ticketTitlestring

Title of the ticket

ticketRequestorstring

Ticket requested by

ticketGroupAssigneestring

Group the ticket is assigned to

ticketAgentAssigneestring

Agent the ticket is assigned to

currentUserRolestring

User role

ticketIDinteger

ID of the ticket

ticketFollowersarray of string

Followers of the ticket

itemsstring

ticketTagsstring

Tags for the ticket

createdAtinteger

Unix timestamp

UpdatedAtinteger

Unix timestamp

locationstring

Location

subLocationstring

Sub-location

ticketCommentIDinteger

ID - ticket comment

ticketGroupIDinteger

ID - ticket group

ticketGroupLinkstring

Link to the ticket group

ticketAgentIDinteger

ID - ticket agent

ticketAgentLinkstring

Link - ticket agent

ticketEventstring

Ticket event

userRolestring

Role of the user

attachmentNamestring

Name of the attachment

attachmentLinkstring

Link for the attachment

notionMetadataNotionMetadata (object)

createdBystring

Page creator

updatedBystring

Page update by

workspaceNamestring

Workspace name

workspaceLinkstring

Link to workspace

pageIDstring

ID of the page

pageTitlestring

Title of the page

createdAtinteger

Unix timestamp

updatedAtinteger

Unix timestamp

privatePageLinkstring

Private page link

publicPageLinkstring

Public page link

sharedExternallyboolean

Externally shared state

attachmentIDstring

ID of the attachment

browserMetadataBrowserMetadata (object)

locationstring

Page URL where the extension is launched

subLocationstring

Specific location on the page

browserNamestring

Browser type

userCommentstring

Remediation comment from the user

m365TeamsMetadataM365TeamsMetadata (object)

teamNamestring

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

tenantIDstring

ID of the tenant

tenantDomainstring

Domain name of the tenant

teamIDstring

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

teamVisibilitystring

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

teamWebURLstring

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

channelIDstring

ID of the channel where the message was sent

channelNamestring

Name of the channel where the message was sent

channelTypestring

Type of the channel where the message was sent

channelWebURLstring

Web URL of the channel where the message was sent

messageIDstring

ID of the message

createdAtinteger

Unix timestamp

updatedAtinteger

Unix timestamp

chatMessageSenderstring

Sender of the chat message

userIDstring

ID of the user who sent the message

userPrincipalNamestring

Principal name of the user who sent the message

attachmentsarray of M365TeamsAttachment (object)

Attachment details

attachmentIDstring

ID of the attachment present in the message

attachmentNamestring

Name of the attachment present in the message

attachmentURLstring

URL of the attachment present in the message

chatMessageImportancestring

Importance of the sent message

chatIDstring

ID of the chat conversation

chatTypestring

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

chatTopicstring

Topic or subject of the chat conversation

chatParticipantsarray of M365TeamsChatParticipant (object)

userIDstring

ID of the user participating in the chat conversation

emailstring

email address of the chat participant

displayNamestring

display name of the chat participant

m365OnedriveMetadataM365OnedriveMetadata (object)

tenantIDstring

ID of the tenant

tenantDomainstring

Domain name of the tenant

driveItemIDstring

ID of the drive item

driveItemNamestring

Name of the drive item

driveItemURLstring

URL of the drive item

driveItemMimeTypestring

Mime type of the drive item

driveItemSizeinteger

Size of the drive item in bytes

parentPathstring

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

createdByIDstring

ID of the user who created the drive item

updatedByEmailstring

Email of the user who last updated the drive item

updatedByIDstring

ID of the user who last updated the drive item

updatedByNamestring

Name of the user who last updated the drive item

createdAtinteger

Unix timestamp when the drive item was created

updatedAtinteger

Unix timestamp when the drive item was last updated

specialFolderNamestring

Name of the special folder if drive item is inside one

driveIDstring

ID of the drive where the drive item is present

driveOwnerNamestring

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

driveOwnerEmailstring

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

driveOwnerIDstring

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

inlineEmailMetadataInlineEmailMetadata (object)

domainstring

Domain of the company where email was sent from

user_namestring

User Name who sent the email

fromstring

Email of the sender

toarray of string

Recipients of the Email

itemsstring

ccarray of string

Recipients mentioned in the CC field of the Email

itemsstring

bccarray of string

Recipients mentioned in the BCC field of the Email

itemsstring

subjectstring

Subject of the email

sent_atinteger

Unix timestamp of when email was sent

thread_idstring

ThreadID of the email

attachment_namestring

Name of the attachment

attachment_typestring

Type of attachment

fileDetailsFileDetails (object)

fileNamestring

The name of the file

mimeTypestring

The file mime type

permalinkstring

The link to the resource on the integration

policyUUIDsarray of string

Policies violated

itemsstring

detectionRuleUUIDsarray of string

Detection rules triggered

itemsstring

detectorUUIDsarray of string

Detectors triggered

itemsstring

riskViolationRisk (enum)

UNSPECIFIEDLOWMEDIUMHIGHCRITICALNO_RISK

riskSourceViolationRiskSource (enum)

NIGHTFALLCUSTOMOVERRIDDEN

riskScorenumber (float)

The calculated score of the risk for this violation

userInfoUserInformation (object)

usernamestring

Username as on the integration

userEmailstring

User email as on the integration, may be empty

nextPageTokenstring

Next page cursor, omitted if end of results reached

Request

const response = await fetch('https://api.nightfall.ai/dlp/v1/violations/search?query=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "violations": [
    {
      "id": "text",
      "integration": "SLACK",
      "possibleActions": [
        "ACKNOWLEDGE"
      ],
      "state": "ACTIVE",
      "resourceLink": "text",
      "metadata": {
        "slackMetadata": {
          "location": "text",
          "locationType": "text",
          "username": "text",
          "userID": "text",
          "messagePermalink": "text",
          "locationMembers": [
            "text"
          ],
          "channelID": "text",
          "workspaceName": "text"
        },
        "confluenceMetadata": {
          "itemName": "text",
          "itemType": "text",
          "isArchived": false,
          "labels": [
            "text"
          ],
          "spaceName": "text",
          "spaceKey": "text",
          "spaceNameLink": "text",
          "parentPageName": "text",
          "authorName": "text",
          "authorEmail": "text",
          "authorNameLink": "text",
          "permalink": "text",
          "confluenceID": "text",
          "confluenceUserID": "text",
          "parentPageID": "text"
        },
        "gdriveMetadata": {
          "fileID": "text",
          "fileName": "text",
          "fileType": "text",
          "fileSize": "text",
          "fileLink": "text",
          "permissionSetting": "text",
          "sharingExternalUsers": [
            "text"
          ],
          "sharingInternalUsers": [
            "text"
          ],
          "canViewersDownload": false,
          "fileOwner": "text",
          "isInTrash": false,
          "drive": "text",
          "updatedBy": "text"
        },
        "jiraMetadata": {
          "projectName": "text",
          "ticketNumber": "text",
          "projectType": "text",
          "issueID": "text",
          "projectLink": "text",
          "ticketLink": "text",
          "commentLink": "text",
          "attachmentLink": "text"
        },
        "githubMetadata": {
          "branchName": "text",
          "organization": "text",
          "repository": "text",
          "authorEmail": "text",
          "authorUsername": "text",
          "isRepoPrivate": false,
          "filePath": "text",
          "githubPermalink": "text",
          "repositoryOwner": "text",
          "githubRepoLink": "text"
        },
        "salesforceMetadata": {
          "orgName": "text",
          "recordID": "text",
          "objectName": "text",
          "contentType": "text",
          "userID": "text",
          "userName": "text",
          "fields": [
            "text"
          ],
          "fileType": "text",
          "attachmentLink": "text",
          "attachmentName": "text",
          "objectLink": "text"
        },
        "zendeskMetadata": {
          "ticketStatus": "text",
          "ticketTitle": "text",
          "ticketRequestor": "text",
          "ticketGroupAssignee": "text",
          "ticketAgentAssignee": "text",
          "currentUserRole": "text",
          "ticketFollowers": [
            "text"
          ],
          "ticketTags": "text",
          "location": "text",
          "subLocation": "text",
          "ticketGroupLink": "text",
          "ticketAgentLink": "text",
          "ticketEvent": "text",
          "userRole": "text",
          "attachmentName": "text",
          "attachmentLink": "text"
        },
        "notionMetadata": {
          "createdBy": "text",
          "updatedBy": "text",
          "workspaceName": "text",
          "workspaceLink": "text",
          "pageID": "text",
          "pageTitle": "text",
          "privatePageLink": "text",
          "publicPageLink": "text",
          "sharedExternally": false,
          "attachmentID": "text"
        },
        "browserMetadata": {
          "location": "text",
          "subLocation": "text",
          "browserName": "text",
          "userComment": "text"
        },
        "m365TeamsMetadata": {
          "teamName": "text",
          "tenantID": "text",
          "tenantDomain": "text",
          "teamID": "text",
          "teamVisibility": "text",
          "teamWebURL": "text",
          "channelID": "text",
          "channelName": "text",
          "channelType": "text",
          "channelWebURL": "text",
          "messageID": "text",
          "chatMessageSender": "text",
          "userID": "text",
          "userPrincipalName": "text",
          "attachments": [
            {
              "attachmentID": "text",
              "attachmentName": "text",
              "attachmentURL": "text"
            }
          ],
          "chatMessageImportance": "text",
          "chatID": "text",
          "chatType": "text",
          "chatTopic": "text",
          "chatParticipants": [
            {
              "userID": "text",
              "email": "text",
              "displayName": "text"
            }
          ]
        },
        "m365OnedriveMetadata": {
          "tenantID": "text",
          "tenantDomain": "text",
          "driveItemID": "text",
          "driveItemName": "text",
          "driveItemURL": "text",
          "driveItemMimeType": "text",
          "parentPath": "text",
          "createdByID": "text",
          "updatedByEmail": "text",
          "updatedByID": "text",
          "updatedByName": "text",
          "specialFolderName": "text",
          "driveID": "text",
          "driveOwnerName": "text",
          "driveOwnerEmail": "text",
          "driveOwnerID": "text"
        },
        "inlineEmailMetadata": {
          "domain": "text",
          "user_name": "text",
          "from": "text",
          "to": [
            "text"
          ],
          "cc": [
            "text"
          ],
          "bcc": [
            "text"
          ],
          "subject": "text",
          "thread_id": "text",
          "attachment_name": "text",
          "attachment_type": "text"
        }
      },
      "fileDetails": {
        "fileName": "text",
        "mimeType": "text",
        "permalink": "text"
      },
      "policyUUIDs": [
        "text"
      ],
      "detectionRuleUUIDs": [
        "text"
      ],
      "detectorUUIDs": [
        "text"
      ],
      "risk": "UNSPECIFIED",
      "riskSource": "NIGHTFALL",
      "riskScore": 0,
      "userInfo": {
        "username": "text",
        "userEmail": "text"
      }
    }
  ],
  "nextPageToken": "text"
}