Merge branch 'version_1231' into testing

docs/releasenotes.rst

@@ -15,11 +15,14 @@ This is a new main release branch, TrackMe 1.2.x requires the deployment of the
 TrackMe requires a summary index (defaults to trackme_summary) and a metric index (defaults to trackme_metrics):
 https://trackme.readthedocs.io/en/latest/configuration.html
 
+- Feature: Introducing the trackme REST API wrapper SPL command, allows interracting with the TrackMe REST API endpoints within SPL queries!
+- Feature: Introducing the smart status REST API endpoints, performs advanced status correlations and investigations easily and automatically, within the UI, as part of an alert action or within your third party automation!
 - Feature: REST API endpoint for Data Sampling - allow rest and run sampling
 - Fix - Issue #217 - Activity alerts view results link would result to 404 page not found for out of the box alerts
 - Fix - Issue #218 - Data sampling - creating custom rule from main then clicking on back leads to wrong window
 - Fix - Issue #219 - Outliers detection - dropdown for alert on upper is not pref-filled with the actual setting of the entity
 - Fix - Issue #220 - Audit scheduling - in some environments, status=success is replaced it search time by completed (internal scheduler) which is not expected by the searches
+- Fix - Issue #221 - Data sources - Tags are not preserved following actions in the UI
 - Change: Icons change
 
 Version 1.2.30

docs/rest_api_reference.rst

@@ -42,6 +42,46 @@ These resource groups are accessible by specific endpoint paths as following:
 
 These endpoints can be used to interract with TrackMe in a programmatic fashion, for instance to perform integration tasks with automation systems.
 
+REST API trackme SPL command
+----------------------------
+
+Interracting with the REST API in SPL queries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TrackMe provides a Python based custom command ``trackme`` that acts as a REST API wrapper to interract with the API endpoints.
+
+.. image:: img/img_rest_api_wrapper1.png
+   :alt: img_rest_api_wrapper1.png
+   :align: center
+
+Syntax
+''''''
+
+::
+
+    | trackme url=<API endpoint> mode=<HTTP method: get/post/delete> body=<Optional: provides the HTTP body in a json format>
+
+**Arguments:**
+
+- ``url``: (required) describes the API endpoint url, such as ``/services/trackme/v1/smart_status/ds_smart_status``
+- ``mode``: (required) the HTTP mode, valid options are ``get``, ``post``, ``delete``
+- ``body``: the http body, optional for a get query depending on the endpoint, required for post and delete calls
+
+Example
+'''''''
+
+*This example calls the smart_status endpoint for a target data_source:*
+
+::
+
+    | trackme url=/services/trackme/v1/smart_status/ds_smart_status mode=get body="{'data_name': 'firewall:pan:traffic'}"
+
+.. image:: img/img_rest_api_wrapper2.png
+   :alt: img_rest_api_wrapper2.png
+   :align: center
+
+Every endpoint described in the present REST API reference documentation can be actioned via the trackme custom command, authentication and capabilities are transparently inherited from the user environment running the SPL query.
+
 Authentication
 --------------
 

trackme/bin/trackme.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python
+# coding=utf-8
+
+# REST API SPL handler for TrackMe, allows interracting with the TrackMe API endpoints with get / post / delete calls
+# See: https://trackme.readthedocs.io/en/latest/rest_api_reference.html
+
+from __future__ import absolute_import, division, print_function, unicode_literals
+
+import os
+import sys
+import splunk
+import splunk.entity
+import requests
+import json
+import re
+import time
+
+splunkhome = os.environ['SPLUNK_HOME']
+sys.path.append(os.path.join(splunkhome, 'etc', 'apps', 'trackme', 'lib'))
+
+from splunklib.searchcommands import dispatch, GeneratingCommand, Configuration, Option, validators
+import rest_handler
+import splunklib.client as client
+
+
+@Configuration(distributed=False)
+
+class TrackMeRestHandler(GeneratingCommand):
+
+    # url and mode are required arguments of the SPL command
+    url = Option(require=True)
+    mode = Option(require=True)
+    # body is optional and required for post and delete calls
+    body = Option(require=False)
+
+    def generate(self, **kwargs):
+
+        if self.url and self.mode in ("get", "post", "delete"):
+
+            # Get the session key
+            session_key = self._metadata.searchinfo.session_key
+
+            # Get splunkd port
+            entity = splunk.entity.getEntity('/server', 'settings',
+                                                namespace='trackme', sessionKey=session_key, owner='-')
+            splunkd_port = entity['mgmtHostPort']
+
+            # build header and target
+            header = 'Splunk ' + str(session_key)
+            target_url = "https://localhost:" + str(splunkd_port) + str(self.url)
+
+            # prepare the body data, if any
+            json_data = None
+            if self.body:
+                json_data = json.dumps(json.loads(self.body.replace("\'", "\""), strict=False), indent=1)
+
+            # Run http request
+            response_data = None
+
+            # Get
+            if self.mode in ("get"):
+                if self.body:
+                    response = requests.get(target_url, headers={'Authorization': header}, verify=False, data=json_data)
+                else:
+                    response = requests.get(target_url, headers={'Authorization': header}, verify=False)                    
+
+            # Post (body is required)
+            elif self.mode in ("post"):
+                response = requests.post(target_url, headers={'Authorization': header}, verify=False, data=json_data)
+
+            # Delete (body is required)
+            elif self.mode in ("delete"):
+                response = requests.delete(target_url, headers={'Authorization': header}, verify=False, data=json_data)
+
+            # yield data
+
+            # parse if response is a proper json, otherwise returns as string
+            try:
+                response_data = json.loads(json.dumps(response.json(), indent=1))
+            except Exception as e:
+                # Response is not json, let's parse and make it a json answer
+                response_data = str(response.content)
+                response_data = re.sub('^b\'', '', response_data)
+                response_data = re.sub('\'$', '', response_data)
+                response_data = "{\"response\": \"" + str(response_data.replace("\"", "\\\"")) + "\"}"
+
+            # yield
+            data = {'_time': time.time(), '_raw': response_data}
+            yield data
+
+dispatch(TrackMeRestHandler, sys.argv, sys.stdin, sys.stdout, __name__)