The api/audit/users endpoint provides user list information extracted from recorded sessions.
Prerequisites
URL
GET https://<IP-address-of-SPS>/api/audit/users
Cookies
| session_id |
Contains the authentication token of the user |
Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For more information on authentication, see Authenticate to the SPS REST API.
NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
Sample request
The following command lists the available user information.
Querying audited users request
Response
The following is a sample response received when listing user information.
Querying audited users response
For more information on the meta object, see Message format.
Elements response message body include:
|
items |
|
List |
Top level element, lists audited users. |
|
|
user_id |
String |
The ID of the user. |
|
last_seen |
String |
The date of the user's last activity. |
|
score |
String |
The risk of the user's activity according to the baseline. |
|
score_timestamp |
String |
The date when the score was calculated. |
|
meta |
|
JSON object |
Top level element, contains metadata about the endpoint. |
|
href |
string (relative path) |
Path of the resource that returned the response. When creating a new object, this is the URL of the created object. |
|
|
limit |
Integer |
This parameter displays the number of users returned in the response body. The default value is 100. |
|
parent |
string (relative path) |
Path of the parent of the current resource. |
Sample request
The following command lists the user information and limits the search results in 1.
NOTE: The maximum value that you can give to the limit parameter is 10,000.
Querying audited users using the `limit` parameter to limit the search results request
Response
The following is a sample response received when listing user information and limiting the search results in 1.
Querying audited users using the `limit` parameter to limit the search results response
Sample request
The following command sorts user information based on the score parameter.
NOTE: The default sorting method sorts the results based on the last_seen and the score parameters in a decreasing manner (-last_seen,-score).
Querying audited users using the `sort` parameter to sort the search results request
Response
The following is a sample response received when sorting user information based on the score parameter.
Querying audited users using the `sort` parameter to sort the search results response
Querying the users count
api/audit/users/_count
Using this endpoint, you can check the total number of users in the recorded sessions.
Sample request
The following command counts the total number of users in the recorded sessions.
Querying the number of audited users request
Response
The following is a sample response received when counting the total number of users in the recorded sessions.
Querying the number of audited users response
Elements response message body include:
|
count |
|
Integer |
Displays the total number of users in the recorded sessions. |
For more information on the meta object, see Message format.
Status and error codes
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
|
200 |
Ok |
The JSON file that contains the users information was retrieved successfully. |
|
400 |
UsersRestNotAvailable |
Querying users REST API endpoints on a cluster node with a search-minion role is not supported. To query users REST API endpoints, issue the same request on your search-master or search-local node. |
|
400 |
DuplicatedParameterError |
Invalid query: your query contains duplicated search parameter. Use each search parameter only once. |
|
400 |
InvalidSort |
Same field was given more than once. |
|
400 |
InvalidSort |
Invalid fields given. |
|
400 |
InvalidQueryValue |
Limit should be less than 10,001. |
|
400 |
NotANumber |
The limit request parameter you provided is invalid. To submit a valid request, provide a number for the limit request parameter. |
|
400 |
NegativeValue |
Limit should be greater than 0. |
|
401 |
Unauthenticated |
The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
|
403 |
Unauthorized |
The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
The api/audit/users/<user-id> endpoint provides detailed user information extracted from recorded sessions.
You can find the <user-id> parameter in the user_id field of the api/audit/users endpoint response.
The <user-id> parameter in the /api/audit/users/<user-id> endpoint is the URL-encoded version of the user_id field in the /api/audit/users endpoint.
Prerequisites
URL
GET https://<IP-address-of-SPS>/api/audit/users/<user-id>
Cookies
| session_id |
Contains the authentication token of the user |
Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For more information on authentication, see Authenticate to the SPS REST API.
NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
Sample request
The following command lists the available detailed user information.
Audited users
Response
The following is a sample response received when listing detailed user information.
Audited users
For more information on the meta object, see Message format.
Elements response message body include:
|
|
user_id |
String |
The ID of the user. |
|
last_seen |
String |
The date of the user's last activity. |
|
score |
String |
The risk of the user's activity according to the baseline. |
|
score_timestamp |
String |
The date when the score was calculated. |
|
|
baselines |
String |
The baselines that were created for the queried user. Baselines can have the following attributes: last_success.timestamp, last_success.baseline_id, last_failure.timestamp, last_failure.reason. |
|
meta |
|
JSON object |
Top level element, contains metadata about the endpoint. |
|
href |
string (relative path) |
Path of the resource that returned the response. When creating a new object, this is the URL of the created object. |
|
parent |
string (relative path) |
Path of the parent of the current resource. |
NOTE: Depending on the baselines built for the queried user, some baseline items might not appear in your response, as some of these items might not have been built for the queried user.
For more information on algorithms that build the baselines, see Algorithms in the Safeguard for Privileged Analytics Configuration Guide.
Status and error codes
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
|
200 |
Ok |
The JSON file that contains the users information was retrieved successfully. |
|
400 |
UsersRestNotAvailable |
Querying users REST API endpoints on a cluster node with a search-minion role is not supported. To query users REST API endpoints, issue the same request on your search-master or search-local node. |
|
401 |
Unauthenticated |
The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
|
403 |
Unauthorized |
The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
|
404 |
NotFound |
The queried user does not exist in the database. |
You can search in the contents of individual connections at the api/audit/sessions/<session-id>/content/?q=<my-search-expression> endpoint.
URL
GET https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/content/?q=<my-search-expression>
Cookies
| session_id |
Contains the authentication token of the user |
Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For more information on authentication, see Authenticate to the SPS REST API.
NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
Sample request
The following command retrieves those events in the contents of a specific connection that match the search expression(s).
curl --cookie cookies.txt https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/content/?q=<my-search-expression>
NOTE: Make sure that you use the ?q option and that when you use it, you do not leave it empty. Not using the ?q option or an empty ?q will result in an empty "items" list returned in the response.
You can use the Apache Lucene query syntax to create the search expression, but note the following points.
-
You must format the search expression as a URL, and escape special characters accordingly. For example, if your search expression is man iptables, you must escape the whitespace: man%20iptables
-
Do not begin the expression with the * wildcard.
Response
The response contains a list of those events in the contents of the connection that match the search expression(s). The response also contains some meta fields.
If you specified a search expression using the ?q option and the response returns an empty "items" list, that can indicate that:
The following is an example response:
{
"items": [
{
"channel.id": 5,
"end_time": "2017-08-14T10:35:43.957000",
"rank": 2.4756217002868652,
"record_id": {
"begin": 158,
"end": 160,
"for_screenshot": 158
},
"start_time": "2017-08-14T10:35:19.098000",
"trail_id": "12"
}
],
"meta":
{
"href": "/api/audit/sessions/2a620c1cfeb39c537a5e80280283d741/content",
"parent": "/api/audit/sessions/2a620c1cfeb39c537a5e80280283d741",
"remaining_seconds": 599
}
}
| items |
|
|
list |
Top-level element, a list containing the details of the matching session. |
|
channel.id |
|
integer |
A reference to the ID of the channel in the session where the event occurred. |
|
end_time |
|
string |
The timestamp of when the content disappeared from the screen.
Starting with SPS 5 LTS, the timestamp is in ISO 8601 format, for example, 2018-10-11T09:23:38.000+02:00. In earlier versions, it was in UNIX timestamp format. |
|
rank |
|
float |
Indicates the relevance of the match.
If there are several results, the order of them is based on their relevance. |
|
record_id |
|
integer |
The content element's exact position in the audit trail file. |
|
|
begin |
integer |
The identifier of the screenshot in the audit trail file where the content element first appeared. |
|
|
end |
integer |
The identifier of the screenshot in the audit trail file where the content element last appeared. |
|
|
for_screenshot |
integer |
The identifier of the most relevant screenshot in the audit trail file. This is the screenshot on which the event in question is the most clearly visible. For details on how to generate and retrieve the screenshot, see Generate and retrieve screenshot for content search. |
|
start_time |
|
string |
The timestamp of when the content first appeared on the screen and recording started.
Starting with SPS 5 LTS, the timestamp is in ISO 8601 format, for example, 2018-10-11T09:23:38.000+02:00. In earlier versions, it was in UNIX timestamp format. |
|
trail_id |
|
integer |
The unique identifier of the trail that contains the event. |
In addition, search results can contain the usual meta elements of other endpoints:
| meta |
|
JSON object |
Top-level element, a list containing meta information about the response.
For details about the type of information returned, see Message format. |
To generate and download screenshots for a specific content search result, complete the following steps. For details on searching in the content of a session, see Searching in connection content.
-
Perform a content search in a session.
Use a GET request on the endpoint of a specific session, for example:
GET https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/content/?q=<my-search-expression>
For details, see Searching in connection content. If there are search results for the search keywords in the session, the response includes a record_id block, for example:
"record_id": {
"begin": 158,
"end": 160,
"for_screenshot": 158
},
-
Generate a screenshot for the search result.
Note the value of the for_screenshot key in the search response, and use it to generate a screenshot for that particular record_id. POST the value of the for_screenshot key to the https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/_generate?record_ids=<value-of-for_screenshot> endpoint.
-
Download the screenshot.
To download the screenshot in PNG format, GET the value of the for_screenshot key to the https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/screenshots/<value-of-for_screenshot> endpoint.
