Default

Search exfiltration events

get

Fetch a list of exfiltration events based on some filters

Authorizations

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:"[e-mail]"
field	user_email
operator	:
value	[e-mail]

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:[e-mail]
• 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

Responses

200

Successful response

application/json

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

HTTPcURLJavaScriptPython

GET /exfiltration/v1/events/search HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "events": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "integration": "text",
      "createdAt": 1,
      "state": "text",
      "eventType": "text",
      "policyUUIDs": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "assetsCount": 1,
      "userInfo": {
        "username": "text",
        "userEmail": "[e-mail]",
        "userProfileLink": "https://example.com",
        "deviceId": "text",
        "machineName": "text",
        "isExternal": true
      },
      "appInfo": {
        "id": "text",
        "name": "text"
      }
    }
  ],
  "nextPageToken": "text"
}

Fetch exfiltration events

get

Fetch a list of exfiltration events for a period

Authorizations

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

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

HTTPcURLJavaScriptPython

GET /exfiltration/v1/events HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "events": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "integration": "text",
      "createdAt": 1,
      "state": "text",
      "eventType": "text",
      "policyUUIDs": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "assetsCount": 1,
      "userInfo": {
        "username": "text",
        "userEmail": "[e-mail]",
        "userProfileLink": "https://example.com",
        "deviceId": "text",
        "machineName": "text",
        "isExternal": true
      },
      "appInfo": {
        "id": "text",
        "name": "text"
      }
    }
  ],
  "nextPageToken": "text"
}

Fetch exfiltration event details

get

Fetch an exfiltration event details by ID

Authorizations

Path parameters

eventIdstring · uuidRequired

The UUID of the event to fetch

Responses

200

Successful response

application/json

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

HTTPcURLJavaScriptPython

GET /exfiltration/v1/events/{eventId} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "assets": {
    "id": "text",
    "name": "text",
    "path": "text",
    "sizeBytes": 1,
    "mimetype": "text",
    "owner": {
      "id": "text",
      "email": "[e-mail]",
      "comment": "text",
      "metadata": {
        "gdrive": {
          "userBelongsToGroups": [
            "text"
          ],
          "isAdmin": true,
          "isSuspended": true,
          "createdAt": 1
        },
        "salesforce": {},
        "endpointAgent": {
          "deviceID": "text",
          "machineName": "text"
        }
      }
    },
    "comment": "text",
    "ddrViolationIDs": [],
    "metadata": {
      "gdrive": {
        "fileID": "text",
        "fileName": "text",
        "fileSize": "text",
        "fileLink": "text",
        "permissionSetting": "text",
        "sharingExternalUsers": [
          "text"
        ],
        "sharingInternalUsers": [
          "text"
        ],
        "canViewersDownload": true,
        "fileOwner": "text",
        "isInTrash": true,
        "createdAt": 1,
        "updatedAt": 1,
        "drive": "text",
        "labels": [
          "text"
        ],
        "filePermissionType": "text"
      },
      "salesforce": {
        "resourceType": "text",
        "fileResourceMetadata": {
          "fileAction": "text",
          "sourceIP": "text",
          "sessionLevel": "text"
        },
        "reportResourceMetadata": {
          "description": "text",
          "displayEntityFields": [
            "text"
          ],
          "dashboardName": "text",
          "scope": "text",
          "operation": "text",
          "recordCount": 1,
          "queriedEntities": [
            "text"
          ],
          "groupedColumnHeaders": [
            "text"
          ],
          "columnCount": 1,
          "processedRowCount": 1,
          "sourceIP": "text",
          "eventSource": "text",
          "sessionLevel": "text"
        },
        "bulkApiResourceMetadata": {
          "query": "text",
          "eventIdentifier": "text",
          "sourceIP": "text",
          "sessionKey": "text",
          "sessionLevel": "text"
        }
      },
      "endpointAgent": {
        "medium": "EXFIL_MEDIUM_USB",
        "mediumName": "text",
        "user": "text"
      }
    }
  },
  "actor": {
    "id": "text",
    "email": "[e-mail]",
    "comment": "text",
    "metadata": {
      "gdrive": {
        "userBelongsToGroups": [
          "text"
        ],
        "isAdmin": true,
        "isSuspended": true,
        "createdAt": 1
      },
      "salesforce": {},
      "endpointAgent": {
        "deviceID": "text",
        "machineName": "text"
      }
    }
  },
  "events": {
    "type": "DOWNLOAD",
    "timestamp": 1,
    "metadata": {
      "endpointAgent": {
        "endpointBrowserUploadMetadata": {
          "browserName": "text",
          "browserVersion": "text",
          "domain": "text",
          "browserTabURL": "text",
          "browserTabTitle": "text",
          "uploadStartTime": 1,
          "uploadEndTime": 1,
          "fileName": "text",
          "originMetadata": [
            {
              "timestamp": 1,
              "browserDownloadMetadata": {
                "browserName": "text",
                "browserVersion": "text",
                "domain": "text",
                "browserTabURL": "text",
                "browserTabTitle": "text",
                "downloadStartTime": 1,
                "downloadEndTime": 1
              },
              "clipboardCopyMetadata": {
                "contentType": "CCT_TEXT",
                "browserMetadata": {
                  "browserName": "text",
                  "browserVersion": "text",
                  "domain": "text",
                  "browserTabURL": "text",
                  "browserTabTitle": "text"
                }
              }
            }
          ]
        },
        "endpointCloudSyncMetadata": {
          "app": "text",
          "accountType": "text",
          "accountName": "text",
          "email": "text",
          "destinationFilePath": "text",
          "uploadStartTime": 1,
          "uploadEndTime": 1,
          "fileName": "text"
        },
        "endpointClipboardMetadata": {
          "contentType": "text",
          "originMetadata": [
            {
              "timestamp": 1,
              "browserDownloadMetadata": {
                "browserName": "text",
                "browserVersion": "text",
                "domain": "text",
                "browserTabURL": "text",
                "browserTabTitle": "text",
                "downloadStartTime": 1,
                "downloadEndTime": 1
              },
              "clipboardCopyMetadata": {
                "contentType": "CCT_TEXT",
                "browserMetadata": {
                  "browserName": "text",
                  "browserVersion": "text",
                  "domain": "text",
                  "browserTabURL": "text",
                  "browserTabTitle": "text"
                }
              }
            }
          ],
          "destinationMetadata": {
            "browserMetadata": {
              "browserName": "text",
              "browserVersion": "text",
              "domain": "text",
              "browserTabURL": "text",
              "browserTabTitle": "text"
            }
          }
        }
      },
      "gdrive": {
        "originatingAppId": "text",
        "originatingAppName": "text",
        "isClientSyncEvent": true
      },
      "salesforce": {
        "sourceIP": "text",
        "sessionLevel": "text",
        "sessionKey": "text",
        "sfUserId": "text"
      }
    },
    "assetIDs": []
  }
}

