PSA Elasticsearch Integration

Setup the Polarity Source Analytics Integration with Elasticsearch

Download and Install

The Source Analytics integration can be installed through the Integration Store.

Navigate to the Integration Store tab and search for "telemetry".  Install the "Telemetry - Elasticsearch" integration:

Setup Elasticsearch API Key

The Source Analytics integration requires a properly configured API key to be able to search the telemetry logs.

1. Login to your Kibana instance and navigate to "Stack Management" -> "Security" -> "API Keys".
2. Click on the Create API Key button.
3. Under Name, fill in descriptive name for the API Key usage such as Polarity Source Analytics Integration. 
4. Check the "Restrict privileges" check box and then paste the following configuration into the text box area:
   JSONJSON

   {
     "source_analytics": {
       "cluster": [],
       "indices": [
         {
           "names": [
             "<name-of-data-stream>"
           ],
           "privileges": [
             "read"
           ],
           "allow_restricted_indices": false
         }
       ],
       "run_as": [
         "*"
       ]
     }
   }

5. Be sure to replace <name-of-data-stream> with the name of the data stream that that Source Analytic logs are being sent to.  
   Note

   If you used the configuration from the Polarity Source Analtyics with Elasticsearch guide, then the data stream name will be logs-docker.container_logs-default.

6. Optionally set the API Key to expire after a certain amount of time.
7. Next click on the Create API Key button.
8. Copy and Save the provided API key in Base64 format.

Configure the Integration

Set the following required values for the integration which can be configured from the Integration Settings page under the Options tab.

Integration Options

• Elasticsearch URL
  • This should be the Elasticsearch REST API URL.  The URL should include the scheme (https://) and a port if applicable.
  • Example: https://elastic.prod:9200
• Username and Password
  • While the integration supports authenticating via Username and Password we do not recommend this method of authentication.  Leave these two options blank and instead provide the API Key you configured previously.
• API Key
  • Fill in the API Key you generated in the previous Setup Elasticsearch API Key step.
• Index
  • The index where your Source Analytics data is being sent.  This can be set to the name of the data stream you generated which in a default configuration would be logs-psa-default
• Ignored User Ids
  • This option allows you to ignore searches from specific users.  Typically this field is left blank but in some deployments you may want to ignore lookups performed by the admin user.  In this case you can set the value of this field to 1 which is the user ID of the default admin user.
• Fields
  • This is a comma delimited list of the required source analytic fields.  For a default configuration you should set this value to:
    JSONJSON

    timestamp:@timestamp, entityValue:polarity.entityValue, userId:polarity.userId, integrationId:polarity.integrationId, isFromCache:polarity.isFromCache, hasResult:polarity.hasResult, windowTitle:polarity.windowTitle, process:polarity.process

• Ignore Integrations
  • Comma delimited list of integration IDs to ignore. Integration IDs match the directory name of the integration but with dashes converted to underscores. For example, if the integration directory is "generic-integration", the ID for the integration would be "generic_integration". 
  • The Source Analytics integration will never include itself in results so this option can typically be left blank.
• Display Window Title
  • If checked, Window Title information will displayed as part of the returned data.  In some cases you may not want other users to be able to view Window Title information of previous search requests.  In this case, uncheck this option.

Testing

Once the integration options have been set you can subscribe to the integration and try searching on an indicator that has been searched before.  You will see the Source Analytics integration return results in the Overlay Window.