Merge pull request #104 from reyesj2/updpro

doc update

administration.rst

@@ -62,6 +62,8 @@ If you're not sure of which component a particular setting may belong to, you ca
 
 Some settings can be applied across the entire grid or to specific nodes. If you apply a setting to a specific node, it will override the grid setting.
 
+.. _administration-advanced-settings:
+
 Advanced Settings
 ~~~~~~~~~~~~~~~~~
 

kafka.rst

@@ -0,0 +1,85 @@
+.. _kafka:
+
+Kafka
+=====
+
+From https://kafka.apache.org :
+
+    Apache Kafka is an open-source distributed event streaming platform used by thousands of companies for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications.
+
+Kafka for guaranteed message delivery replaces :ref:`redis` and :ref:`logstash` on the Security Onion Manager node and Receiver nodes in order to provide the same benefits available when using the standard Security Onion deployment model with Receiver nodes for pipeline redundancy. However, Kafka can provide some additional benefits.
+
+.. note::
+
+    This is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonionsolutions.com for more information about purchasing a Security Onion Pro license to enable this feature.
+
+Guaranteed Message Delivery
+---------------------------
+By leveraging Kafka, we can ensure that messages sent to the Kafka cluster are written to disk on the partition leader and replicated to other physical brokers before acknowledging recipt to the producer.
+
+For more information, please see https://kafka.apache.org/documentation/#producerconfigs_acks
+
+High Availability
+-----------------
+With a properly configured Kafka cluster, data integrity and data availability are maintained even in the event of a Kafka broker / controller failure. In order to start taking advantage of Kafka we'd recommend three Kafka controllers and a minimum of three Kafka brokers. With this configuration you can increase your replication factor to ensure that messages are replicated to multiple brokers.
+
+For more information, please see https://kafka.apache.org/documentation/#replication
+
+
+Configuration
+-------------
+.. important::
+
+    | Before configuring Kafka, it is recommened you build your grid as you would normally. Including adding any receiver nodes that will later be repurposed as Kafka brokers / controllers.
+    |
+    | Also note that :ref:`Guaranteed Message Delivery <kafka>` which leverages Kafka, requires a valid Security Onion license. See :ref:`pro`.
+
+You can modify your Kafka configuration by going to :ref:`administration` --> Configuration --> Kafka.
+
+.. image:: images/config-item-kafka.png
+  :target: _images/config-item-kafka.png
+
+Controllers
+~~~~~~~~~~~
+Controllers are responsible for managing the Kafka cluster. They are responsible for electing a leader and managing the cluster metadata. Controllers can be relatively lightweight virtual machines or physical machines.
+
+A system with 4 CPU cores, 8GB of RAM, and 200GB storage should be sufficient for a single Kafka controller.
+
+Controllers are assigned by adding the hostnames to the "controllers" configuration option separated by a comma.
+::
+
+    hostname1,hostname2,hostname3
+
+We recommend that you have atleast three controllers. This allows for a single controller to fail and the cluster to continue to operate.
+
+For more information, please see https://kafka.apache.org/documentation/#kraft_voter
+
+Brokers
+~~~~~~~
+Brokers are responsible for the storage and replication of messages. With Kafka enabled the Elastic Agent will begin to act as a producer and write its messages to topics stored on Kafka the broker(s). Brokers require much more resources than controllers as they are responsible for managing the data and providing the data to consumers.
+
+Sizing brokers depends heavily on expected message volume. A system with 8 CPU cores, 32GB of RAM, and 500GB storage should be sufficient for a single Kafka broker.
+
+.. warning::
+
+   | The above hardware recommendations should be used as a minimum. Increasing the number of brokers and the resources available to each broker will increase the overall performance of the Kafka cluster. Additionally, without sufficient storage space on each broker, the cluster may run out of space and stop accepting messages. The brokers log.retention.hours can be configured to delete messages after a certain amount of time to prevent this from happening.
+
+Broker configuration can be modified by going to :ref:`administration` --> Configuration --> Kafka --> config --> broker
+
+For more information, please see https://kafka.apache.org/documentation/#brokerconfigs
+
+Enabling Kafka
+~~~~~~~~~~~~~~
+Once you have the appropriate configuration in place, you can enable Kafka by navigating to :ref:`administration` --> Configuration --> global --> pipeline and setting the value to KAFKA.
+
+There is no need to click on the ``SYNCHRONIZE GRID``. Once you have set the global pipeline value to KAFKA, the changes will begin to take affect in the background before finally switching the grid to the new pipeline.
+
+.. note::
+
+    | In order to change the global pipeline you will need to enable the :ref:`administration-advanced-settings` option.
+
+More information
+----------------
+.. note::
+
+   | For more information about Kafka, please see: https://kafka.apache.org/documentation/#gettingStarted

