Posture Management APIs

You can use the posture management APIs to search posture events, fetch posture events and also event details. Additionally, you can also view details of the user (actor) whose actions triggered an event, and details of the asset that triggered an event.

Search posture events

get

Fetch a list of posture events based on some filters

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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:

• user_mail:[email protected]
• 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 posture 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 posture 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

/events/search

HTTPcURLJavaScriptPython

GET /posture/v1/events/search?query=text 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 posture events

get

Fetch a list of posture events for a period

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/events

HTTPcURLJavaScriptPython

GET /posture/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 posture event details

get

Fetch an posture event details by ID

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/events/{eventId}

HTTPcURLJavaScriptPython

GET /posture/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": {}
      }
    },
    "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"
        }
      }
    }
  },
  "actor": {
    "id": "text",
    "email": "[email protected]",
    "comment": "text",
    "metadata": {
      "gdrive": {
        "userBelongsToGroups": [
          "text"
        ],
        "isAdmin": true,
        "isSuspended": true,
        "createdAt": 1
      },
      "salesforce": {}
    }
  },
  "events": {
    "type": "PERMISSION_CHANGE",
    "timestamp": 1,
    "metadata": {
      "gdrive": {
        "originatingAppId": "text",
        "originatingAppName": "text",
        "isClientSyncEvent": true
      },
      "salesforce": {
        "sourceIP": "text",
        "sessionLevel": "text",
        "sessionKey": "text",
        "sfUserId": "text"
      }
    },
    "assetIDs": []
  }
}

Fetch posture event activity feed

get

Fetch the activity feed for a specific posture event

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

eventIdstring · uuidRequired

The UUID of the posture event

Query parameters

limitinteger · int32 · max: 100Optional

Number of activity items to fetch in one page

Default: 50

createdAfterintegerOptional

Unix timestamp in seconds, filters activity created > the value

createdBeforeintegerOptional

Unix timestamp in seconds, filters activity created < the value

descendingbooleanOptional

Whether to sort results in descending order (default false)

Default: false

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

404

Event does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/events/{eventId}/activity

HTTPcURLJavaScriptPython

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

{
  "activities": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "message": "text",
      "timestamp": 1,
      "type": "CREATION",
      "data": {
        "action": "ACKNOWLEDGE",
        "userUUID": "123e4567-e89b-12d3-a456-426614174000",
        "userName": "text",
        "userEmail": "text",
        "receiverEmail": "text",
        "actionLogData": {
          "applyLabelsActionLogData": {
            "activityType": "LABELS_SUCCESSFULLY_APPLIED",
            "labels": [
              "text"
            ],
            "labelUpdatesOnResource": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "failureReason": "text"
          },
          "setExpirationActionLogData": {
            "expirationTime": 1
          },
          "revokeAccessActionLogData": {
            "revokedEmails": [
              "text"
            ],
            "unRevokedEmails": [
              "text"
            ]
          },
          "notifyEmailActionLogData": {
            "receiverEmail": "text"
          },
          "genericActionLogData": {
            "additionalContext": "text"
          },
          "blockActionActionLogData": {
            "isBlocked": true,
            "blockReason": "text",
            "skippedReason": "text"
          }
        }
      }
    }
  ],
  "nextPageToken": "text"
}

Fetch asset activity

get

Fetch the activity history for a specific asset

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/asset/activity

HTTPcURLJavaScriptPython

GET /posture/v1/asset/activity?assetID=text&rangeStart=1&rangeEnd=1 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"
          },
          "thickAppMetadata": {
            "thickApp": "text"
          },
          "genericAppMetadata": {
            "appName": "text"
          },
          "appType": "text"
        }
      }
    }
  ],
  "nextPageToken": "text"
}

Fetch actor activity

get

Fetch the activity history for a specific actor

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/actor/activity

HTTPcURLJavaScriptPython

GET /posture/v1/actor/activity?actorID=text&rangeStart=1&rangeEnd=1 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"
          },
          "thickAppMetadata": {
            "thickApp": "text"
          },
          "genericAppMetadata": {
            "appName": "text"
          },
          "appType": "text"
        }
      }
    }
  ],
  "nextPageToken": "text"
}