Get Session

curl --request GET \
  --url https://use.hoop.dev/api/sessions/{session_id}

{
  "ai_analysis": {
    "action": "allow_execution",
    "explanation": "The script contains queries that may expose sensitive data.",
    "risk_level": "high",
    "title": "Potential Data Leakage"
  },
  "connection": "pgdemo",
  "connection_subtype": "postgres",
  "connection_tags": {
    "team": "banking;environment:prod"
  },
  "correlation_id": "task-12345",
  "end_date": "2024-07-25T15:56:35.361101Z",
  "event_size": 569,
  "event_stream": [
    123
  ],
  "exit_code": 123,
  "guardrails_info": [
    {
      "direction": "input",
      "matched_words": [
        "password",
        "secret"
      ],
      "rule": {
        "pattern_regex": "^[A-Z0-9]+",
        "type": "deny_words_list",
        "words": [
          "password",
          "secret"
        ]
      },
      "rule_name": "block-sensitive-data"
    }
  ],
  "id": "1CBC8DB5-FBF8-4293-8E35-59A6EEA40207",
  "identity_type": "user",
  "integrations_metadata": {},
  "labels": {},
  "machine_identity_id": "BF997324-5A27-4778-806A-41EE83598494",
  "metadata": {},
  "metrics": {},
  "org_id": "0CD7F941-2BB8-4F9F-93B0-11620D4652AB",
  "resource_name": "my-resource",
  "review": {
    "access_duration": 0,
    "access_request_rule_name": "default-access-request-rule",
    "created_at": "2024-07-25T15:56:35.317601Z",
    "force_approval_groups": [
      "sre-team"
    ],
    "id": "9F9745B4-C77B-4D52-84D3-E24F67E3623C",
    "min_approvals": 2,
    "rejection_reason": "This command is not allowed in production.",
    "review_groups_data": [
      {
        "forced_review": false,
        "group": "sre",
        "id": "20A5AABE-C35D-4F04-A5A7-C856EE6C7703",
        "review_date": "2024-07-25T19:36:41Z",
        "reviewed_by": {
          "email": "john.wick@bad.org",
          "id": "D5BFA2DD-7A09-40AE-AFEB-C95787BA9E90",
          "name": "John Wick",
          "slack_id": "U053ELZHB53"
        },
        "status": "APPROVED"
      }
    ],
    "revoke_at": "",
    "time_window": {
      "configuration": {
        "end_time": "18:00",
        "start_time": "09:00"
      },
      "type": "time_range"
    }
  },
  "role_name": "pgdemo",
  "script": {
    "data": "SELECT NOW()"
  },
  "script_size": 12,
  "session_batch_id": "batch-abc-123",
  "start_date": "2024-07-25T15:56:35.317601Z",
  "type": "database",
  "user": "<string>",
  "user_id": "nJ1xV3ASWGTi7L8Y6zvnKqxNlnZM2TxV1bRdc0706vZ",
  "user_name": "John Wick"
}

Sessions

Get Session

Get a session by id. This endpoint returns a conditional response

When the query string extension is present it will return a payload containing a link to download the session

{
  "download_url": "http://127.0.0.1:8009/api/sessions/<id>/download?token=<token>&extension=csv&newline=1&event-time=0&events=o,e",
  "expire_at": "2024-07-25T15:56:35.317601Z",
}

Fetching the endpoint without any query string returns the payload documented for this endpoint
The attribute event_stream will be rendered differently if the request contains the query string event_stream with the values utf8 or base64.

{
  (...)
  "event_stream": ["hello world"]
  (...)
}

The attribute metrics contains the following structure:

{
  "data_masking": {
    "err_count": 0,
    "info_types": {
      "EMAIL_ADDRESS": 1
    },
    "total_redact_count": 1,
    "transformed_bytes": 31
  },
  "event_size": 356
}

GET

sessions

{session_id}

Get Session

curl --request GET \
  --url https://use.hoop.dev/api/sessions/{session_id}

{
  "ai_analysis": {
    "action": "allow_execution",
    "explanation": "The script contains queries that may expose sensitive data.",
    "risk_level": "high",
    "title": "Potential Data Leakage"
  },
  "connection": "pgdemo",
  "connection_subtype": "postgres",
  "connection_tags": {
    "team": "banking;environment:prod"
  },
  "correlation_id": "task-12345",
  "end_date": "2024-07-25T15:56:35.361101Z",
  "event_size": 569,
  "event_stream": [
    123
  ],
  "exit_code": 123,
  "guardrails_info": [
    {
      "direction": "input",
      "matched_words": [
        "password",
        "secret"
      ],
      "rule": {
        "pattern_regex": "^[A-Z0-9]+",
        "type": "deny_words_list",
        "words": [
          "password",
          "secret"
        ]
      },
      "rule_name": "block-sensitive-data"
    }
  ],
  "id": "1CBC8DB5-FBF8-4293-8E35-59A6EEA40207",
  "identity_type": "user",
  "integrations_metadata": {},
  "labels": {},
  "machine_identity_id": "BF997324-5A27-4778-806A-41EE83598494",
  "metadata": {},
  "metrics": {},
  "org_id": "0CD7F941-2BB8-4F9F-93B0-11620D4652AB",
  "resource_name": "my-resource",
  "review": {
    "access_duration": 0,
    "access_request_rule_name": "default-access-request-rule",
    "created_at": "2024-07-25T15:56:35.317601Z",
    "force_approval_groups": [
      "sre-team"
    ],
    "id": "9F9745B4-C77B-4D52-84D3-E24F67E3623C",
    "min_approvals": 2,
    "rejection_reason": "This command is not allowed in production.",
    "review_groups_data": [
      {
        "forced_review": false,
        "group": "sre",
        "id": "20A5AABE-C35D-4F04-A5A7-C856EE6C7703",
        "review_date": "2024-07-25T19:36:41Z",
        "reviewed_by": {
          "email": "john.wick@bad.org",
          "id": "D5BFA2DD-7A09-40AE-AFEB-C95787BA9E90",
          "name": "John Wick",
          "slack_id": "U053ELZHB53"
        },
        "status": "APPROVED"
      }
    ],
    "revoke_at": "",
    "time_window": {
      "configuration": {
        "end_time": "18:00",
        "start_time": "09:00"
      },
      "type": "time_range"
    }
  },
  "role_name": "pgdemo",
  "script": {
    "data": "SELECT NOW()"
  },
  "script_size": 12,
  "session_batch_id": "batch-abc-123",
  "start_date": "2024-07-25T15:56:35.317601Z",
  "type": "database",
  "user": "<string>",
  "user_id": "nJ1xV3ASWGTi7L8Y6zvnKqxNlnZM2TxV1bRdc0706vZ",
  "user_name": "John Wick"
}

