Posture Management APIs | Developer APIs | Nightfall Documentation
Posture Management APIs | Developer 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
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:"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.comuser_name:"John Doe"
Special Characters
+ - && || ! ( ) { } [ ] ^ " ~ * ? : are special characters need to be escaped using \. For example:
- a value like
(1+1):2should 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
codeintegerOptional
A status code to uniquely describe this error.
messagestringOptional
A message associated with the status code.
descriptionstringOptional
Additional details to explain what may have occurred. Omitted if empty.
get/events/search
Fetch posture events
get
Fetch a list of posture events for a period
Authorizations
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
codeintegerOptional
A status code to uniquely describe this error.
messagestringOptional
A message associated with the status code.
descriptionstringOptional
Additional details to explain what may have occurred. Omitted if empty.
get/events
Fetch posture event details
get
Fetch an posture event details by ID
Authorizations
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
codeintegerOptional
A status code to uniquely describe this error.
messagestringOptional
A message associated with the status code.
descriptionstringOptional
Additional details to explain what may have occurred. Omitted if empty.
get/events/{eventId}
Fetch posture event activity feed
get
Fetch the activity feed for a specific posture event
Authorizations
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
codeintegerOptional
A status code to uniquely describe this error.
messagestringOptional
A message associated with the status code.
descriptionstringOptional
Additional details to explain what may have occurred. Omitted if empty.
get/events/{eventId}/activity
Fetch asset activity
get
Fetch the activity history for a specific asset
Authorizations
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
codeintegerOptional
A status code to uniquely describe this error.
messagestringOptional
A message associated with the status code.
descriptionstringOptional
Additional details to explain what may have occurred. Omitted if empty.
get/asset/activity
Fetch actor activity
get
Fetch the activity history for a specific actor
Authorizations
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
codeintegerOptional
A status code to uniquely describe this error.
messagestringOptional
A message associated with the status code.
descriptionstringOptional
Additional details to explain what may have occurred. Omitted if empty.
get/actor/activity