One Identity Safeguard for Privileged Sessions 6.9.5 - REST API Reference Guide

Filtering

You can use the ?q option to filter the list using one or more property (element) of the sessions.

?q=protocol:ssh

You can escape special characters using the backslash character.

?q=server_username:\"Windows User\"

To add multiple elements to the filter, you can use the AND, AND NOT, and OR operators.

?q=protocol:ssh AND verdict:accept AND NOT name:admin

You can create groups using () (parentheses).

?q=(client.address:10.20.30.40 OR target.address:10.20.30.40) AND verdict:accept

You can also use () (parentheses) to add multiple possible values for a property.

?q=protocol:(ssh rdp)

You can use the * (asterisk) and ? (question mark) wildcards for string-type values.

?q=name:?dmi*

You can define ranges using [] (brackets) or {} (braces) and the TO operator. This only works for numeric (int) values.

• [ means equal or higher than the following value

• ] means equal or lower than the preceding value

• { means higher than the following value

• }means lower than the preceding value

For example, the following range resolves to 22:

?q=port:{21 TO 23}

You can also use the * (asterisk) wildcard in the range.

?q=start_time:[* TO 1461654799]

Note that not all connection data can be used for filtering. The available elements are:

• active

  Boolean, true means the session is ongoing (it is still active).

• auth_method

  String, the authentication method used.

• channel_policy

  String, the key of the channel policy.

• client.address

  String, the IP address of the client.

• client.port

  Integer, the port of the client.

• psm.connection_policy

  String, the key of the connection policy.

• end_time

  The date of the end of the session in ISO 8601 format.

• name

  String, the username used for authenticating against the gateway.

• protocol

  String, the protocol of the session.

• server.address

  String, the IP of the remote server.

• psm.server_local.address

  String, the IP of SPS.

• psm.server_local.port

  String, the port of SPS.

• server.port

  String, the port of the remote server.

• server_username

  String, the username used for authenticating on the remote server.

• session_id

  String, the identifier of the session.

• start_time

  The date of the start of the session in ISO 8601 format.

• target.address

  String, the IP the client targeted in the session.

• target.port

  Integer, the port the client targeted in the session.

• verdict

  String, the connection verdict. Possible values are:

  • accept

    The connection attempt was successful.

  • accept-terminated

    The connection violated a content policy, and was terminated by SPS.

  • auth-fail

    Authentication failure.

  • deny

    The connection was denied.

  • fail

    The connection attempt failed.

  • gw-auth-fail

    Gateway authentication failure.

  • key-error

    The connection attempt failed due to a host key mismatch.

  • user-mapping-fail

    The connection attempt failed due to a user mapping failure.

Content search in indexed audit trails

You can use the ?content option to search for keywords that appear in the content of the audit trails. Such content is any text that appeared on the screen in terminal or graphical sessions, or commands that the user typed in terminal sessions. Note that content search works only if:

• Indexing was enabled in the connection policy related to the audit trail during the session, and

• the audit trail has already been indexed.

?content="my-search-expression"

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 an URL, and escape special characters accordingly. For example, if your search expression is man iptables, you must escape the whitespace: man%20iptables

  For a list of special (reserved) URL characters, see RFC3986.

• Do not begin the expression with the * wildcard.

?content=example

?content=example%3F

?content=exam%2A

curl --cookie cookies "https://<IP-address-of-SPS>/api/audit/sessions?q=protocol:ssh&content=sudo"

Displaying session data

You can use the ?fields option to display the selected data (body elements) of each session.

?fields=protocol

To list multiple elements, use the , (comma) character. Note that the response includes the selected fields in alphabetic order, not in the order they were specified.

?fields=protocol,name

To list all possible elements, use the fields=* expression.

?fields=*

Note that not all connection data can be displayed in the generated list. The available elements are:

• active

  Boolean, true means the connection is ongoing.

• archived

  Boolean, true means the session has been archived.

• auth_method

  String, the authentication method used.

• channel_policy

  String, the key of the channel policy.

• client.address

  String, the IP address of the client.

• client.port

  Integer, the port of the client.

• connection_policy

  String, the key of the connection policy.

• duration

  Integer, the duration of the session. Computed value.

• end_time

  The date of the end of the session in ISO 8601 format.

• name

  String, the username used for authenticating against the gateway.

• protocol

  String, the protocol of the session.

• server.address

  String, the IP of the remote server.

• server_local.address

  String, the IP of SPS.

• server_local.port

  Integer, the port of SPS.

• server.port

  Integer, the port of the remote server.

• server_username

  String, the username used for authenticating on the remote server.

• session_id

  String, the identifier of the session.

• start_time

  The date of the start of the session in ISO 8601 format.

• target.address

  String, the IP the client targeted in the session.

• target.port

  Integer, the port the client targeted in the session.

Date-specific search

To display search results only for specific date intervals, you can use the ?start and ?end options.

• The ?start option selects the sessions that started after the specified date (based on the value of the start_time field).

• The ?end option selects the sessions that ended before the specified date (based on the value of the end_time field).

• Both options accept the date in ISO 8601 format.

?start=2017-01-25T11:11:52.000+01:00
?end=2017-01-25T11:41:52.000+01:00
?start=2017-01-24&end=2017-01-25

?start=2017-01-20

?start=2017-01-20T11:00

?end=2017-01-20

?start=2017-01-20&end=2017-01-20

?start=2017-01-20T11:00&end=2017-01-21T09:00

Sort the results

You can sort the search results using the sort expression, for example, based on the length of the sessions:

?sort=duration

