Agari App for Splunk Quick-Start Guide

Transcription

1 Agari App for Splunk Quick-Start Guide Initial Release (v1.1.0) This document describes how to get started with the Agari App for Splunk. This release is available to Agari customers via SplunkBase ( The Agari App for Splunk includes the following: A setup script that installs and configures the application A python-based data input script that retrieves data from the Agari REST API A reference set of Splunk search queries, reports, and dashboards that can be used to view/explore the data Installing the Agari App for Splunk The Agari App for Splunk can be installed from Splunkbase by either browsing for apps directly from your Splunk software (Figure I1/I2), or by downloading the app package via a web browser, then uploading via Splunk software (Figure I3). Figure I1: Click Browse more apps to browse Splunkbase. Click Install app from file to install a downloaded app package Figure I2: The Agari App for Splunk can be located via the search string agari

2 If installing via a downloaded app package, you may need to click the box labeled Upgrade app to overwrite the existing installed app if you have a previous version installed. (Figure X) Figure I3: Manual upload of the Agari App for Splunk package Configuring the Agari App for Splunk After installing the Agari App for Splunk, click Set up now to go the app configuration screen. (Figure C1) Figure C1: Post-install setup required notification Enter the setup information for the Agari app. (Figure C2) At a minimum, this requires copy/pasting your API Client ID and Client Secret credentials which are obtained from the Agari Customer Protect portal. See the next section for details on obtaining your API credentials.

3 Optionally, a Proxy Address URL (with or without HTTP Basic auth) can be configured. SSL verification is enabled by default (recommended) but can be disabled if needed by deselecting the Verify SSL option. Additionally, a custom CA_BUNDLE can be configured by entering the filepath to a valid CA_BUNDLE file or folder. Note that the use of a custom CA_BUNDLE requires the Verify SSL option to be enabled. Figure C2: Agari App for Splunk configuration screen Obtaining/generating API credentials API access credentials are generated on a per-user basis and must be obtained from within the Agari Customer Protect portal located at You may use the credentials of an existing user account, or you can create a new Splunk user account (recommended). 1. From within the Agari portal, navigate to Admin > Users 2. Click an existing user, or select Add New User 3. Click Generate API Credentials to create new credentials OR click Regenerate API Client Secret to regenerate a new client secret for an existing user. (Note: A user account must accept the invitation for a brand new account before the Generate API Credentials links is available.) (Figure C3) 4. Copy/Paste the Client ID and Client Secret to the Agari App for Splunk configuration page

4 5. Be sure to hit the Update button after generating/recording API credentials to save the user s profile with the newly generated credentials! Figure C3: Generation of an API Client ID and API Client Secret via the Agari Customer Protect portal That s it! You can now use the Agari App for Splunk link from the Splunk landing page to launch the app. (Figure C4) Figure C4: Agari App for Splunk can be accessed from the Splunk home screen

5 Specifying a Dedicated Agari Index (Optional) The Agari App for Splunk installation will use the default index that has been specified in your Spunk environment. If you are ingesting a lot of data into your default index, you may consider creating (or switching to) a separate index to host the Agari data, which will improve search performance. Index creation should be managed by your Splunk administrator and done in accordance with Splunk documentation and best practices. A process overview follows. 1. Create a new index 1. Select Settings / Indexes 2. Click New Index 3. Enter your index configuration ( Index Name at a minimum) (Figure O1) Note: If Splunk is running in a distributed environment, it may be necessary to replicate the newly-created index on the other indexers in the environment. Figure O1: Configuration of an index specific for Agari data

6 2. Configure the Agari data input to use the desired index 1. Select Settings / Data inputs / Script s 2. Click $SPLUNK_HOME/etc/apps/agari/bin/agari_cp.py to edit the input script configuration 3. Click More settings 4. Select the desired index from the Index drop-down (Figure O2) Figure O2: Assignment of the agari index to the Agari input script 3. Modify the Agari search macro 1. From within the Agari app select Settings / Advanced Search / Search macros 2. Click macro_agari_index to edit the index macro

7 3. Modify the macro Definition accordingly (Figure O3) Figure O3: Modification of the macro_agari_index macro to refer to the newly-created index Note: There are 3 macros created by the Agari App for Splunk. Only macro_agari_index should be modified, as the others will inherit this change. (Figure O4) Figure O4: Only 1 macro must be edited to reflect the newly-created index Using the Agari App for Splunk The Agari App for Splunk consists of a background data input script that harvests Agari Customer Protect data (events) using the Agari REST API, and a number of preconfigured searches, reports and dashboards that can be used to view and explore the data. Data Input Script The data input script is scheduled to run automatically in the background every 15 minutes. When the app is first installed the script will backfill data for the previous two weeks (in 12hr

8 increments). As such, a complete backfill of data will take about 7 hours of uninterrupted operation. The data ingested into Splunk consist of Agari Customer Protect alert events, which include: Infrastructure alerts Threat Spike alerts Authentication Spike alerts SPF Record Changed DMARC Record Changed New Sender alert Brand Spoofing alert Other ingested data include: Failure Sample data that is specific to certain alert events (i.e. Threat Spike, Authentication Spike, and Brand Spoofing alerts) API Service status Log data from the data input script Dashboards The Agari App for Splunk includes a number of dashboards that provide views of your alert activity. Click the Dashboards menu item from within the Agari app to view the list of available dashboards. (Figure U1) Figure U1: Pre-built dashboards are provided by the Agari App for Splunk

9 There are two top-level summary dashboards. The Alert Dashboard: All Alerts: 1 Day dashboard provides a daily snapshot of alert activity. (Figure U2) Clicking on the bar chart will drill-down into a more detailed dashboard view for the specific alert type. Figure U2: Alert Dashboard: All Alerts: 1 Day The Alert Dashboard: All Alerts: 2 Week dashboard provides a 2 week snapshot of recent alert activity. (figure U3) Clicking on the bar chart will drill-down into a more detailed dashboard view for the specific alert type. You can use the timepicker control to modify the time period for the alerts. Figure U3: Alert Dashboard: All Alerts: 2 Weeks

10 In addition to the top-level summary dashboards, there are dashboards that display more specific information for each alert type. Clicking on the bar chart from within one of the alert-specific dashboards displays summary information for the specified alert(s). Additional details can be displayed by clicking on a row from the summary table. Reports The Agari App for Splunk includes a number of reports. Click the Reports menu item from within the Agari app to view the list of available reports. (Figure U4) Figure U3: Report list Report: Agari Log contains debugging information and error messages generated by the data input script. If you encounter any problems importing data, please check this Agari Log report. Report: All Alerts is similar to the Alert Dashboard: All Alerts: 2 Week dashboard. It is included here to provide an example of a report-packaged view. Report: Service Status shows the service status of the Agari API. Each invocation of the data input script should result in a new entry in this report.

11 Search If you would like explore the Agari alert data by using Splunk s built-in search engine, you can do so by selecting the Search menu item. (Figure U4) Figure U3: Searching raw Agari data using Splunk s built-in search engine At a minimum, you will need to indicate the index where the Agari data reside. This can be done by referencing the Agari CP macro in the search bar : `macro_agari_cp` Note: use backticks to enclose the reference to macro_agari_cp Upon a successful search you will see a list of Selected Fields in the left frame of search page. You can click the various fields to further refine your search. Example: view all alert events `macro_agari_cp` event_type=alert_detail dedup event_data.id Example: view all infrastructure alerts `macro_agari_cp` event_type=alert_detail event_data.alert_type=infrastructure dedup event_data.id Example: view the failure samples that correspond to the alert event with an ID of `macro_agari_cp` index=agari event_type=failure_samples alert_id=

12 Troubleshooting Not receiving data If you are not receiving any Agari alert data, first check the Agari Log for possible errors. The Agari Log is available from within the Agari App for Splunk by clicking the Reports menu. This following error in the Agari Log report indicates that a problem with the API credentials provided during setup: Auth error: [401] Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method. Please review the information in the section titled Obtaining/generating API credentials and ensure you have entered your API credentials correctly into Splunk. If necessary, you can regenerate a new Client Secret value. If you need to enter/reenter your credentials into Splunk: 1. Click the Blue Gear icon from the main Splunk page 2. Locate the Agari App in the list of apps 3. Click Set up 4. Enter the (new) Client ID and Client Secret values 5. Click Save HTTPSConnectionPool Error in Agari Log The following error in the Agari Log report indicates that the data input script was not able to communicate with the Agari API server: Auth exception: HTTPSConnectionPool(host='api.agari.com', port=443): Max retries exceeded with url: /oauth/token If this error occurs repeatedly (i.e. back-to-back), then there likely is a network security configuration which is disallowing outbound access via port 433 (SSL). Please check your network configuration. If this error occurs infrequently or intermittently, then Splunk host may be going into sleep or hibernation mode. This is often the case if Splunk is running on a personal laptop. In this situation, normal operation should resume when the system awakens from sleep or hibernation mode.

13 Dashboards and Reports are slow Sharing the Agari index with other high-volume data source can cause the Agari App for Splunk to be slow when displaying Dashboard and Report data. By default, the Agari setup will use the default index in your Splunk configuration. If there are other high-volume data sources using the default index, you may need to configure a separate/dedicated index to hold the Agari data. Please see the section titled Specifying a Dedicated Agari Index (Optional) for more information. Providing Feedback to Agari We would like your feedback and suggestions for ways we can improve the Agari App for Splunk. Please contact your Agari Customer Success representative if you would like to provide feedback, or if you otherwise require assistance.

14

15