Chat now with support
Chat with Support

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

Introduction Using the SPS REST API Basic settings User management and access control Managing SPS General connection settings HTTP connections Citrix ICA connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST About us Third-party contributions

Searching in connection content

You can search in the contents of individual connections at the api/audit/sessions/<session-id>/content/?q=<my-search-expression> endpoint.

URL
GET https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/content/?q=<my-search-expression>
Headers
Header 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).

Sample request

The following command retrieves those events in the contents of a specific connection that match the search expression(s).

curl --cookie cookies https://<IP-address-of-SPS>/api/audit/sessions/<session-id>/content/?q=<my-search-expression>

NOTE:

Make sure that you use the ?q option and that when you use it, you do not leave it empty. Not using the ?q option or an empty ?q will result in an empty "items" list returned in the response.

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

  • Do not begin the expression with the * wildcard.

Response

The response contains a list of those events in the contents of the connection that match the search expression(s). The response also contains some meta fields.

If you specified a search expression using the ?q option and the response returns an empty "items" list, that can indicate that:

  • The search returned no results.

  • There is no content recorded for the connection.

The following is an example response:

{
    "items": [
        { 
            "psm.channel.id": 5, 
            "end_time": "2017-08-14T10:35:43.957000", 
            "rank": 2.4756217002868652,
            "record_id": {
                "begin": 158,
                "end": 160,
                "for_screenshot": 158
            },
            "start_time": "2017-08-14T10:35:19.098000", 
            "trail_id": "12" 
        }
    ],
    "meta":
        { 
            "href": "/api/audit/sessions/2a620c1cfeb39c537a5e80280283d741/content", 
            "parent": "/api/audit/sessions/2a620c1cfeb39c537a5e80280283d741", 
            "remaining_seconds": 599 
        }
}
Element Type Description
items list Top-level element, a list containing the details of the matching session.
psm.channel.id integer A reference to the ID of the channel in the session where the event occurred.
end_time string

The timestamp of when the content disappeared from the screen.

Starting with SPS 5 LTS, the timestamp is in ISO 8601 format, for example, 2017-04-11T09:23:38.000+02:00. In earlier versions, it was in UNIX timestamp format.

rank float

Indicates the relevance of the match.

If there are several results, the order of them is based on their relevance.

record_id integer The content element's exact position in the audit trail file.
begin integer The identifier of the screenshot in the audit trail file where the content element first appeared.
end integer The identifier of the screenshot in the audit trail file where the content element last appeared.
for_screenshot integer The identifier of the most relevant screenshot in the audit trail file. This is the screenshot on which the event in question is the most clearly visible.
start_time string

The timestamp of when the content first appeared on the screen and recording started.

Starting with SPS 5 LTS, the timestamp is in ISO 8601 format, for example, 2017-04-11T09:23:38.000+02:00. In earlier versions, it was in UNIX timestamp format.

trail_id integer The unique identifier of the trail that contains the event.

In addition, search results can contain the usual meta elements of other endpoints:

Element Type Description
meta JSON object

Top-level element, a list containing meta information about the response.

For details about the type of information returned, see Introduction.

Related Documents