API v2: Sessions management¶

Data structures¶

Note

The following data structure contains read-only fields for retrieving session data.

`SessionsModel`¶
Parameter	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
paused	boolean
retention_locked	boolean
indexed	number
-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	string	Datetime of the record creation
modified_at	string	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`

`SessionsMLModel`¶
Parameter	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

`SessionBackupAssignmentModel`¶
Parameter	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

Allowed methods

`GET`	for reading data of an existing object; no request body is required
`POST`	for creating an object; requires a request body, specified in JSON format, that contains the values for properties of the object that is about to be created
`PATCH`	for modifying an existing object; requires a request body, specified in JSON format, that contains the values for properties of the object
`DELETE`	for removing an existing object; no request body is required

There is a list of URL parameters available for a specific method to be included within a path:

fields - for including the object fields in the query,

filter - narrows out the result with available additions:

in - include possible field values (separated with comma),

match - include a sequence of characters to be searched in field values,

eq - equal,

ne - not equal,

lt - less than,

le - less or equal,

gt - greater than,

ge - greater than or equal

blocked - filter blocked objects,

!blocked - filter unblocked objects,

isempty() - filter objects with empty values in specified fields, only applies to arrays (e.g., server.isnull()),

order,

offset,

limit,

debug - for showing statistics, database errors, etc,

total_count,

reveal - to see objects: active, removed, or all for both removed and un-removed.

An example of the request that shows a list of 10 users that have a role user with their id and name specified, sorted alphabetically by their names and shows a total count of users that match the given criteria: GET https://<fudo_address>/api/v2/user?fields=id,name&filter=role.eq(user)&order=name&limit=10&total_count

Possible responses

Code	Status
`200`	success	`OK`
`201`	success	`CREATED`
`400`	failure	`BAD REQUEST`; message examples: `Unrecognized endpoint`, `Request body is not allowed for this endpoint`
`401`	failure	`UNAUTHORIZED`
`404`	failure	`BAD REQUEST`; message example: `Object not found`

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 sessions list¶

Request

Method	GET
Path	/api/v2/session

Retrieving a session¶

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"
}}

Modifying a session¶

Request

Method	PATCH
Path	/api/v2/session/<id>

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"
        ]
}