diff --git a/README.md b/README.md index a25f051..a2a58d4 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Docs](https://github.com/rba-community/SA-CortexXDRDevices/actions/workflows/docs.yml/badge.svg)](https://pan-xdr.rba.community/) ![Appinspect](https://github.com/rba-community/SA-CortexXDRDevices/actions/workflows/appinspect.yml/badge.svg) ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/rba-community/SA-CortexXDRDevices) -[![Splunkbase App](https://img.shields.io/badge/Splunkbase-SA--CortexXDRDevices-blue)](https://splunkbase.splunk.com/app/#TODO) +[![Splunkbase App](https://img.shields.io/badge/Splunkbase-SA--CortexXDRDevices-blue)](https://classic.splunkbase.splunk.com/app/7063/) [![Splunk ES Compatibility](https://img.shields.io/badge/Splunk%20ES%20Compatibility-7.x%20|%206.x-success)](https://splunkbase.splunk.com/app/263) [![XDR Endpoint TA Compatibility](https://img.shields.io/badge/XDR%20Endpoint%20TA%20Compatibility->=1.0.1-success)](https://splunkbase.splunk.com/app/6396) ![Splunk Cloud Compatibility](https://img.shields.io/badge/Splunk%20Cloud%20Ready-Victoria%20|%20Classic-informational?logo=splunk) @@ -26,7 +26,7 @@ Full documentation can be found at [https://pan-xdr.rba.community](https://pan-x Info | Description ------|---------- -SA-CortexXDRDevices | 1.0.0 - [Splunkbase](https://splunkbase.splunk.com/app/#TODO) \| [GitHub](https://github.com/rba-community/SA-CortexXDRDevices/releases) +SA-CortexXDRDevices | 1.0.0 - [Splunkbase](https://classic.splunkbase.splunk.com/app/7063/) \| [GitHub](https://github.com/rba-community/SA-CortexXDRDevices/releases) Splunk Enterprise Security Version (Required) | [7.x \| 6.x](https://splunkbase.splunk.com/app/263) Palo Alto Cortex XDR Endpoint Retriever (Required) | [>=1.0.1](https://splunkbase.splunk.com/app/6396) Add-on has a web UI | No, this add-on does not contain views. diff --git a/docs/components/all-configurations.md b/docs/components/all-configurations.md new file mode 100644 index 0000000..53b9185 --- /dev/null +++ b/docs/components/all-configurations.md @@ -0,0 +1,17 @@ +# All Configurations + +Below is a table that list all configuration for this add-on. + +Name | Type | Web Location | CLI Location\* | Description +---- | ---- | ------------ | ------------- | ----------- +Cortex XDR Devices - Lookup Gen | Saved Search | Settings > Searches reports, and alerts | savedsearches.conf | Populates the lookup file `xdr_devices`. +xdr_devices | lookup | Settings > Lookups > Lookup definitions | transforms.conf | Lookup definition for the KVStore collection `xdr_devices_collection`. +xdr_devices_collection | KVStore collection | n/a\*\* | collections.conf | KVStore configuration. +sa_cortex_xdr_index | Search macro | Settings > Advanced Search > Search Macros | macros.conf | Index definition for the index that contains the sourcetype `cortex:xdr:endpoints`. +identity_manager://xdr_devices | Asset lookup configuration | Enterprise Security > Configure > Data Enrichment > Asset and Identity Management > Asset Lookups | inputs.conf | Asset configuration lookup to load PA Networks Cortex XDR assets into the asset database. + +> \*CLI locations are relative to `../default`. Any update to CLI configuration files should be done in the local directory. + +!!!info +**If you have the [Splunk App for Lookup File Editing :icon-link-external:](https://splunkbase.splunk.com/app/263){ target="blank" }, the KVStore collection `xdr_devices_collection` is viewable within the Web interface. +!!! \ No newline at end of file diff --git a/docs/components/category.md b/docs/components/category.md new file mode 100644 index 0000000..0dc9b0e --- /dev/null +++ b/docs/components/category.md @@ -0,0 +1,12 @@ +# Category Field + +## Default category field mapping + +Mapped Field | Event Field +------------ | ----------- +xdr_os | `operating_system` +xdr_policy | `assigned_prevention_policy` +xdr_content_status | `content_status` +xdr_last_seen | `last_seen` +xdr_package | `installation_package` +xdr_operational_status | `xdr_operational_status` \ No newline at end of file diff --git a/docs/components/index.yml b/docs/components/index.yml new file mode 100644 index 0000000..be42ff1 --- /dev/null +++ b/docs/components/index.yml @@ -0,0 +1,2 @@ +order: -4 +icon: tools \ No newline at end of file diff --git a/docs/configure/category.md b/docs/configure/category.md new file mode 100644 index 0000000..9e2c9aa --- /dev/null +++ b/docs/configure/category.md @@ -0,0 +1,5 @@ +# Category Field + +The category field by default includes many important fields. Most will find that the default configuration for this field will work for their needs. + +This field is an eval statement with multiple functions to map and clean field values. See the [Category Field reference](../components/category.md) for full field mappings and example values. diff --git a/docs/configure/index.md b/docs/configure/index.md new file mode 100644 index 0000000..d40a706 --- /dev/null +++ b/docs/configure/index.md @@ -0,0 +1,12 @@ +--- +order: -3 +icon: gear +label: Advanced Configurations +--- + +# Configure + +Each field can be customized to fit your environment. The following fields should be examined and tailored to your data. + +- [Update Priority](priority.md) (recommended) +- [Update Category](category.md) diff --git a/docs/configure/priority.md b/docs/configure/priority.md new file mode 100644 index 0000000..4199ba8 --- /dev/null +++ b/docs/configure/priority.md @@ -0,0 +1,10 @@ +# Priority Field + + +The priority field is very generic by default and should be updated to suit your environment. The following table describes how this field is set. + +Default priority field definition + +```python +priority=if(endpoint_type="AGENT_TYPE_SERVER", "high", "medium") +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..48bc47a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,36 @@ +--- +icon: home +label: Home +--- + +# Welcome to the Docs! + +This supporting add-on comes with prebuilt content for [Palo Alto Networks :icon-link-external:][palo]{ target="blank" } Cortex XDR data to be easily used with Splunk Enterprise Security's Asset database. This documentation will cover the components used in the add-on and advanced configurations. + +!!!danger Important +This Supporting add-on is only intended to work with [Splunk Enterprise Security :icon-link-external:](https://splunkbase.splunk.com/app/263){ target="blank" } deployments. +!!! + +> __*Disclaimer*__ +> +> *This Splunk Supporting Add-on is __not__ affiliated with [__Palo Alto Networks__ :icon-link-external:][palo]{ target="blank" } and is not sponsored or sanctioned by the Palo Alto Networks team. Please visit [https://www.paloaltonetworks.com/ :icon-link-external:][palo]{ target="blank" } for more information about Palo Alto Networks.* + +## Assumptions + +This documentation assumes the following: + +1. You have a working Splunk Enterprise Security environment. __This add-on is not intended to work without Splunk ES.__ +2. You already have Palo Alto Networks Cortex XDR data ingested using the [Palo Alto Cortex XDR Endpoint Retriever :icon-link-external:](https://splunkbase.splunk.com/app/6396){ target="blank" }. +3. Familiarity with setting up a new Asset source in Enterprise Security. + +## About + +Info | Description +------|---------- +SA-CortexXDRDevices | [Splunkbase :icon-link-external:](https://splunkbase.splunk.com/app/7063){ target="blank" } \| [GitHub :icon-link-external:](https://github.com/rba-community/SA-CortexXDRDevices/releases/){ target="blank" } +Splunk Enterprise Security Version (Required) | [7.x \| 6.x :icon-link-external:](https://splunkbase.splunk.com/app/263){ target="blank" } +Palo Alto Cortex XDR Endpoint Retriever (Required) | [>=1.1.0 :icon-link-external:](https://splunkbase.splunk.com/app/6396){ target="blank" } +Add-on has a web UI | No, this add-on does not contain views. +Author | [Dennis Morton](https://www.linkedin.com/in/dennis-morton-627632/) + +[palo]: https://www.paloaltonetworks.com/ \ No newline at end of file diff --git a/docs/releases/compatibility.md b/docs/releases/compatibility.md new file mode 100644 index 0000000..ce0bcc2 --- /dev/null +++ b/docs/releases/compatibility.md @@ -0,0 +1,11 @@ +--- +icon: check-circle +--- + +# Compatibility + +Product | Version +--------- | ------- +Splunk platform versions | 9.x, 8.x +Splunk Enterprise Security version | [7.x, 6.x :icon-link-external:](https://splunkbase.splunk.com/app/263){ taget="blank" } +Palo Alto Cortex XDR Endpoint Retriever | [>=1.1.0](https://splunkbase.splunk.com/app/6396){ target="blank" } \ No newline at end of file diff --git a/docs/releases/index.md b/docs/releases/index.md new file mode 100644 index 0000000..c16bf03 --- /dev/null +++ b/docs/releases/index.md @@ -0,0 +1,17 @@ +--- +order: -100 +icon: project-roadmap +label: Releases +--- + +# Release Notes + +--- + +## v1.0.0 [!badge text="LATEST" variant="info"] + +Released: [2023-09-28](https://github.com/rba-community/SA-CortexXDRDevices/releases/tag/v1.0.0) + ++++ New :icon-shield-check: +- [x] Initial Release by [Dennis Morton](https://www.linkedin.com/in/dennis-morton-627632/) ++++ \ No newline at end of file diff --git a/docs/releases/issues.md b/docs/releases/issues.md new file mode 100644 index 0000000..abf7fdc --- /dev/null +++ b/docs/releases/issues.md @@ -0,0 +1,12 @@ +--- +icon: bug +order: -100 +--- + +# Known issues + +Issue | Description | Solution | GitHub issue reference +----- | ----------- | -------- | ---------------------- +Lookup file error | You may see the error `status="Lookup file error, unknown path or update time" name=xdr_devices` | This error exists since the KVstore is being used opposed to a csv file and does not interfere with the functionality of lookup creation. | Similar Issue [#22 :icon-link-external:](https://github.com/ZachChristensen28/SA-CrowdstrikeDevices/issues/22){ target="blank" } + + Issues can be reported on the [Github page :icon-link-external:](https://github.com/rba-community/SA-CortexXDRDevices/issues){ target="blank" }. \ No newline at end of file diff --git a/docs/retype.yml b/docs/retype.yml new file mode 100644 index 0000000..4ec9cf7 --- /dev/null +++ b/docs/retype.yml @@ -0,0 +1,27 @@ +input: . +output: .retype +url: pan-xdr.rba.community +branding: + title: SA-CortexXDRDevices + label: v1.0.0 + colors: + label: + text: "#fff" + background: "#E14F28" +links: +- text: Splunkbase + link: https://splunkbase.splunk.com/7063 + target: blank + icon: apps +- text: GitHub + link: https://github.com/rba-community/SA-CortexXDRDevices/releases + target: blank + icon: mark-github +footer: + copyright: "© Copyright {{ year }}. All rights reserved.\nMade with :icon-heart-fill: by [ZachTheSplunker](https://www.linkedin.com/in/zachthesplunker/){ target=blank }" + links: + - text: Connect with the Author, Dennis Morton, on LinkedIn + link: https://www.linkedin.com/in/dennis-morton-627632/ + target: blank +markdown: + lineBreaks: hard \ No newline at end of file diff --git a/docs/start/build.md b/docs/start/build.md new file mode 100644 index 0000000..df70795 --- /dev/null +++ b/docs/start/build.md @@ -0,0 +1,21 @@ +--- +order: -4 +icon: workflow +label: Force build +--- + +# Force initial build + +!!!info Optional +!!! + +The initial build will not occur until the first scheduled runtime (see [Update default saved search schedule](scheduled-search.md)). To force the initial build perform the following: + +1. Navigate to Settings > Searches, reports, and alerts. +2. Set the "App" dropdown to `SA-CortexXDRDevices`. +3. Set the "Owner" dropdown to `All`. +4. Click "Run" under actions for the search `Cortex XDR Devices - Lookup Gen`. + +!!!info Note +The search will run in a new tab over the default time period of 60 minutes. Expand to longer timeframe for the initial build (i.e. Last 30 days). The default search is configured to periodically run to append new devices reported from Palo Alto Networks. +!!! \ No newline at end of file diff --git a/docs/start/index.md b/docs/start/index.md new file mode 100644 index 0000000..3c442d7 --- /dev/null +++ b/docs/start/index.md @@ -0,0 +1,21 @@ +--- +order: -2 +icon: rocket +expanded: true +--- + +# Getting Started + +!!!primary This add-on has a saved search and Asset configuration input enabled by default. +!!! + +## Navigation + +!!!warning Check the [Prerequisites](prerequisites.md) +!!! + +1. [Where to Install](install.md) +2. [Update default index](macro.md) +3. [Force Build](build.md) (optional) +4. [Enable Asset Correlation in ES](sources.md) +5. [Update default schedule](scheduled-search.md) (optional) diff --git a/docs/start/install.md b/docs/start/install.md new file mode 100644 index 0000000..8d06733 --- /dev/null +++ b/docs/start/install.md @@ -0,0 +1,46 @@ +--- +order: -2 +label: Where to Install +icon: package +--- + +# Where to Install + +!!!danger Important +This supporting add-on must be installed alongside Splunk Enterprise Security. Ensure the [prequisites](prerequisites.md) have been completed before proceeding. +!!! + +For detailed information on where to install Splunk Apps/add-ons, including best practices, can be found at [Splunk Docs: About Installing Splunk add-ons :icon-link-external:](https://docs.splunk.com/Documentation/AddOns/released/Overview/Wheretoinstall){ target="blank" } + +## Splunk Cloud + +Install this app to your Enterprise Security Search head. See [How to install apps on Splunk Cloud :icon-link-external:](https://docs.splunk.com/Documentation/SplunkCloud/latest/Admin/SelfServiceAppInstall){ target="blank" }. + +## Standalone Deployments (with Splunk ES) + +Install this add-on to the single instance. For more information see [Splunk Docs: Install add-on in a single-instance Splunk deployment :icon-link-external:](https://docs.splunk.com/Documentation/AddOns/released/Overview/Singleserverinstall){ target="blank" } + +## Distributed Deployments + +!!!primary Install on Enterprise Security Search head _**only**_ +!!! + +Splunk Instance type | Supported | Required | Comments +-------------------- | --------- | -------- | -------- +Enterprise Security Search Head | Yes | Yes | Install this add-on to the Enterprise Security Search Head. +Splunk Core Search Head (without ES) | No | No | Do not install on regular search heads. +Indexers | No | No | Do not install on Indexers. +Heavy Forwarders | No | No | Do not install on Heavy Forwarders. +Universal Forwarders | No | No | Do not install on Universal Forwarders. + +The installation steps for deploying Apps/add-ons in a distributed environment can be found at [Splunk Docs: Install an add-on in a distributed Splunk deployment :icon-link-external:](https://docs.splunk.com/Documentation/AddOns/released/Overview/Distributedinstall){ target="blank" } + +## Distributed Deployment Compatibility + +Distributed deployment feature | Supported | Comments +------------------------------ | --------- | -------- +Search Head Clusters | Yes | You can install this add-on to an Enterprise Security search head cluster. +Indexer Clusters | No | Do not deploy this add-on to an Indexer cluster. +Deployment Server | No | There is no need to use a deployment server to deploy this add-on. + +\* For more information, see Splunk's [documentation :icon-link-external:](https://docs.splunk.com/Documentation/AddOns/released/Overview/Installingadd-ons){ target="blank" } on installing Add-ons. diff --git a/docs/start/macro.md b/docs/start/macro.md new file mode 100644 index 0000000..7b62fb8 --- /dev/null +++ b/docs/start/macro.md @@ -0,0 +1,32 @@ +--- +order: -3 +label: Update Index +icon: command-palette +--- + +# Update Splunk Index + +!!!danger [Danger, Will Robinson :icon-link-external:](https://cultural-phenomenons.fandom.com/wiki/Danger,_Will_Robinson){ target="blank" } +Failure to update the index to the correct setting will cause no devices to be available in Splunk Enterprise Security. +!!! + +The index definition is set by a search macro. + +Macro | Default | Description +----- | ------- | ----------- +`sa_cortex_xdr_index` | index=pan_endpoints | Index definition for Palo Alto Networks Cortex XDR index. + +> Update the index definition to the correct index that contains the `cortex:xdr:endpoints` sourcetype. + +## How to update + +==- :icon-star-fill: Use Enterprise Security's Settings (Recommended) +1. (In Splunk Enterprise Security) Navigate to Configure > General > General Settings. +2. From the "App" dropdown select `SA-CortexXDRDevices`. +3. Update the SA-CortexXDRDevices Index definition and click "Save." +==- Update Search Macro Manually +1. Navigate to Settings > Advanced Search > Search Macros. +2. From the "App" dropdown choose `SA-CortexXDRDevices`. +3. Set the "Owner" dropdown to `any`. +4. Click the macro named `sa_cortex_xdr_index` to update the index definition. +=== \ No newline at end of file diff --git a/docs/start/prerequisites.md b/docs/start/prerequisites.md new file mode 100644 index 0000000..e2fcfa2 --- /dev/null +++ b/docs/start/prerequisites.md @@ -0,0 +1,15 @@ +--- +order: -1 +icon: stop +--- + +# Prerequisites + +!!!danger Important +Complete the prerequisites before installing this add-on. +!!! + +Required App | Version | Description +------------ | ------- | ----------- +[Splunk Enterprise Security :icon-link-external:](https://splunkbase.splunk.com/app/263){ target="blank" } | 7.x \| 6.x | This add-on supports Splunk ES and is not designed to work without it. +[SA-CortexXDRDevices :icon-link-external:](https://splunkbase.splunk.com/app/6396){ target="blank" } | >=1.1.0 | Palo Alto Networks Cortex XDR data must be brought in prior to installing this add-on. See the [documentation :icon-link-external:](https://splunkbase.splunk.com/app/6396){ target="blank" } for more information. diff --git a/docs/start/scheduled-search.md b/docs/start/scheduled-search.md new file mode 100644 index 0000000..066c074 --- /dev/null +++ b/docs/start/scheduled-search.md @@ -0,0 +1,18 @@ +--- +order: -6 +label: Update schedule +icon: clock +--- + +# Update default saved search schedule + +!!!info Optional +!!! + +The default saved search runs every hour to update and continually build and update the devices. To update the default schedule perform the following steps: + +1. Navigate to Settings > Searches, reports, and alerts. +2. Set the "App" dropdown to `SA-CortexXDRDevices`. +3. Set the "Owner" dropdown to `All`. +4. Click "Edit" under actions for the search `Cortex XDR Devices - Lookup Gen`. +5. Click "Edit Schedule" and update the schedule and necessary. \ No newline at end of file diff --git a/docs/start/sources.md b/docs/start/sources.md new file mode 100644 index 0000000..2e4a863 --- /dev/null +++ b/docs/start/sources.md @@ -0,0 +1,14 @@ +--- +order: -5 +icon: play +--- + +# Enable asset correlation + +Confirm asset correlation has been setup in Enterprise Security. + +1. Navigate to Enterprise Security > Configure > Data Enrichment > Asset and Identity Management. +1. Switch to the "Correlation Setup" tab. +1. Either enable for all sourcetypes (Recommended) or selectively by sourcetype. + - If you choose to enable select sourcetypes, ensure the `stash` sourcetype is also selected so Notable events will be enriched with asset information. +1. Save. \ No newline at end of file diff --git a/docs/static/asset-key-field.png b/docs/static/asset-key-field.png new file mode 100644 index 0000000..8c866a0 Binary files /dev/null and b/docs/static/asset-key-field.png differ diff --git a/docs/troubleshooting/asset-merge.md b/docs/troubleshooting/asset-merge.md new file mode 100644 index 0000000..5f646fb --- /dev/null +++ b/docs/troubleshooting/asset-merge.md @@ -0,0 +1,68 @@ +# Asset Merge + + It is possible that some of your devices share a common key field (`dns`, `ip`, `mac`, `nt_host`) that is causing an erroneous merge of your assets. There are a few ways to overcome this: + +- [Asset Merge](#asset-merge) + - [Problem Scenario](#problem-scenario) + - [Default merge](#default-merge) + - [Expected behavior](#expected-behavior) + - [Solutions](#solutions) + - [Disable Asset Merging](#disable-asset-merging) + - [Update Asset Key Fields](#update-asset-key-fields) + +## Problem Scenario + +Consider you have the following assets: + +Host | dns | ip | mac | nt_host +---- | --- | -- | --- | ------- +host1 | host1.local | ==10.0.34.9== | 77:61:f5:cb:33:a7 | host1 +host2 | host2.local | ==10.0.34.9== | a5:e7:5c:39:77:d1 | host2 + +Since these two systems share the same IP they will be merged into a single asset by default. + +### Default merge + +Asset | dns | ip | mac | nt_host +----- | --- | -- | --- | ------- +host1
host2
host1.local
10.0.34.9
77:61:f5:cb:33:a7
a5:e7:5c:39:77:d1 | host1.local
host2.local | 10.0.34.9 | 77:61:f5:cb:33:a7
a5:e7:5c:39:77:d1 | host1
host2 + +### Expected behavior + +_see next section to accomplish this expected behavior_ + +Asset | dns | ip | mac | nt_host +----- | --- | -- | --- | ------- +host1
host1.local
10.0.34.9
77:61:f5:cb:33:a7 | host1.local | 10.0.34.9 | 77:61:f5:cb:33:a7 | host1 +host2
host2.local
10.0.34.9
a5:e7:5c:39:77:d1 | host2.local | 10.0.34.9 | a5:e7:5c:39:77:d1 | host2 + +## Solutions + +### Disable Asset Merging + +If Palo Alto Networks Cortex XDR is your **_only_** data source for assets, you can disable asset merge in the global settings. + +!!!warning This is not recommended if you have more than one asset list configured (see next section) +!!! + +1. In Enterprise Security navigate to Configure > Data Enrichment > Asset and Identity Management > Global Settings. +2. Toggle off "Assets" under `Enable Merge for Assets or Identities`. + +Changes should reflect the next time the Asset database builds (usually 5-10 minutes). + +\*_For more information, see [Splunk Docs:icon-link-external:](https://docs.splunk.com/Documentation/ES/latest/Admin/Merge){ target="blank" }._ + +### Update Asset Key Fields + +If you have more than one asset list configured you can look at disabling the common key field to prevent the default merging behavior. + +!!!success In most cases, the IP field will be field that needs to disabled as the key field. +!!! + +1. (In Enterprise Security) Navigate to Configure > Data Enrichment > Asset and Identity Management. +1. Select the "Asset Fields" Tab. +1. Select the `ip` field (or the field you want to disable) and "uncheck" it from being a Key. + +![Disable Asset Key by unchecking "Key"](../static/asset-key-field.png) + +Changes should reflect the next time the Asset database builds (usually 5-10 minutes). \ No newline at end of file diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md new file mode 100644 index 0000000..467b42e --- /dev/null +++ b/docs/troubleshooting/index.md @@ -0,0 +1,13 @@ +--- +order: -4 +icon: question +--- + +# Troubleshooting + +There can be many issues when setting up a new app/add-on in Splunk. Below highlights the most common issues with this Add-on. Don't see your issue? Submit a new issue on [Github :icon-link-external:](https://github.com/rba-community/SA-CortexXDRDevices/issues){ target="blank" }. + +Issue | Description | Solution +----- | ----------- | -------- +Multiple asset merge | It is possible that some of your devices share a common key field (`dns`, `ip`, `mac`, `nt_host`) which will cause merging by default. |See the [Asset Merge Solutions](asset-merge.md) for ways to improve the merging behavior. +Asset Database not populating with data | The asset database may show no data if the initial search has not run to build the asset database or the default macro has not been updated. | Verify the default macro has the correct index definition (see [Update Default Macro](../start/macro.md)). Also see [Force build](../start/build.md) to build the assets lookup before the first scheduled run. \ No newline at end of file