You can use any field to sort the results. By default, sorting returns the results in ascending order, if you use ?sort=duration, then the shortest session is at the beginning of the list. To sort the results in descending order, add the minus sign (-) before the field name. For example, the response to the following expression starts with the longest session:

?sort=-duration

You can specify multiple fields to order the list. In this case, the list is first ordered using the first field, then the second, and so on. For example, to order the list first by duration, then by start time, use the following expression.

?sort=duration,start_time

The following example sorts the results by duration, and displays the start time, gateway username, and duration fields.

curl --cookie cookies "https://<IP-address-of-SPS>/api/audit/sessions?sort=duration&fields=start_time,psm.gateway_username,duration"

Configure the format of the displayed results

The default value of ?format is json. If you do not configure the ?format parameter, the results will be displayed in JSON format.

?format=json

To display search results in a CSV format, enter csv as a value.

?format=csv

{
  "1": {
    "channel": [
      {"channel_id": 1},
      {"channel_id": 2}
    ],
    "recording": {
      "session_id": 1,
      "archived": false,
      "channel_policy": "policy1",
      "content_reference_id": 1,
      "connection_policy": "connection1",
      "auth_method": "password",
      "target": {
        "port": 2222,
        "ip": "1.1.1.1",
        "name": "1.1.1.1"
      },
      "server_local": {
        "port": 46,
        "ip": "1.1.1.1",
        "name": "1.1.1.1"
      }
    },
    "user": {
      "server_username": "user1",
      "gateway_username": "user1"
    },
    "client": {
      "port": 48679,
      "ip": "2.2.2.2",
      "name": "2.2.2.2"
    },
    "active": false,
    "start_time": 1,
    "duration": 4,
    "server": {
      "port": 22,
      "ip": "2.2.2.2",
      "name": "2.2.2.2"
    },
    "end_time": 5,
    "protocol": "ssh"
  },
  "2": {
    "channel": [
      {"channel_id": 3},
      {"channel_id": 4}
    ],
    "recording": {
      "session_id": 2,
      "archived": false,
      "channel_policy": "policy2",
      "content_reference_id": 2,
      "connection_policy": "connection2",
      "auth_method": "password",
      "target": {
        "port": 2222,
        "ip": "1.1.1.1",
        "name": "1.1.1.1"
      },
      "server_local": {
        "port": 46,
        "ip": "1.1.1.1",
        "name": "1.1.1.1"
      }
    },
    "user": {
      "server_username": "user2",
      "gateway_username": "user2"
    },
    "client": {
      "port": 48680,
      "ip": "3.3.3.3",
      "name": "3.3.3.3"
    },
    "active": false,
    "start_time": 1,
    "duration": 4,
    "server": {
      "port": 24,
      "ip": "2.2.2.2",
      "name": "2.2.2.2"
    },
    "end_time": 7,
    "protocol": "ssh"
  }
}

curl --cookie cookies "https://<IP-address-of-SPS>/api/audit/sessions?format=csv&fields=protocol,end_time,user.gateway_username,server.ip,client.ip,client.port"

"Key","Protocol","End time","Gateway username","Server IP","Client IP","Client port"
"2","ssh","7","user2","2.2.2.2","3.3.3.3","48680"
"1","ssh","5","user1","2.2.2.2","2.2.2.2","48679"

{
  "1":{
    "origin": "RECORDING",
    "protocol": "SSH",
    "analytics": {
      "interesting_events": ["ssh", "sudo"],
      "similar_sessions": []
    },
    "recording": {
      "session_id": "1",
      "verdict": "ACCEPT",
      "audit_trail": "/var/lib/zorp/audit/532078660569910c6542b2/01/audit-scb_ssh-1451900800-1.zat",
      "connection_policy": "ssh1",
      "content_reference_id": 1
    }
  },
  "2":{
    "origin": "RECORDING",
    "protocol": "SSH",
    "analytics": {
      "interesting_events": ["sudo", "systemctl"],
      "similar_sessions": []
    },
    "recording": {
      "session_id": "2",
      "verdict": "ACCEPT",
      "connection_policy": "ssh2",
      "content_reference_id": 2
    }
  }
}

curl --cookie cookies "https://<IP-address-of-SPS>/api/audit/sessions?sort=recording.session_id&format=csv&fields=recording.session_id,analytics.interesting_events,analytics.similar_sessions"

"Key","Recording Session ID","Analytics Interesting events","Similar Sessions"
"1","1","ssh",""
"1","1","sudo",""
"2","2","sudo",""
"2","2","systemctl",""

{
  "svc-paKzcMJwXghEFJ9UvsdqFU-sid-1": {
    "origin": "RECORDING",
    "protocol": "SSH",
    "recording": {
      "session_id": "1",
      "verdict": "ACCEPT",
      "audit_trail": "/var/lib/zorp/audit/532078660569910c6542b2/01/audit-scb_ssh-1451900800-1.zat",
      "connection_policy": "ssh1",
      "content_reference_id": 1
    }
  },
  "svc-paKzcMJwXghEFJ9UvsdqFU-sid-2": {
   "origin": "RECORDING",
    "protocol": "SSH",
    "recording": {
      "session_id": "2",
      "verdict": "ACCEPT",
      "connection_policy": "ssh2",
      "content_reference_id": 2
    }
  }
}

curl --cookie cookies "https://<IP-address-of-SPS>/api/audit/sessions?format=csv&fields=trail_download_link"

"Key","Audit trail download link"
"svc-paKzcMJwXghEFJ9UvsdqFU-sid-2",""
"svc-paKzcMJwXghEFJ9UvsdqFU-sid-1","https://127.0.0.1/api/audit/sessions/svc-paKzcMJwXghEFJ9UvsdqFU-sid-1/audit_trail"