Search Violations

PreviousFetch Violations by ID NextFetch Violation Findings

Last updated 6 months ago

Was this helpful?

Search violations

Fetch a list of violations based on some filters

get

/violations/search

Authorizations

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

sortenum

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

Options: TIME_ASC, TIME_DESC, RELEVANCE, RISK_ASC, RISK_DESC

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nightfall.ai/dlp/v1/violations/search?query=text' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

401

429

500

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

Successful response