Search Control#

REST API located at /api/searchctrl

The searchctrl group is used to query information about persistent searches and optionally invoke some action. We currently provide the ability to query all active searches, get information about a specific search, background a an active search, archive an active search, and delete/terminate a search.

Basic API overview#

The basic action here is to perform a GET, DELETE, or PATCH on a REST url.

Search States#

Searches can be in any of the following states, and can be in more than one state at a time (such as ACTIVE/BACKGROUNDED, SAVED/ATTACHED, or DORMANT/SAVED).

  • Active: The search is running and/or finished and there is a session attached to it.

  • Backgrounded: The search is actively running but marked in a way that it will persist without an attached session.

  • Saving: The search has been marked as saved, but is still waiting for completion to move its contents to a persistent location.

  • Saved: The search is marked as saved and moved to the appropriate persistent location.

  • Dormant: The search is being kept (background or saved) and no sessions are attached.

  • Attached: The search is saved and a session has re-attached to it.

Getting a list of searches#

When requesting the list of searches the web server will return all searches the current user is authorized to view. No json package is posted, but rather an empty GET is performed against ‘/api/searchctrl’.

[
        {
                "ID": "181382061",
                "UID": 1,
                "GID": 0,
                "State": "ACTIVE",
                "AttachedClients": 1
        },
        {
                "ID": "010985768",
                "UID": 1,
                "GID": 0,
                "State": "BACKGROUNDED",
                "AttachedClients": 0
        },
        {
                "ID": "795927171",
                "UID": 1,
                "GID": 0,
                "State": "DORMANT",
                "AttachedClients": 0
        }
]

Importing a saved search archive#

An optional download format for a search is an archive. An archive represents a fully self-contained search that can be imported into another Gravwell instance. The import API accepts the saved search archives as an upload and unpacks the search into the saved search system. Users can then attach to the search as if it were saved on the local system.

When a search archive is re-imported, the imported search is owned by the user that imported it, regardless of which user downloaded it. An optional GID form field may be supplied in the import request to share the imported search with a group.

Searches are imported by performing a multipart form POST to the /api/searchctrl/import URL.

The API expects that the file upload be in the form field called file.

The import API can be authenticated using either the JWT authorization token or a cookie.

Note

An admin can specify groups it is not a member of in the GID form field, but non-admin users must be a member of the group specified in GID.

Admin APIs#

Admin users can get information about any search, delete any search, load any search, send any search to the background, etc. using the API endpoints documented above.

List all searches#

In order to get a list of all searches that exist on the system, an admin user may do a GET on /api/searchctrl/all. The format is identical to that returned from /api/searchctrl, but includes all searches on the system.

[
    {
        "AttachedClients": 0,
        "GID": 0,
        "ID": "486574780",
        "State": "DORMANT",
        "StoredData": 9355,
        "UID": 1
    },
    {
        "AttachedClients": 0,
        "GID": 0,
        "ID": "815623546",
        "State": "DORMANT",
        "StoredData": 3536,
        "UID": 4
    },
    {
        "AttachedClients": 0,
        "GID": 0,
        "ID": "525125903",
        "State": "DORMANT",
        "StoredData": 0,
        "UID": 7
    },
    {
        "AttachedClients": 0,
        "GID": 0,
        "ID": "274379984",
        "State": "DORMANT",
        "StoredData": 319,
        "UID": 4
    }
]