New documentation format (#62)

Signed-off-by: Zach Christensen <23529374+ZachChristensen28@users.noreply.github.com>
splunk · Aug 20, 2023 · 8d12c97 · 8d12c97
1 parent adef32b
commit 8d12c97
Show file tree

Hide file tree

Showing 45 changed files with 385 additions and 661 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,16 +1,21 @@
 name: docs
 on:
+  workflow_dispatch:
   push:
     branches:
-      - master
       - main
+      - master
     paths:
       - "docs/**"
-      - "mkdocs.yml"
-      - "overrides/**"
-
 jobs:
-  call-docs-workflow:
-    uses: ZachChristensen28/splunk-github-wfa/.github/workflows/docs.yml@main
-    with:
-      config-path: docs/requirements.txt
+  publish:
+    name: Publish to retype branch
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+      - uses: retypeapp/action-build@latest
+      - uses: retypeapp/action-github-pages@latest
+        with:
+          update-branch: true
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,5 @@ __pycache__/
 venv
 .idea
 Pipfile**
+retype.manifest
+.retype/**
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-[![SA-CrowdstrikeDevices](./docs/assets/sa-crowdstrike-logo-dark.svg)](https://splunk-sa-crowdstrike.ztsplunker.com)
+[![SA-CrowdstrikeDevices](./docs/static/sa-crowdstrike-hero.webp)](https://splunk-sa-crowdstrike.ztsplunker.com)
 
 ![GitHub](https://img.shields.io/github/license/zachchristensen28/SA-CrowdstrikeDevices)
 [![Docs](https://github.com/ZachChristensen28/SA-CrowdstrikeDevices/actions/workflows/docs.yml/badge.svg)](https://splunk-sa-crowdstrike.ztsplunker.com/)

diff --git a/docs/CNAME b/docs/CNAME
diff --git a/docs/assets/sa-crowdstrike-example-dark.png b/docs/assets/sa-crowdstrike-example-dark.png
diff --git a/docs/assets/sa-crowdstrike-example-light.png b/docs/assets/sa-crowdstrike-example-light.png
diff --git a/docs/assets/sa-crowdstrike-logo-dark.svg b/docs/assets/sa-crowdstrike-logo-dark.svg
diff --git a/docs/assets/sa-crowdstrike-logo.svg b/docs/assets/sa-crowdstrike-logo.svg
diff --git a/docs/reference/all-configurations.md → docs/components/all-configurations.md b/docs/reference/all-configurations.md → docs/components/all-configurations.md
@@ -1,7 +1,3 @@
----
-hide:
-    - toc
----
 # All Configurations
 
 Below is a table that list all configuration for this add-on.
@@ -18,5 +14,6 @@ identity_manager://crowdstrike_devices | Asset lookup configuration | Enterprise
 
 > \*CLI locations are relative to `../default`. Any update to CLI configuration files should be done in the local directory.
 
-!!! note ""
-    **If you have the [Splunk App for Lookup File Editing](https://splunkbase.splunk.com/app/263), the KVStore collection `crowdstrike_devices_collection` is viewable within the Web interface.
+!!!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 `crowdstrike_devices_collection` is viewable within the Web interface.
+!!!
diff --git a/docs/reference/asset-mapping.md → docs/components/asset-mapping.md b/docs/reference/asset-mapping.md → docs/components/asset-mapping.md
@@ -1,28 +1,23 @@
----
-hide:
-    - toc
----
-
 # Asset Database Mapping
 
 The following table describes how this add-on maps to the Asset Database.
 
-> reference [Format an asset or identity in Splunk ES](https://docs.splunk.com/Documentation/ES/latest/Admin/Formatassetoridentitylist#Asset_lookup_header)
+> reference [Format an asset or identity in Splunk ES<small>:icon-link-external:</small>](https://docs.splunk.com/Documentation/ES/latest/Admin/Formatassetoridentitylist#Asset_lookup_header){ target="blank" }
 
-ES Asset lookup field | [Crowdstrike Device TA Fields](https://splunkbase.splunk.com/app/5570) | Example value | Multi-value allowed
+ES Asset lookup field | [Crowdstrike Device TA Fields<small>:icon-link-external:</small>](https://splunkbase.splunk.com/app/5570){ target="blank" } | Example value | Multi-value allowed
 --- | --- | --- | ---
 ip | `falcon_device.local_ip` | 10.15.23.8 | true
 mac | `mac` | 61:se:e3:1s:7r:38 | true
 nt_host | `falcon_device.hostname` | dev-server01 | false
 dns | `nt_host` + `falcon_device.machine_domain` | dev-server01.example.com | true
 owner | n/a | `not mapped` | n/a
-priority | see [Configure Priority](/configure/priority) | medium | false
+priority | see [Configure Priority](/configure/priority.md) | medium | false
 lat | from `iplocation` of `falcon_device.external_ip` | 40.76073 | false
 long | from `iplocation` of `falcon_device.external_ip` | -111.89096 | false
 city | from `iplocation` of `falcon_device.external_ip` | Salt Lake City | false
 country | from `iplocation` of `falcon_device.external_ip` | United States | false
 bunit | `falcon_device.ou{}` + `falcon_device.site_name` | computer,finance | true
-category | see [Category field reference](../category) | see [Category field reference](../category) | true
+category | see [Category field reference](category.md) | see [Category field reference](category.md) | true
 pci_domain | n/a | `not mapped` | n/a
 is_expected | n/a | `not mapped` | n/a
 should_timesync | n/a | `not mapped` | n/a

diff --git a/docs/reference/category.md → docs/components/category.md b/docs/reference/category.md → docs/components/category.md
@@ -1,4 +1,4 @@
-# Category
+# Category Field
 
 ## Default category field mapping
 

diff --git a/docs/components/index.yml b/docs/components/index.yml
@@ -0,0 +1,2 @@
+order: -4
+icon: tools
diff --git a/docs/configure/bunit.md b/docs/configure/bunit.md
@@ -1,5 +1,6 @@
 # Business Unit Field (bunit)
 
-!!! info "To update the `bunit` field modify the `Crowdstrike Devices Lookup - Gen` saved search. It is recommended to clone the default search before making changes (see [Clone Saved Search](../best-practice/clone-search))."
+!!!infoTo update the `bunit` field modify the `Crowdstrike Devices Lookup - Gen` saved search. It is recommended to clone the default search before making changes (see [Clone Saved Search](clone-search.md))
+!!!
 
-The bunit field will most likely need to be updated. Every organization will have different values for this field. See [Asset Mappings](/reference/asset-mapping) for description of the default fields used.
+The bunit field will most likely need to be updated. Every organization will have different values for this field. See [Asset Mappings](/components/asset-mapping.md) for description of the default fields used.
diff --git a/docs/configure/category.md b/docs/configure/category.md
@@ -1,7 +1,8 @@
 # Category Field
 
-!!! info "To update the `category` field modify the `Crowdstrike Devices Lookup - Gen` saved search. It is recommended to clone the default search before making changes (see [Clone Saved Search](../best-practice/clone-search))."
+!!!info To update the `category` field modify the `Crowdstrike Devices Lookup - Gen` saved search. It is recommended to clone the default search before making changes (see [Clone Saved Search](clone-search.md)).
+!!!
 
 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](../../reference/category) for full field mappings and example values.
+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/cleanup.md b/docs/configure/cleanup.md
@@ -2,8 +2,9 @@
 
 The saved search `Crowdstrike Devices Lookup - Cleanup` runs every hour 29 minutes after the hour to remove old/stale device data from the kvstore. By default, it will remove any device that has not reported in longer than 2 days.
 
-???+ note
-    Even though a device may be removed, it will be re-added by the saved search `Crowdstrike Devices Lookup - Gen` if it begins to send data again.
+!!!info Note
+Even though a device may be removed, it will be re-added by the saved search `Crowdstrike Devices Lookup - Gen` if it begins to send data again.
+!!!
 
 ## Update Search Macro
 
@@ -13,14 +14,12 @@ To change the retention period from the default 2 days, there is a search macro
 1. Set the "App" to `SA-CrowdstrikeDeviecs`.
 1. Set the "Owner" to `Any`.
 1. Click on `sa_crowdstrike_retention` to modify the definition.
-1. Set the definition to a valid [time modifier](https://docs.splunk.com/Documentation/Splunk/9.0.1/SearchReference/SearchTimeModifiers#How_to_specify_relative_time_modifiers).
+1. Set the definition to a valid [time modifier<small>:icon-link-external:</small>](https://docs.splunk.com/Documentation/Splunk/latest/SearchReference/SearchTimeModifiers#How_to_specify_relative_time_modifiers){ target="blank" }.
 
-???+ important
-    __Make sure to keep the quotes around the definition.__
-
-    i.e.
-
-    "-7d@d"
+!!!success Note
+__Make sure to keep the quotes around the definition.__
+i.e. -7d\@d
+!!!
 
 ## Update Search Schedule
 

diff --git a/docs/configure/best-practice/clone-search.md → docs/configure/clone-search.md b/docs/configure/best-practice/clone-search.md → docs/configure/clone-search.md
@@ -1,3 +1,7 @@
+---
+order: -100
+---
+
 # Clone default saved search
 
 In order to preserve the default behavior and to compare changes to new releases, it is recommended to clone the default search `Crowdstrike Devices Lookup - Gen` before making any changes.

diff --git a/docs/configure/index.md b/docs/configure/index.md
@@ -1,11 +1,17 @@
+---
+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.
 
-!!! info "It is recommended to clone the default search before making changes (see [Clone Saved Search](./best-practice/clone-search))."
+!!!success It is recommended to clone the default search before making changes (see [Clone Saved Search](clone-search.md)).
+!!!
 
-- [Update Priority](./priority)
-- [Update Category](./category)
-- [Update Business Unit](./bunit)
-- [Update Schedule](./schedule.md)
-- [Update Cleanup](./cleanup.md)
+- [Update Priority](priority.md) <small>(recommended)</small>
+- [Update Category](category.md)
+- [Update Business Unit](bunit.md)
+- [Update Cleanup](cleanup.md)
diff --git a/docs/configure/priority.md b/docs/configure/priority.md
@@ -1,6 +1,7 @@
 # Priority Field
 
-!!! info "To update the `priority` field modify the `Crowdstrike Devices Lookup - Gen` saved search. It is recommended to clone the default search before making changes (see [Clone Saved Search](../best-practice/clone-search))."
+!!!primary To update the `priority` field modify the `Crowdstrike Devices Lookup - Gen` saved search. It is recommended to clone the default search before making changes (see [Clone Saved Search](clone-search.md)).
+!!!
 
 The priority field is very generic by default and should be updated to suite your environment. The following table describes how this field is set.
 
@@ -11,8 +12,7 @@ RegEx\* | server\|ubuntu\|rhel\|linux | `high` | Servers
 boolean | true() | `medium` | catch-all. Remaining devices receive medium severity.
 
 
-!!! note ""
-    \*Regex Match is performed on the category field.
+> \*Regex Match is performed on the category field.
 
 Default priority field definition
 

diff --git a/docs/configure/schedule.md b/docs/configure/schedule.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,41 +1,37 @@
 ---
-hide:
-    - navigation
-    - toc
+icon: home
+label: Home
 ---
-# Home
 
-![Image title](./assets/sa-crowdstrike-logo.svg#only-light){ class="ignore-image" }
-![Image title](./assets/sa-crowdstrike-logo-dark.svg#only-dark){ class="ignore-image" }
+![](/static/sa-crowdstrike-hero.webp)
 
-The SA-CrowdstrikeDevices add-on allows Splunk Enterprise Security admins to use Crowdstrike device data with the Asset Database.
+# Welcome to the Docs!
 
-__Example Output__
-![SA-CrowdstrikeDevices Example](/assets/sa-crowdstrike-example-dark.png#only-dark)
-![SA-CrowdstrikeDevices Example](/assets/sa-crowdstrike-example-light.png#only-light)
+The SA-CrowdstrikeDevices add-on allows Splunk Enterprise Security admins to use [CrowdStrike<small>:icon-link-external:</small>][crowdstrike]{ target="blank" } device data with the Asset Database. This documentation will cover the components used in the add-on and advanced configurations. 
 
-!!! important "This Supporting add-on is only intended to work with [Splunk Enterprise Security](https://splunkbase.splunk.com/app/263) deployments."
+!!!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.
+!!!
 
-!!! quote ""
-    __*Disclaimer*__
-
-    *This Splunk Supporting Add-on is __not__ affiliated with [__Crowdstrike, Inc.__](https://www.crowdstrike.com) and is not sponsored or sanctioned by the Crowdstrike team. As such, the included documentation does not contain information on how to get started with Crowdstrike. Rather, this documentation serves as a guide to use Crowdstrike device data with Splunk Enterprise Security. Please visit [https://www.crowdstrike.com](https://www.crowdstrike.com) for more information about Crowdstrike.*
+> __*Disclaimer*__
+> 
+> *This Splunk Supporting Add-on is __not__ affiliated with [__Crowdstrike, Inc.__<small>:icon-link-external:</small>][crowdstrike]{ target="blank" } and is not sponsored or sanctioned by the Crowdstrike team. As such, the included documentation does not contain information on how to get started with Crowdstrike. Rather, this documentation serves as a guide to use Crowdstrike device data with Splunk Enterprise Security. Please visit [https://www.crowdstrike.com<small>:icon-link-external:</small>][crowdstrike]{ target="blank" } for more information about Crowdstrike.*
 
 ## 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 Crowdstrike device data ingested using the [Crowdstrike Devices technical add-on](https://splunkbase.splunk.com/app/5570).
+2. You already have Crowdstrike device data ingested using the [Crowdstrike Devices technical add-on<small>:icon-link-external:</small>](https://splunkbase.splunk.com/app/5570){ target="blank" }.
 3. Familiarity with setting up a new Asset source in Enterprise Security.
 
 ## About
 
 Info | Description
 ------|----------
-SA-CrowdstrikeDevices | 1.1.1 - [Splunkbase](https://splunkbase.splunk.com/app/6573) \| [GitHub](https://github.com/ZachChristensen28/SA-CrowdstrikeDevices/releases/tag/v1.1.1)
-Splunk Enterprise Security Version <small>(Required)</small> | [7.x \| 6.x](https://splunkbase.splunk.com/app/263)
-Crowdstrike Devices Add-on <small>(Required)</small> | [3.x](https://splunkbase.splunk.com/app/5570)
+SA-CrowdstrikeDevices | 1.1.1 - [Splunkbase<small>:icon-link-external:</small>](https://splunkbase.splunk.com/app/6573){ target="blank" } \| [GitHub<small>:icon-link-external:</small>](https://github.com/ZachChristensen28/SA-CrowdstrikeDevices/releases/tag/v1.1.1){ 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" }
+Crowdstrike Devices Add-on <small>(Required)</small> | [3.x<small>:icon-link-external:</small>](https://splunkbase.splunk.com/app/5570){ target="blank" }
 Add-on has a web UI | No, this add-on does not contain views.
 
-[Quick Start](quickstart/prerequisites){ .md-button .md-button--primary }
+[crowdstrike]: https://www.crowdstrike.com
diff --git a/docs/quickstart/prerequisites.md b/docs/quickstart/prerequisites.md
diff --git a/docs/quickstart/quickstart.md b/docs/quickstart/quickstart.md