Improve docs by creating a nav tree for sources (#220)

* Improve table of contents * Split sources.md by vendor * new theme
CSVD · Dec 7, 2019 · f7e299e · f7e299e
1 parent 5a8e39b
commit f7e299e
Show file tree

Hide file tree

Showing 22 changed files with 1,196 additions and 1,107 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -9,4 +9,9 @@ mkdocs:
 formats: all
 
 submodules:
-  exclude: all
+  exclude: all
+
+python:
+  version: 3.7
+  install:
+    - requirements: mkdocs-requirements.txt
diff --git a/docs/gettingstarted.md → docs/gettingstarted/index.md b/docs/gettingstarted.md → docs/gettingstarted/index.md
@@ -1,12 +1,14 @@
-# Getting Started
+# Before you start
+
+## Getting Started
 
 Splunk Connect for Syslog is a containerized distribution of syslog-ng with a configuration framework
 designed to simplify getting syslog data into Splunk Enterprise and Splunk Cloud. Our approach is
 to provide a runtime-agnostic solution allowing customers to deploy using the container runtime
 environment of choice.
 
 
-# Planning Deployment
+## Planning Deployment
 
 Syslog is an overloaded term that refers to multiple message formats AND optionally a wire protocol for
 transmission of events between computer systems over UDP, TCP, or TLS. The protocol is designed to minimize
@@ -24,11 +26,11 @@ environment.
 * Plan for appropriately sized hardware (see)[performance.md]
 
 
-# Implementation
+## Implementation
 
-## Splunk Setup
+### Splunk Setup
 
-### Create Indexes
+#### Create Indexes
 
 SC4S is pre-configured to map each sourcetype to a typical index. For new installations, it is best practice to create them in Splunk when 
 using the SC4S defaults. SC4S can be easily customized to use different indexes if desired.
@@ -42,15 +44,15 @@ using the SC4S defaults. SC4S can be easily customized to use different indexes
 * netipam
 * em_metrics (ensure this is created as a metrics index)
 
-### Install Related Splunk Apps
+#### Install Related Splunk Apps
 
 Install the following:
 
 * [Splunk App for Infrastructure](https://splunkbase.splunk.com/app/3975/)
 * [Splunk Add-on for Infrastructure](https://splunkbase.splunk.com/app/4217/)
 * [Splunk Metrics Workspace](https://splunkbase.splunk.com/app/4192/) *NOTE Included in Splunk 7.3.0 and above*
 
-### Configure the Splunk HTTP Event Collector
+#### Configure the Splunk HTTP Event Collector
 
 - Set up the Splunk HTTP Event Collector with the HEC endpoints behind a load balancer (VIP) configured for https round robin *WITHOUT* sticky
 session.  Alternatively, a list of HEC endpoint URLs can be configured in SC4S (native Syslog-ng load balancing) if no load balancer is in place.  In either case, it is
@@ -61,14 +63,14 @@ event destinations.
 or [Splunk Enterprise](http://dev.splunk.com/view/event-collector/SP-CAAAE6Q) for specific HEC configuration instructions based on your
 Splunk type.
 
-## Implement a Container Runtime and SC4S
+### Implement a Container Runtime and SC4S
 
-### Prerequisites
+#### Prerequisites
 
 * Linux host with Docker (CE 19.x or greater with Docker Swarm) or Podman enabled, depending on runtime choice (below).
 * A network load balancer (NLB) configured for round robin. Note: Special consideration may be required when more advanced products are used. The optimal configuration of the load balancer will round robin each http POST request (not each connection).
 
-### Select a Container Runtime and SC4S Configuration
+#### Select a Container Runtime and SC4S Configuration
 
 | Container and Orchestration | Notes |
 |-----------------------------|-------|
@@ -78,7 +80,7 @@ Splunk type.
 | [Docker CE + Swarm single node RHEL 7.7](gettingstarted/docker-swarm-rhel7.md) | Option for RedHat 7.7 desiring Docker Compose or Swarm orchestration |
 | [Bring your own Envionment](gettingstarted/byoe-rhel7.md) | Option for RedHat 7.7 (centos 7) with SC4S configuration without containers | 
 
-## Offline Container Installation
+### Offline Container Installation
 
 Follow these instructions to "stage" SC4S by downloading the container so that it can be loaded "out of band" on a
 host machine, such as an airgapped system, without internet connectivity.
@@ -116,7 +118,7 @@ attempt to obtain the container image via the internet.
 Environment="SC4S_IMAGE=sc4slocal:latest"
 ```
 
-# Scale out
+## Scale out
 
 Additional hosts can be deployed for syslog collection from additional network zones and locations:
 

diff --git a/docs/logo.png b/docs/logo.png
diff --git a/docs/sources.md b/docs/sources.md
diff --git a/docs/sources/Checkpoint/index.md b/docs/sources/Checkpoint/index.md
@@ -0,0 +1,63 @@
+# Vendor - Checkpoint
+
+## Product - Log Exporter (Splunk)
+
+| Ref            | Link                                                                                                    |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| Splunk Add-on  | https://splunkbase.splunk.com/app/4293/                                                                 |
+| Product Manual | https://sc1.checkpoint.com/documents/App_for_Splunk/html_frameset.htm |
+
+
+### Sourcetypes
+
+| sourcetype     | notes                                                                                                   |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| cp_log         | None                                                                                                    |
+
+### Sourcetype and Index Configuration
+
+| key            | sourcetype     | index          | notes          |
+|----------------|----------------|----------------|----------------|
+| checkpoint_splunk         | cp_log         | netfw          | none           |
+
+### Source and Index Configuration
+
+Checkpoint Software blades with CIM mapping have been sub-grouped into sources
+to allow routing to appropriate indexes. All other source meta data is left at default
+
+| key            | source     | index          | notes          |
+|----------------|----------------|----------------|----------------|
+| checkpoint_splunk_dlp         | dlp         | netdlp          | none           |
+| checkpoint_splunk_email         | email         | email          | none           |
+| checkpoint_splunk_firewall         | firewall         | netfw          | none           |
+| checkpoint_splunk_sessions         | sessions         | netops          | none           |
+| checkpoint_splunk_web         | web         | netproxy          | none           |
+
+### Filter type
+
+MSG Parse: This filter parses message content
+
+### Setup and Configuration
+
+* Install the Splunk Add-on on the search head(s) for the user communities interested in this data source. If SC4S is exclusively used the addon is not required on the indexer.
+* Review and update the splunk_index.csv file and set the index and sourcetype as required for the data source.
+* Follow vendor configuration steps per Product Manual above 
+
+### Options
+
+| Variable       | default        | description    |
+|----------------|----------------|----------------|
+| SC4S_LISTEN_CHECKPOINT_SPLUNK_TCP_PORT      | empty string      | Enable a TCP port for this specific vendor product using the port number defined |
+| SC4S_LISTEN_CHECKPOINT_SPLUNK_UDP_PORT      | empty string      | Enable a UDP port for this specific vendor product using the port number defined |
+| SC4S_ARCHIVE_CHECKPOINT_SPLUNK | no | Enable archive to disk for this specific source |
+| SC4S_DEST_CHECKPOINT_SPLUNK_HEC | no | When Splunk HEC is disabled globally set to yes to enable this specific source | 
+
+### Verification
+
+Use the following search to validate events are present
+
+```
+index=<asconfigured> sourcetype=cp_log
+```
+
+Verify timestamp, and host values match as expected   
diff --git a/docs/sources/Cisco/index.md b/docs/sources/Cisco/index.md
@@ -0,0 +1,236 @@
+# Vendor - Cisco
+
+## Product - ASA (Pre Firepower)
+
+| Ref            | Link                                                                                                    |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| Splunk Add-on  | https://splunkbase.splunk.com/app/1620/                                                                 |
+| Product Manual | https://www.cisco.com/c/en/us/td/docs/security/asa/asa82/configuration/guide/config/monitor_syslog.html |
+
+
+### Sourcetypes
+
+| sourcetype     | notes                                                                                                   |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| cisco:asa      | None                                                                                                    |
+| cisco:pix      | Not supported                                                                                           |
+| cisco:fwsm     | Not supported                                                                                           |
+
+### Sourcetype and Index Configuration
+
+| key            | sourcetype     | index          | notes          |
+|----------------|----------------|----------------|----------------|
+| cisco_asa      | cisco:asa      | netfw          | none           |
+
+
+### Filter type
+
+MSG Parse: This filter parses message content
+
+### Setup and Configuration
+
+* Install the Splunk Add-on on the search head(s) for the user communities interested in this data source. If SC4S is exclusively used the addon is not required on the indexer.
+* Review and update the splunk_index.csv file and set the index and sourcetype as required for the data source.
+* Follow vendor configuration steps per Product Manual above ensure:
+    * Log Level is 6 "Informational"
+    * Protocol is TCP/IP
+    * permit-hostdown is on
+    * device-id is hostname and included
+    * timestamp is included
+
+### Options
+
+| Variable       | default        | description    |
+|----------------|----------------|----------------|
+| SC4S_LISTEN_CISCO_ASA_TCP_PORT      | empty string      | Enable a TCP port for this specific vendor product using the number defined expecting RFC5424 format |
+| SC4S_LISTEN_CISCO_ASA_UDP_PORT      | empty string      | Enable a UDP port for this specific vendor product using the number defined expecting RFC5424 format |
+| SC4S_ARCHIVE_CISCO_ASA | no | Enable archive to disk for this specific source |
+| SC4S_DEST_CISCO_ASA_HEC | no | When Splunk HEC is disabled globally set to yes to enable this specific source | 
+| SC4S_LISTEN_CISCO_ASA_LEGACY_TCP_PORT      | empty string      | Enable a TCP port for this specific vendor product using the number defined expecting RFC3164 format |
+| SC4S_LISTEN_CISCO_ASA_LEGACY_UDP_PORT      | empty string      | Enable a UDP port for this specific vendor product using the number defined expecting RFC3164 format |
+| SC4S_ARCHIVE_CISCO_ASA_LEGACY | no | Enable archive to disk for this specific source |
+| SC4S_DEST_CISCO_ASA_LEGACY_HEC | no | When Splunk HEC is disabled globally set to yes to enable this specific source | 
+
+### Verification
+
+Use the following search to validate events are present
+
+```
+index=<asconfigured> sourcetype=cisco:asa
+```
+
+Verify timestamp, and host values match as expected    
+
+## Product - IOS and NX-OS based equipment
+
+| Ref            | Link                                                                                                    |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| Splunk Add-on  | https://splunkbase.splunk.com/app/1467/                                                                 |
+| IOS Manual     | https://www.cisco.com/c/en/us/td/docs/switches/lan/catalyst2960/software/release/12-2_55_se/configuration/guide/scg_2960/swlog.html |
+| NX-OS Manual   | https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus9000/sw/6-x/system_management/configuration/guide/b_Cisco_Nexus_9000_Series_NX-OS_System_Management_Configuration_Guide/sm_5syslog.html|
+| Cisco ACI      | https://community.cisco.com/legacyfs/online/attachments/document/technote-aci-syslog_external-v1.pdf |
+| Cisco WLC & AP | https://www.cisco.com/c/en/us/support/docs/wireless/4100-series-wireless-lan-controllers/107252-WLC-Syslog-Server.html#anc8 |
+
+### Sourcetypes
+
+| sourcetype     | notes                                                                                                   |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| cisco:ios      | This source type is also used for NX-OS, ACI and WLC product lines                                                                                                    |
+
+### Sourcetype and Index Configuration
+
+| key            | sourcetype     | index          | notes          |
+|----------------|----------------|----------------|----------------|
+| cisco_ios      | cisco:ios      | netops          | none          |
+| cisco_nx_os    | cisco:ios      | netops          | none          |
+
+### Filter type
+
+* Cisco IOS products can be identified by message parsing alone
+* Cisco NX OS, WLC, and ACI products must be identified by host or ip assignment update the filter `f_cisco_nx_os` as required
+
+
+### Setup and Configuration
+
+* Install the Splunk Add-on on the search head(s) for the user communities interested in this data source. If SC4S is exclusively used the addon is not required on the indexer.
+* Review and update the splunk_index.csv file and set the index and sourcetype as required for the data source.
+* IOS Follow vendor configuration steps per Product Manual above ensure:
+    * Ensure a reliable NTP server is set and synced
+    * Log Level is 6 "Informational"
+    * Protocol is TCP/IP
+    * permit-hostdown is on
+    * device-id is hostname and included
+    * timestamp is included
+* NX-OS Follow vendor configuration steps per Product Manual above ensure:
+    * Ensure a reliable NTP server is set and synced
+    * Log Level is 6 "Informational" user may select alternate levels by module based on use cases
+    * Protocol is TCP/IP
+    * device-id is hostname and included
+    * timestamp is included and milisecond accuracy selected
+* ACI Logging configuration of the ACI product often varies by use case.
+    * Ensure NTP sync is configured and active
+    * Ensure proper host names are configured
+* WLC
+    * Ensure NTP sync is configured and active
+    * Ensure proper host names are configured
+    * For security use cases per AP logging is required
+
+### Options
+
+| Variable       | default        | description    |
+|----------------|----------------|----------------|
+| SC4S_LISTEN_CISCO_IOS_UDP_PORT      | empty string      | Enable a TCP port for this specific vendor product using the number defined |
+| SC4S_LISTEN_CISCO_IOS_TCP_PORT      | empty string      | Enable a UDP port for this specific vendor product using the number defined |
+| SC4S_ARCHIVE_CISCO_IOS | no | Enable archive to disk for this specific source |
+| SC4S_DEST_CISCO_IOS_HEC | no | When Splunk HEC is disabled globally set to yes to enable this specific source | 
+| SC4S_LISTEN_CISCO_NX_OS_TCP_PORT      | empty string      | Enable a TCP port for this specific vendor product using the number defined |
+| SC4S_LISTEN_CISCO_NX_OS_UDP_PORT      | empty string      | Enable a UDP port for this specific vendor product using the number defined |
+| SC4S_ARCHIVE_CISCO_NXOS | no | Enable archive to disk for this specific source |
+| SC4S_DEST_CISCO_NXOS_HEC | no | When Splunk HEC is disabled globally set to yes to enable this specific source | 
+
+### Verification
+
+Use the following search to validate events are present, for NX-OS, WLC and ACI products ensure each host filter condition is verified
+
+```
+index=<asconfigured> sourcetype=cisco:ios | stats count by host
+```
+
+## Product - ISE
+
+| Ref            | Link                                                                                                    |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| Splunk Add-on  | https://splunkbase.splunk.com/app/1915/                                                                 |
+| Product Manual | https://www.cisco.com/c/en/us/td/docs/security/ise/2-6/Cisco_ISE_Syslogs/Cisco_ISE_Syslogs/Cisco_ISE_Syslogs_chapter_00.html |
+
+
+### Sourcetypes
+
+| sourcetype     | notes                                                                                                   |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| cisco:ise:syslog     | Aggregation used                                                                                                    |
+
+### Sourcetype and Index Configuration
+
+| key            | sourcetype     | index          | notes          |
+|----------------|----------------|----------------|----------------|
+| cisco_ise     | cisco:ise:syslog    | netauth          | None     |
+
+
+### Filter type
+
+PATTERN MATCH
+
+### Setup and Configuration
+
+* No special steps required
+
+### Options
+
+| Variable       | default        | description    |
+|----------------|----------------|----------------|
+| SC4S_LISTEN_CISCO_ISE_TCP_PORT      | empty string      | Enable a TCP port for this specific vendor product using the number defined expecting RFC5424 format |
+| SC4S_LISTEN_CISCO_ISE_UDP_PORT      | empty string      | Enable a UDP port for this specific vendor product using the number defined expecting RFC5424 format |
+| SC4S_ARCHIVE_CISCO_ISE | no | Enable archive to disk for this specific source |
+| SC4S_DEST_CISCO_ISE_HEC | no | When Splunk HEC is disabled globally set to yes to enable this specific source | 
+
+### Verification
+
+Use the following search to validate events are present
+
+```
+index=<asconfigured> sourcetype=cisco:ise:syslog
+```
+
+Verify timestamp, and host values match as expected    
+
+## Product - Meraki Product Line MR, MS, MX, MV
+
+| Ref            | Link                                                                                                    |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| Splunk Add-on  | https://splunkbase.splunk.com/app/3018/                                                                 |
+| Product Manual | https://documentation.meraki.com/zGeneral_Administration/Monitoring_and_Reporting/Syslog_Server_Overview_and_Configuration |
+
+
+### Sourcetypes
+
+| sourcetype     | notes                                                                                                   |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| merkai     | None                                                                                                    |
+
+### Sourcetype and Index Configuration
+
+| key            | sourcetype     | index          | notes          |
+|----------------|----------------|----------------|----------------|
+| cisco_meraki     | meraki    | netfw          | The current TA does not sub sourcetype or utilize source preventing segmenation into more appropriate indexes           |
+
+
+### Filter type
+
+IP, Netmask, Host or Port
+
+### Setup and Configuration
+
+* Install the Splunk Add-on on the search head(s) for the user communities interested in this data source. If SC4S is exclusively used the addon is not required on the indexer.
+* Review and update the splunk_index.csv file and set the index and sourcetype as required for the data source.
+* Follow vendor configuration steps per Product Manual above
+
+### Options
+
+| Variable       | default        | description    |
+|----------------|----------------|----------------|
+| SC4S_LISTEN_CISCO_MERAKI_TCP_PORT      | empty string      | Enable a TCP port for this specific vendor product using the number defined expecting RFC5424 format |
+| SC4S_LISTEN_CISCO_MERAKI_UDP_PORT      | empty string      | Enable a UDP port for this specific vendor product using the number defined expecting RFC5424 format |
+| SC4S_ARCHIVE_CISCO_MERAKI | no | Enable archive to disk for this specific source |
+| SC4S_DEST_CISCO_MERAKI_HEC | no | When Splunk HEC is disabled globally set to yes to enable this specific source | 
+
+### Verification
+
+Use the following search to validate events are present
+
+```
+index=<asconfigured> sourcetype=merkai
+```
+
+Verify timestamp, and host values match as expected    
+