luks.rst

@@ -25,3 +25,19 @@ LUKS Install Options with a TPM
 -------------------------------
 
 If a TPM module is installed in the system you will have the option of storing the key in the TPM to unlock the drives automatically at boot. This process uses clevis in order to manage this process.   
+
+LUKS TPM enrollment / re-enrollment
+-----------------------------------
+There may be a case where you have already installed Security Onion with LUKS enabled, but did not opt-in to use your TPM for automatic decryption at boot. In this case, you can use the ``so-luks-tpm-regen`` script to enroll the TPM and configure it for automatic decryption.
+
+SSH to the Security Onion node and run the following command:
+
+::
+
+    sudo so-luks-tpm-regen --enroll-tpm
+
+Similarly, if for any reason automatic decryption was previously enabled using the ISO and has now stopped working you can re-enroll the TPM.
+
+::
+
+    sudo so-luks-tpm-regen

pro.rst

@@ -5,7 +5,9 @@ Security Onion Pro
 
 In 2022, we announced that we would be releasing enterprise features that would only be available to paid users of the platform. You can read the announcement at https://blog.securityonion.net/2022/08/security-onion-enterprise-features-and.html.
 
-Starting in Security Onion 2.4.70, licensed users of Security Onion Pro can activate the following features: :ref:`oidc` 3rd-party authentication, :ref:`luks` disk encryption, :ref:`fips` OS compliance, :ref:`stig` OS compliance, :ref:`notifications`, and time tracking inside of :ref:`cases`. In a future release, we will add guaranteed message delivery as a Pro feature.
+Starting in Security Onion 2.4.70, licensed users of Security Onion Pro can activate the following features: :ref:`oidc` 3rd-party authentication, :ref:`luks` disk encryption, :ref:`fips` OS compliance, :ref:`stig` OS compliance, :ref:`notifications`, and time tracking inside of :ref:`cases`.
+
+With the release of Security Onion 2.4.80 we're introducing :ref:`Guaranteed Message Delivery <kafka>` support leveraging Kafka for Security Onion Pro.
 
 .. note::
 
@@ -19,3 +21,4 @@ Starting in Security Onion 2.4.70, licensed users of Security Onion Pro can acti
    fips   
    stig
    notifications
+   kafka

stig.rst

@@ -9,7 +9,45 @@ STIG stands for Security Technical Implementation Guide. For more information ab
 
     This is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonionsolutions.com for more information about purchasing a Security Onion Pro license to enable this feature.
 
-Enabling STIG During the ISO Install   
-------------------------------------
+STIG During the ISO Install
+---------------------------
 
 The recommended way to use STIG with Security Onion is to install via our Security Onion ISO image. At the ISO boot menu, you'll need to modify the boot command. This can be done using the ``e`` key in UEFI boot mode or the ``Tab`` key in BIOS boot mode before it automatically boots. Then append ``stig=1`` (and possibly other options like :ref:`fips` and :ref:`luks`) to the boot parameters and continue the boot process.
+
+Specifying ``stig=1`` before installing with the Security Onion ISO will create the following partitions:
+
+==============       =========
+ Partition            Storage
+==============       =========
+/home                  25GB
+/tmp                   2GB
+/var                   50GB
+/var/log               5GB
+/var/log/audit         2GB
+/var/log/tmp           2GB
+==============       =========
+
+Enabling STIG
+-------------
+.. warning::
+
+    | Before enabling STIGs on your production Security Onion deployment, we recommend testing in a development environment. With different environments and configurations, there may be unexpected errors.
+
+To enable STIGs you'll first need setup your Security Onion grid and apply your :ref:`Security Onion Pro <pro>` license. You can then navigate to :ref:`administration` --> Configuration --> stig --> enabled and set the value to ``true``.
+
+.. note::
+
+    | You will need to enable the :ref:`administration-advanced-settings` option to modify this setting.
+
+OpenSCAP
+--------
+In order to apply STIGs on Security Onion we use a combination of our existing Saltstack configuration managment and OpenSCAP. Currently, OpenSCAP is using a draft version of STIGs for Oracle Linux 9.
+
+OpenScap can be configured to run at different time intervals. By default, OpenSCAP will run a remediation every 12 hours meaning any changes made to the system that bring it out of compliance will be reverted back to the STIG compliant state. This setting can be lowered or increased by modifying the ``run_interval`` setting found under :ref:`administration` --> Configuration --> stig
+
+With the STIG feature enabled, you can find OpenSCAP reports under ``/opt/so/log/stig``. Currently, the expected compliance score is 86%.
+
+More information
+----------------
+For more information about OpenSCAP see: https://www.open-scap.org/
+For more information about STIGs see: https://public.cyber.mil/stigs/