List of options that affect all VNC connections.
GET https://<IP-address-of-SPS>/api/configuration/vnc/options
Cookie name | Description | Required | Values |
---|---|---|---|
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 details on authentication, see Authenticate to the SPS REST API. Note that 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). |
The following command lists global VNC options.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/vnc/options
The following is a sample response received when listing global VNC options.
For details of the meta object, see Message format.
{ "body": { "audit": { "cleanup": { "enabled": false }, "timestamping": { "selection": "local", "signing_interval": 30 } }, "service": { "enabled": true, "log_level": 4 } }, "key": "options", "meta": { "first": "/api/configuration/vnc/channel_policies", "href": "/api/configuration/vnc/options", "last": "/api/configuration/vnc/options", "next": null, "parent": "/api/configuration/vnc", "previous": "/api/configuration/vnc/channel_policies", "transaction": "/api/transaction" } }
Element | Type | Description | ||
---|---|---|---|---|
key | Top level item | Contains the ID of the endpoint. | ||
body | Top level item | Contains the elements of the global VNC options. | ||
audit | Top level item | Contains settings for timestamping and cleanup. | ||
service | Top level item | Global setting to enable VNC connections, and specify the logging detail. | ||
enabled | boolean | Set to true to enable VNC connections. | ||
log_level | int | Defines the logging detail of VNC connections. |
Set SPS as the timestamping server:
{ "audit": { "cleanup": { "enabled": false }, "timestamping": { "selection": "local", "signing_interval": 30 } }, "service": { "enabled": true, "log_level": 4 } }
Enable cleanup, and set it to occur every 10 days:
{ "audit": { "cleanup": { "channel_database_cleanup_days": 10, "enabled": true }, "timestamping": { "selection": "local", "signing_interval": 30 } }, "service": { "enabled": true, "log_level": 4 } }
Change timestamping to a remote server, without specifying a timestamping policy:
{ "audit": { "cleanup": { "channel_database_cleanup_days": 10, "enabled": true }, "timestamping": { "oid": { "enabled": false }, "selection": "remote", "server_url": "<url-of-timestamping-server>", "signing_interval": 30 } }, "service": { "enabled": true, "log_level": 4 } }
Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:
{ "audit": { "cleanup": { "channel_database_cleanup_days": 10, "enabled": true }, "timestamping": { "oid": { "enabled": true, "policy_oid": "1.2.3" }, "selection": "remote", "server_url": "<url-of-timestamping-server>", "signing_interval": 30 } }, "service": { "enabled": true, "log_level": 4 } }
To modify global VNC settings, you have to:
For details, see Open a transaction.
PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/vnc/options endpoint. You can find a detailed description of the available parameters listed in Element . The elements of the audit item are described in Elements of audit.
For details, see Commit a transaction.
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.
Code | Description | Notes |
---|---|---|
201 | Created | The new resource was successfully created. |
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. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
404 | NotFound | The requested object does not exist. |
Searching in the session database
Searching in connection content
The api/audit/sessions endpoint lists the recorded sessions (active and closed).
GET https://<IP-address-of-SPS>/api/audit/sessions
Cookie name | Description | Required | Values |
---|---|---|---|
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 details on authentication, see Authenticate to the SPS REST API. Note that 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). |
The following command lists the connections.
curl --cookie cookies https://<IP-address-of-SPS>/api/audit/sessions
The following command retrieves the properties of a specific connection.
curl --cookie cookies https://<IP-address-of-SPS>/api/audit/sessions/<session-id>
The following is a sample response received when listing connections.
For details of the meta object, see Message format.
{ "items": [ { "key": "2", "meta": { "href": "/api/audit/sessions/2" } }, { "key": "1", "meta": { "href": "/api/audit/sessions/1" } } ], "meta": { "fields": [], "first": "/api/audit/sessions?limit=500&offset=0&fields=", "href": "/api/audit/sessions", "last": "/api/audit/sessions?limit=500&offset=0&fields=", "limit": 500, "match_count": 39, "next": null, "offset": 0, "parent": "/api/audit", "previous": null } }
When retrieving the endpoint of a specific connection, the response is the following.
{ "body": { "active": false, "alerts": { "href": "/api/audit/sessions/rUhhQZ3jYsY1NDWYp9DEpq/alerts" }, "analytics": { "interesting_events": [], "scripted": false, "scripted_results": {}, "similar_sessions": [], "tags": [] }, "channels": { "href": "/api/audit/sessions/rUhhQZ3jYsY1NDWYp9DEpq/channels" }, "client": { "ip": "10.20.30.40", "name": "10.20.30.40", "port": 59125 }, "creation_time": "2018-11-14T12:26:59.244Z", "duration": 57, "end_time": "2018-09-15T14:22:00+05:00", "events": { "href": "/api/audit/sessions/rUhhQZ3jYsY1NDWYp9DEpq/events" }, "hidden": false, "indexing": { "href": "/api/audit/sessions/rUhhQZ3jYsY1NDWYp9DEpq/indexing" }, "node_id": "6fed7872-065e-41d2-9cfa-ba75e8cad901", "origin": "RECORDING", "phantom": false, "protocol": "SSH", "recording": { "archived": false, "audit_trail": { "archive": null, "download": { "href": "/api/audit/sessions/rUhhQZ3jYsY1NDWYp9DEpq/audit_trail" } }, "auth_method": "password", "channel_policy": "shell-only", "command_extracted": false, "connection_policy": "myconnectionpolicy", "connection_policy_id": "15682863055beac3c8d23bf", "content_reference_id": 30, "has_accepted_channel": true, "index_status": "INDEXED", "server_local": { "ip": "10.20.30.40", "name": "10.20.30.40", "port": 55386 }, "session_id": "svc/rUhhQZ3jYsY1NDWYp9DEpq/abcde:29", "target": { "ip": "10.20.30.40", "name": "10.20.30.40", "port": 221 }, "verdict": "Accepted", "window_title_extracted": false }, "revision": 15, "server": { "ip": "10.20.30.40", "name": "10.20.30.40", "port": 22 }, "start_time": "2018-09-15T15:53:00+05:00", "user": { "id": "myid", "name": "myname", "server_username": "myserver" }, "verdict": "ACCEPT" }, "key": "rUhhQZ3jYsY1NDWYp9DEpq", "meta": { "href": "/api/audit/sessions/rUhhQZ3jYsY1NDWYp9DEpq", "parent": "/api/audit/sessions", "remaining_seconds": 594 } }
Element | Type | Description | ||
---|---|---|---|---|
key | string | Top level element, contains the key of the connection or audit trail. | ||
body | Top level element (string) | Contains the properties of the connection. | ||
active | boolean | If the returned value is true, the connection is ongoing. | ||
alerts | Top level item |
Contains a link to the details of the alerts. For details, see Session alerts. An event is listed as alert only if the Actions > Store in Connection Database option is selected in the Content Policy used to handle the session. "alerts": { "href": "/api/audit/sessions/7930f4308efe8aecd710202d815b76ff/alerts" }, | ||
analytics | Top level item | Contains analytics details of the connection. | ||
channels | Top level list |
Contains a link to the details of the channel. "channels": { "href": "/api/audit/sessions/svc-rUhhQZ3jYsY1NDWYp9DEpq-kecske-29/channels" }, | ||
client | Top level item | The IP address and port number of the client. | ||
creation_time | date | The time this document was created. In optimal cases this is near equal to the session's original start_time. However, it can be later than start_time. | ||
duration | int | The duration of the session in seconds. Computed value. | ||
end_time | ISO 8601 date |
The timestamp of the end of the connection. For ongoing connection, the value is null. 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. | ||
events | Top level item |
Contains a link to the details of the events. For details, see Session events. "events": { "href": "/api/audit/sessions/7930f4308efe8aecd710202d815b76ff/events" }, | ||
hidden | boolean | True if this is a session that has not been displayed on the SPS GUI yet (due to fragmented data about the session). | ||
indexer | Top level item |
Contains the details of indexing. For details on configuring indexing, see Local services: configuring the indexer. "indexer": { "href": "/api/audit/sessions/rUhhQZ3jYsY1NDWYp9DEpq/indexer" }, | ||
node_id | string | The node ID of the SPS machine where this session has been recorded. | ||
origin | string |
How SPA received this session. The following values are possible:
| ||
protocol | string | The protocol of the connection. | ||
recording | Top level item | Contains the properties of the audit trail. | ||
archived | boolean | If the audit trail has been archived, this value is true, otherwise it is false. For details about the archiving, see the archive object of the psm.audit_trail field. | ||
audit_trail | Top level item | The path to the audit trail file on SPS. If the session does not have an audit trail, this element is not used. To download the audit trail, see Download audit trails. | ||
auth_method | Top level item |
Authentication method: The authentication method used in the connection. For example, password | ||
channel_policy | string | References the name of the channel policy. You can find the list of channel policies for each protocol at the /api/configuration/<protocol>/channel_policies/ endpoint. | ||
command_extracted | boolean | If commands have been extracted from this terminal session, this value is true, otherwise it is false. The extracted commands are available in the events object field. | ||
connection_policy | string | The name of the Connection Policy that handled the session, for example, ssh_gateway_auth. This is the name displayed on the Control > Connections page of the SPS web interface, and in the name field of the Connection Policy object. You can find the list of connection policies for each protocol at the /api/configuration/<protocol>/connections/ endpoint. | ||
connection_policy_id | string | The key of the Connection Policy that handled the session, for example, 54906683158e768e727100. You can find the list of connection policies for each protocol at the /api/configuration/<protocol>/connections/ endpoint. | ||
content_reference_id | long | The unique ID of the TCP connection. | ||
has_accepted_channel | boolean | True, if at least the connection has been built successfully, the authentication was successful, and there was actual traffic. | ||
index_status | string |
Channel's indexing status: Shows if the channel has been indexed. The following values are possible:
| ||
network_id | string | The ID of the Linux network namespace where the session originated from. | ||
server_local | Top level item | The IP address and port number of SPS. | ||
session_id | string | The identifier of the session. | ||
target | Top level item | The IP address and port number the client targeted for connection. | ||
verdict | string |
The connection verdict. Possible values are:
| ||
window_title_extracted | boolean | If window titles have been extracted from this graphical session, this value is true, otherwise it is false. The extracted window titles are available in the events object field. | ||
revision | int | The revision number of the document. A newer document has a larger revision number than an older one. This helps you to determine which session version is newer. | ||
server | Top level item | The IP address and port number of the remote server. | ||
trail_downloads | Top level item |
Contains a link to the details of the audit-trail downloads in this session (if any). "trail_downloads": { "href": "/api/audit/sessions/rUhhQZ3jYsY1NDWYp9DEpq/trail_downloads" }, | ||
start_time | ISO 8601 date |
The timestamp of the start of the connection. 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. | ||
user | Top level item | The details of the user authenticating on the remote server. | ||
id | string | The ID of the user. | ||
name | string | The username used for authenticating against the gateway. | ||
server_username | string | The username used for authenticating on the remote server. | ||
verdict | string | Indicates what SPS decided about the session. A session verdict that originates from log events or other external events. |
All possible SSH channel types:
"channels": [ { "key": "1", "meta": { "href": "/api/audit/sessions/1/channels/1" }, "body": { "type": "session shell", "verdict": "accept", "start_time": 1451901988, "end_time": 1451902145, "duration": 157 } }, { "key": "2", "meta": { "href": "/api/audit/sessions/1/channels/2" }, "body": { "type": "session exec", "verdict": "accept", "start_time": 1451902141, "end_time": 1451902145, "duration": 4, "command": "ls" } }, { "key": "3", "meta": { "href": "/api/audit/sessions/1/channels/3" }, "body": { "type": "session exec scp", "verdict": "accept", "start_time": 1451902141, "end_time": 1451902145, "duration": 4, "scp_path": "<path-to-folder>" } }, { "key": "4", "meta": { "href": "/api/audit/sessions/1/channels/4" }, "body": { "type": "session subsystem sftp", "verdict": "accept", "start_time": 1451902142, "end_time": 1451902145, "duration": 3, "subsystem_name": "sftp" } }, { "key": "5", "meta": { "href": "/api/audit/sessions/1/channels/5" }, "body": { "type": "local forward", "verdict": "accept", "start_time": 1451902145, "end_time": 1451902146, "duration": 1, "originator.address": "::1", "originator.port": 59578, "connected.address": "<server>", "connected.port": 22 } }, { "key": "6", "meta": { "href": "/api/audit/sessions/1/channels/6" }, "body": { "type": "remote forward", "verdict": "accept", "start_time": 1451902145, "end_time": 1451902146, "duration": 1, "originator.address": "::1", "originator.port": 42212, "connected.address": "localhost", "connected.port": 9898 } }, { "key": "7", "meta": { "href": "/api/audit/sessions/1/channels/7" }, "body": { "type": "x11 forward", "verdict": "deny", "start_time": 1451902149, "end_time": 1451902149, "duration": 0 } } ]
All possible RDP channel types:
"channels": [ { "key": "1", "meta": { "href": "/api/audit/sessions/1/channels/1" }, "body": { "type": "drawing", "verdict": "accept", "start_time": 1451901988, "end_time": 1451902145, "duration": 157 } }, { "key": "2", "meta": { "href": "/api/audit/sessions/1/channels/2" }, "body": { "type": "sound", "verdict": "accept", "start_time": 1451902141, "end_time": 1451902145, "duration": 4 } }, { "key": "3", "meta": { "href": "/api/audit/sessions/1/channels/3" }, "body": { "type": "clipboard", "verdict": "accept", "start_time": 1451902141, "end_time": 1451902145, "duration": 4 } }, { "key": "4", "meta": { "href": "/api/audit/sessions/1/channels/4" }, "body": { "type": "seamless", "verdict": "deny", "start_time": 1451902142, "end_time": 1451902142, "duration": 0 } }, { "key": "5", "meta": { "href": "/api/audit/sessions/1/channels/5" }, "body": { "type": "dynamic virtual", "verdict": "accept", "start_time": 1451902145, "end_time": 1451902146, "duration": 1, "dynamic_channel": "Microsoft::Windows::RDS::Geometry::v08.01" } }, { "key": "6", "meta": { "href": "/api/audit/sessions/1/channels/6" }, "body": { "type": "custom", "verdict": "deny", "start_time": 1451902145, "end_time": 1451902145, "duration": 0 } }, { "key": "7", "meta": { "href": "/api/audit/sessions/1/channels/7" }, "body": { "type": "serial redirect", "verdict": "accept", "start_time": 1451902149, "end_time": 1451902150, "duration": 1, "device_name": "COM1" } }, { "key": "8", "meta": { "href": "/api/audit/sessions/1/channels/8" }, "body": { "type": "parallel redirect", "verdict": "accept", "start_time": 1451902149, "end_time": 1451902150, "duration": 1, "device_name": "LPT1" } }, { "key": "9", "meta": { "href": "/api/audit/sessions/1/channels/9" }, "body": { "type": "printer redirect", "verdict": "accept", "start_time": 1451902149, "end_time": 1451902150, "duration": 1, "device_name": "PRN22" } }, { "key": "10", "meta": { "href": "/api/audit/sessions/1/channels/10" }, "body": { "type": "disk redirect", "verdict": "accept", "start_time": 1451902149, "end_time": 1451902150, "duration": 1, "device_name": "J:" } }, { "key": "11", "meta": { "href": "/api/audit/sessions/1/channels/11" }, "body": { "type": "scard redirect", "verdict": "accept", "start_time": 1451902149, "end_time": 1451902150, "duration": 1, "device_name": "SCARD" } }
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.
Code | Description | Notes |
---|---|---|
201 | Created | The new resource was successfully created. |
400 | InvalidQuery | The requested filter or its value is invalid. |
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. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
404 | NotFound | The requested object does not exist. |
You can download the audit trail of a session from the /api/audit/sessions/<session-id>/audit_trail endpoint. To find a specific audit trail, see Searching in the session database. You can download audit trails that are available on SPS, and also audit trails that have been archived (if SPS can access the archived audit trail).
curl --cookie cookies "https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/audit_trail"
To actually create a file, you must save the downloaded data into a file (use the .zat file extension), for example:
curl --cookie cookies "https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/audit_trail" > my-downloaded-trail.zat
You can replay the downloaded audit trails with the Safeguard Desktop Player application. For details, see Safeguard Desktop Player User Guide.
If you want to replay an ongoing session in follow mode, you have to download the audit trail in .srs format. Use the ?format=srs option:
curl --cookie cookies "https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/audit_trail?format=srs" > my-downloaded-trail.srs
For details, see "Replay audit files in follow mode" in the Safeguard Desktop Player User Guide.
© 2024 One Identity LLC. ALL RIGHTS RESERVED. Feedback Terms of Use Privacy Cookie Preference Center