Fetch asset activity

get

Fetch the activity history for a specific asset

Authorizations

Query parameters

assetIDstringRequired

The ID of the asset to fetch activities for

rangeStartintegerRequired

Unix timestamp in seconds, filters activities created ≥ the value

rangeEndintegerRequired

Unix timestamp in seconds, filters activities created < the value

pageTokenstringOptional

Cursor for getting the next page of results

Responses

200

Successful response

application/json

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

HTTPcURLJavaScriptPython

GET /exfiltration/v1/asset/activity HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "activities": [
    {
      "type": "DOWNLOAD",
      "userEmail": "[e-mail]",
      "eventTime": 1,
      "assetNames": [
        "text"
      ],
      "metadata": {
        "downloadEventMetadata": {
          "source": "text",
          "fileName": "text"
        },
        "browserUploadMetadata": {
          "domain": "text",
          "fileName": "text"
        },
        "cloudSyncMetadata": {
          "cloudApp": "text",
          "fileName": "text"
        },
        "clipboardMetadata": {
          "browserMetadata": {
            "domain": "text"
          }
        }
      }
    }
  ],
  "nextPageToken": "text"
}

Fetch actor activity

get

Fetch the activity history for a specific actor

Authorizations

Query parameters

actorIDstringRequired

The Nightfall ID of the actor to fetch activities for

rangeStartintegerRequired

Unix timestamp in seconds, filters activities created ≥ the value

rangeEndintegerRequired

Unix timestamp in seconds, filters activities created < the value

pageTokenstringOptional

Cursor for getting the next page of results

Responses

200

Successful response

application/json

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

HTTPcURLJavaScriptPython

GET /exfiltration/v1/actor/activity HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "activities": [
    {
      "type": "DOWNLOAD",
      "userEmail": "[e-mail]",
      "eventTime": 1,
      "assetNames": [
        "text"
      ],
      "metadata": {
        "downloadEventMetadata": {
          "source": "text",
          "fileName": "text"
        },
        "browserUploadMetadata": {
          "domain": "text",
          "fileName": "text"
        },
        "cloudSyncMetadata": {
          "cloudApp": "text",
          "fileName": "text"
        },
        "clipboardMetadata": {
          "browserMetadata": {
            "domain": "text"
          }
        }
      }
    }
  ],
  "nextPageToken": "text"
}