Path Parameters

session_id

string

required

The id of the resource

Query Parameters

event-time

enum<string>

default:0

Construct the file content adding the event time as prefix when parsing each event

Available options:

0,

1

event_stream

enum<string>

Parse available options for the event stream

utf8 - parse the session output (o) and error (e) events as utf-8 content in the session payload
base64 - parse the session output (o) and error (e) events as base64 content in the session payload
raw-queries - encode each event stream parsing the input of queries based on the database wire protocol (available databases: postgres)

Available options:

utf8,

base64,

raw-queries

events

string[]

Choose the type of events to include

i - Input (stdin)
o - Output (stdout)
e - Error (stderr)

expand

enum<string>

Expand the given attributes

Available options:

event_stream,

session_input

extension

string

The file extension to donwload the session as a file content.

csv - it will parse the content to format in csv format
json - it will parse the content as a json stream.
<any-format> - No special parsing is applied

new_line

enum<string>

default:0

Construct the file content adding a break line when parsing each event

Available options:

0,

1

Response

ai_analysis

object

The AI analysis of the session if it's available

Show child attributes

connection

string

The connection name of this resource (it will be deprecated in favor of RoleName)

Example:

"pgdemo"

connection_subtype

string

The subtype of the connection

Example:

"postgres"

connection_tags

object

The tags of the connection resource

Show child attributes

Example:

{ "team": "banking;environment:prod" }

correlation_id

string

External workflow/task identifier that groups sessions belonging to the same logical run

Example:

"task-12345"

end_date

string

When the execution ended. A null value indicates the session is still running

Example:

"2024-07-25T15:56:35.361101Z"

event_size

integer

The stored resource size in bytes. When any parsing is applied to the request the value display the computed parsed size. The pre-computed size will be available in the attribute metrics.event_size

Example:

569

event_stream

integer[]

The stream containing the output of the execution in the following format

[[0.268589438, "i", "ZW52"], ...]

<event-time> - relative time in miliseconds to start_date
<event-type> - the event type as string (i: input, o: output e: output-error)
<base64-content> - the content of the session encoded as base64 string

exit_code

integer

The Linux exit code if it's available

guardrails_info

object[]

read-only

GuardRailsInfo contains information about guardrail rules that matched during the session. A non-empty list indicates the session was blocked by at least one guardrail rule.

Show child attributes

string<uuid>

The resource unique identifier

Example:

"1CBC8DB5-FBF8-4293-8E35-59A6EEA40207"

identity_type

enum<string>

The type of identity that created this session

user - a human user
machine - a machine identity (non-human identity)

Available options:

user,

machine

Example:

"user"

integrations_metadata

object

Metadata attributes related to integrations with third party services

Show child attributes

labels

object

DEPRECATED in flavor of metrics and metadata

Show child attributes

machine_identity_id

string<uuid>

The machine identity ID if this session was created by a machine identity

Example:

"BF997324-5A27-4778-806A-41EE83598494"

metadata

object

Show child attributes

metrics

object

Refactor to use a struct

Show child attributes

org_id

string<uuid>

The organization unique identifier

Example:

"0CD7F941-2BB8-4F9F-93B0-11620D4652AB"

resource_name

string

The resource name associated with this connection

Example:

"my-resource"

review

object

Review of this session. In case the review doesn't exist this field will be null

Show child attributes

role_name

string

The role name (same as connection name)

Example:

"pgdemo"

script

object

The input of the session. This value is only set for the verb exec

Show child attributes

Example:

{ "data": "SELECT NOW()" }

script_size

integer

The input size of the session in bytes

Example:

12

session_batch_id

string

Batch identifier to group sessions that were executed simultaneously

Example:

"batch-abc-123"

start_date

string

When the execution started

Example:

"2024-07-25T15:56:35.317601Z"

status

enum<string>

Status of the resource

ready - the resource is ready to be executed, after being approved by a user
open - the session started and it's running
done - the session has finished

Available options:

open,

ready,

done

type

string

The connection type of this resource

Example:

"database"

user

string

The user email of the resource

user_id

string

The user subject identifier of the resource

Example:

"nJ1xV3ASWGTi7L8Y6zvnKqxNlnZM2TxV1bRdc0706vZ"

user_name

string

The user display name of this resource

Example:

"John Wick"

verb

enum<string>

Verb is how the client has interacted with this resource

exec - Is an ad-hoc shell execution
connect - Interactive execution, protocol port forwarding or interactive shell session

Available options:

connect,

exec

Retry RDP PII analysis Download Session

⌘I