added docs

Signed-off-by: Zachary Christensen <zchristensen@splunk.com>

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.

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 <small>:icon-link-external:</small>](https://splunkbase.splunk.com/app/263){ target="blank" }, the KVStore collection `xdr_devices_collection` is viewable within the Web interface.
+!!!

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`

docs/components/index.yml

@@ -0,0 +1,2 @@
+order: -4
+icon: tools

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.

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) <small>(recommended)</small>
+- [Update Category](category.md)

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")
+```

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 <small>:icon-link-external:</small>][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 <small>:icon-link-external:</small>](https://splunkbase.splunk.com/app/263){ target="blank" } deployments.
+!!!
+
+> __*Disclaimer*__
+> 
+> *This Splunk Supporting Add-on is __not__ affiliated with [__Palo Alto Networks__ <small>:icon-link-external:</small>][palo]{ target="blank" } and is not sponsored or sanctioned by the Palo Alto Networks team. Please visit [https://www.paloaltonetworks.com/ <small>:icon-link-external:</small>][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 <small>:icon-link-external:</small>](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 <small>:icon-link-external:</small>](https://splunkbase.splunk.com/app/7063){ target="blank" } \| [GitHub <small>:icon-link-external:</small>](https://github.com/rba-community/SA-CortexXDRDevices/releases/){ target="blank" }
+Splunk Enterprise Security Version <small>(Required)</small> | [7.x \| 6.x <small>:icon-link-external:</small>](https://splunkbase.splunk.com/app/263){ target="blank" }
+Palo Alto Cortex XDR Endpoint Retriever <small>(Required)</small> | [>=1.1.0 <small>:icon-link-external:</small>](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/

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 <small>:icon-link-external:</small>](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" }

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/)
++++

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 <small>:icon-link-external:</small>](https://github.com/ZachChristensen28/SA-CrowdstrikeDevices/issues/22){ target="blank" } 
+
+ Issues can be reported on the [Github page <small>:icon-link-external:</small>](https://github.com/rba-community/SA-CortexXDRDevices/issues){ target="blank" }.

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

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.
+!!!

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) <small>(optional)</small>
+4. [Enable Asset Correlation in ES](sources.md)
+5. [Update default schedule](scheduled-search.md) <small>(optional)</small>

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 <small>:icon-link-external:</small>](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 <small>:icon-link-external:</small>](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 <small>:icon-link-external:</small>](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 <small>:icon-link-external:</small>](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 <small>:icon-link-external:</small>](https://docs.splunk.com/Documentation/AddOns/released/Overview/Installingadd-ons){ target="blank" } on installing Add-ons.

docs/start/macro.md

@@ -0,0 +1,32 @@
+---
+order: -3
+label: Update Index
+icon: command-palette
+---
+
+# Update Splunk Index
+
+!!!danger [Danger, Will Robinson <small>:icon-link-external:</small>](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 <small>(Recommended)</small>
+1. <small>(In Splunk Enterprise Security)</small> 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.
+===

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 <small>:icon-link-external:</small>](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 <small>:icon-link-external:</small>](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 <small>:icon-link-external:</small>](https://splunkbase.splunk.com/app/6396){ target="blank" } for more information.

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.

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 <small>(Recommended)</small> 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.