API v2: Sessions Management¶
Data Structures¶
Note
The following data structure contains read-only
fields for retrieving session data.
Attribute | Type | Description |
---|---|---|
id | string | Object Identifier |
leader_session_id | string | Object Identifier |
account_id | string | Account’s Identifier, which was used for connection |
listener_id | string | Listener’s Identifier, which was used for connection |
safe_id | string | Safe’s Identifier, which was used for connection |
server_id | string | Server’s Identifier, which was used for connection |
user_id | string | User’s Identifier, which was used for connection |
started_at | string | Datetime of the session’s start |
finished_at | string | Datetime of the session’s end |
handled_by | string | Object Identifier |
marked_safe_by | string | |
terminate_at | string | Datetime of the session’s termination |
dump_mode | string {all, none, raw, noraw} | Session recording options |
protocol | string{http, modbus, mysql, rdp, ssh, system, tcp, tds, telnet, tn3270, tn5250, vnc} | Used protocol for connection |
source_ip | string | Source IP address |
source_port | number | Port of the source IP address |
destination_ip | string | Destination IP address |
destination_port | number | Port of the destination IP address |
destination_address | string | Expensive. Concatenated destination IP and port. |
paused | boolean | |
retention_locked | boolean | |
indexed | number | Session indexing status. Values: 0 = Waiting, 1 = Error, 2 = Indexed. Session is indexed when value is 2. |
trusted_timestamp | string | |
size | number | |
reason | string | Reason of the session’s termination or rejection |
status | string {approved, disconnected, expired, rejected, terminated, waiting} | |
active_time | number | |
ml (Machine Learning) | SessionsMLModel | |
pending_delete | boolean | |
password_change | boolean | |
checkout_forced | boolean | |
created_at | datetime | Datetime of the record creation |
modified_at | datetime | Datetime of the record modification |
removed | boolean | |
login_reason | string | Reason for user’s connection |
bits_per_pixel | string | Resolution options |
height | string | Resolution options |
width | string | Resolution options |
command | string | Given command during a session |
type | string | Session’s type |
subsystem | string | For example, sftp |
user_name | string | Expensive. User name who created session. |
user_removed | boolean | Expensive. User is removed. |
user_organization | string | Expensive. User organization who created session. |
account_name | string | Expensive. Account name. |
account_removed | boolean | Expensive. Account is removed. |
server_name | string | Expensive. Server name. |
server_removed | boolean | Expensive. Server is removed. |
safe_name | string | Expensive. Safe name. |
safe_removed | boolean | Expensive. Safe is removed. |
listener_name | string | Expensive. Listener name. |
listener_removed | boolean | Expensive. Listener is removed. |
secret_exposure_state | string {user_blocked, user_removed, user_lost_access, seen} | Expensive. State of user who checked out the current account password. Value ‘seen’ means that user has seen password and have access to it. |
ocred | boolean | Expensive. Session texts were ocred. |
availibility | string {archived, available, downloading, missing, unknown} | Expensive. Session availability. |
created_on | string | Expensive. The serial number of the node where the session was created. |
replicated_on_nodes | string | Expensive. Session has been replicated on nodes (serial numbers). |
duration | number | Expensive. Session duration in seconds. |
activity | number | Expensive. Session active time in percents. |
time_limit | number | Expensive. Time in seconds remaining until the session is terminated. Value is available only when terminate_at defined. Value 0 means session is finished or terminated. |
Attribute | Type | Description |
---|---|---|
ml_threat_level | number | Detected threat level |
ml_threat_level_min | number | Min threat level value |
ml_threat_level_max | number | Max threat level value |
ml_converted_at | string | Datetime of the session’s processing |
ml_finished_at | string | End datetime of the session’s processing |
Request for Retrieving Available Attributes of the SessionsModel
Method | GET
|
Path | /api/v2/objspec/session
|
Attribute | Type | Description |
---|---|---|
session_id | string | ID of the session to backup. Requires backup_id: {} or backup_name: {} . |
session_ids | string-array | IDs of the sessions to backup. Requires backup_id: {} or backup_name: {} . |
backup_id | string | ID of the backup target. Requires session_id: {} or session_ids: {} . |
backup_name | string | Name of the backup target. Requires session_id: {} or session_ids: {} . |
Request for Retrieving Available Attributes of the SessionBackupAssignmentModel
Method | GET
|
Path | /api/v2/objspec/session_backup
|
Note
To check allowed methods, available URL parameters and possible responses please refer to the API Overview section.
The next chapter describes procedures for creating separate requests.
Refer to the Batch operations topic to create nested requests for operating on the Sessions objects.
Retrieving a Session by ID¶
Request
Method | GET
|
Path | /api/v2/session/<id>
|
Example Request
Sending GET https://10.0.0.0/api/v2/session/41234678819172646916
{
"result": "success",
"session": {
"id": "3927138875067084301",
"leader_session_id": "3927138875067084301",
"listener_id": "3927138875067073099",
"user_id": "3927138875067072685",
"safe_id": "3927138875067072584",
"account_id": "3927138875067088645",
"server_id": "3927138875067072586",
"started_at": "2022-04-05 16:06:07.313862+02",
"finished_at": "2022-04-05 16:07:58.65701+02",
"dump_mode": "all",
"protocol": "vnc",
"source_ip": "10.2.0.0",
"source_port": 65331,
"destination_ip": "10.0.0.1",
"destination_port": 5900,
"paused": false,
"retention_locked": false,
"indexed": 2,
"size": 371712,
"status": "approved",
"active_time": 60,
"password_change": false,
"checkout_forced": false,
"created_at": "2022-04-05 16:06:07.316523+02",
"modified_at": "2022-04-08 08:16:02.009606+02",
"height": "768",
"width": "1024"
}}
Mark Existing Session for Back Up¶
Request
Method | POST
|
Path | /api/v2/session/<session_id>/backup/<backup_id>
|
Example Request
Sending POST https://10.0.0.0/api/v2/session/2345678901234567890/backup/12345617890123456789
Request
Method | POST
|
Path | /api/v2/session_backup
|
Headers | Content-Type: Application/JSON
|
Body | SessionBackupAssignmentModel
|
Example Request
Sending POST https://10.0.0.0/api/v2/session_backup
{
"backup_name": "Backup_Target_Name",
"session_ids": [
"2345678901234567890",
"2345678901234567891"
]
}
Response
{
"result": "success",
"session_ids": [
"2345678901234567890",
"2345678901234567891"
]
}
Deleting Session¶
Request
Method | DELETE
|
Path | /api/v2/session/<id>
|
Example Request
Sending DELETE https://10.0.0.0/api/v2/session/9124292845052624897
curl -s -k -X DELETE -H 'Authorization: vg1ei6rgo58fsbobr7octp0w3afd9vsm' https://10.0.214.98/api/v2/session/9124292845052624897
Response
{
"result": "success"
}