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

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
get
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": "[email protected]",
        "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
get
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": "[email protected]",
        "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
get
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": "[email protected]",
      "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": "[email protected]",
    "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
get
GET /exfiltration/v1/asset/activity HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "activities": [
    {
      "type": "DOWNLOAD",
      "userEmail": "[email protected]",
      "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
get
GET /exfiltration/v1/actor/activity HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "activities": [
    {
      "type": "DOWNLOAD",
      "userEmail": "[email protected]",
      "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"
}
PreviousExfiltration Prevention APIsNextModels

Was this helpful?