TrackMe REST API

TrackMe provides a deep REST API that allows interracting with any of its components, in fact, all interactions from the user interfaces deal with TrackMe’s REST API endpoints.

Hint

Since the version 2.0.34, TrackMe implements a strict least privileges approach:

  • Endpoints are eventually (depending on the resource group) separated in 3 groups per resource groups, user level endpoints, write level endpoints and admin level endpoints

  • According to the RBAC configuration, a given user may not be granted access to write and admin endpoints if the user is a normal user, or the user may not be granted access to the admin endpoints if the user is power user

  • These are driven by TrackMe’s builtin Splunk capabilities which can be granted to a given Splunk role, by membership or inheritance (see: Role Based Access Control and ownership)

The following table summarizes TrackMe’s builtin roles, associates capabilities, endpoints accesses and privileges categories:

TrackMe builtin Roles and Capabilities

Role

Capability

Endpoints root

Description

trackme_user

trackmeuseroperations

all but write and admin

allows read only access in TrackMe

trackme_power

trackmepoweroperations

*/write

allows management of TrackMe entities but not the creation of new content (such as trackers)

trackme_admin

trackmeadminoperations

*/admin

allows content management such as the creation of tenants and trackers

REST API reference

TrackMe comes with a REST API reference user interface which allows you to navigate through the available API endpoints categorized by resource groups:

Go to Navigation bar / API & Tooling / TrackMe REST API Reference:

screen1.png

REST API resource groups

At the top level, TrackMe REST API endpoints are categorized by resource groups:

screen2.png

TrackMe has a concept of automatic discovery of the REST API endpoints and their documentation, for this, we leverage a custom command:

| trackmeapiautodocs
screen3.png

The custom command trackmeapiautodocs automatically discovers REST API endpoints and extract their documentation such as the endpoint URI, the expected HTTP mode, options available for that endpoint and the example of use in SPL:

To list all resource groups, you can use the following SPL command:

| trackmeapiautodocs target="groups" | table resource_group, resource_desc | sort 0 resource_group

To retrieve the list of API endpoints and their detail, you can use the following SPL command:

Example:

| trackmeapiautodocs target="endpoints" | search resource_group="splk_hybrid_trackers"
screen4.png

REST API logging access

Any activity of the REST API endpoints is carefully logged, consult REST API endpoints logging

REST API audit

Any endpoint performing a change in TrackMe, such as deleting an entity, leads to the generation of one or more audit events from that endpoint.

For instance, you can search for all audit events for a given Virtual Tenant:

index=trackme_audit tenant_id=mytenant

REST API usage example in Splunk

REST API endpoints can therefore be used programmatically for any kind of action, within Splunk using the trackme REST API wrapper custom command, and externally using any program of your choice, from curl to Postman and others.

For instance, the usage for retrieving the details of existing Virtual Tenants:

| trackme url="/services/trackme/v2/vtenants/show_tenants" mode="get"
screen5.png

This other example would create a brand new virgin Virtual Tenant for splk-dsm:

| trackme url="/services/trackme/v2/vtenants/admin/add_tenant" mode="post" body="{ 'tenant_desc': 'Demo tenant', 'tenant_name': 'mytenant', 'tenant_roles_admin': 'trackme_admin', 'tenant_roles_user': 'trackme_user', 'tenant_owner': 'admin', 'tenant_idx_settings': 'global', 'tenant_dsm_enabled': 'true', 'tenant_dsm_sampling_obfuscation': 'disabled', 'update_comment': 'Created for the purpose of the documentation.'}"
screen6.png

The following example deletes that same Virtual Tenant we’ve created:

| trackme url=/services/trackme/v2/vtenants/admin/del_tenant mode=delete body="{ 'tenant_id': 'mytenant', 'force': 'true'}"
screen7.png

Audit messages are generated and indexed in the Virtual Tenant audit index:

index=trackme_audit tenant_id=mytenant
screen8.png

REST API usage example outside of Splunk

Authenticating to the Splunk API

Using a bearer token:

The best approach for using the Splunk REST API is to rely on a bearer token to authenticate and access to splunkd:

See: Splunk docs JSON authentication token

Once you have created an authentication token for the user to be used as the service account, using curl specify the bearer token:

curl -k –H "Authorization: Bearer <token>"

Using basic authentication:

You can also use basic authentication and authenticate to the Splunk API using a username and a password:

curl -k -u admin:'ch@ngeM3'

Generating an API token:

A last method, but less common since the bearer token were introduced, is to authenticate using basic authentication and retrieve an API token which will be used for the REST calls purposes.

See: Splunk docs API token

Example:

curl -k https://localhost:8089/services/auth/login --data-urlencode username=svc_splunk --data-urlencode password=pass

<response>
  <sessionKey>DWGNbGpJgSj30w0GxTAxMj8t0dZKjvjxLYaP^yphdluFN_FGz4gz^NhcgPCLDkjWH3BUQa1Vewt8FTF8KXyyfI09HqjOicIthMuBIB70dVJA8Jg</sessionKey>
  <messages>
    <msg code=""></msg>
  </messages>
</response>

export token="DWGNbGpJgSj30w0GxTAxMj8t0dZKjvjxLYaP^yphdluFN_FGz4gz^NhcgPCLDkjWH3BUQa1Vewt8FTF8KXyyfI09HqjOicIthMuBIB70dVJA8Jg"

A token remains valid for the time of a session. (1 hour by default)

The token would be used as following:

curl -k -H "Authorization: Splunk $token"

Using the REST API from the outside with curl

Consider the following REST API usage example in SPL:

| trackme url="/services/trackme/v2/vtenants/trackmeload" mode="post" body={\"mode\": \"full\"}

Using curl, it could be translated into:

curl -u admin https://localhost:8089/services/trackme/v2/vtenants/trackmeload -X POST -d '{"mode": "full"}'

Hint

JSON format

  • Note that the trackme SPL command understands JSON submitted with both single or double quotes, however when using a REST API endpoint from the outside of Splunk, you must submit a proper JSON object with double quotes.