docs: complete all missing sections (#38)

* docs: add chown root for fbeat cfg and sh prompt

* docs: add section on directive rules

* docs: add an example for taxo plugin

* docs: minor formatting fix

* docs: complete the section on web interfaces

* docs: add link to section on directive rules

* docs: minor rearrangement and fixes

* docs: add implementation note for custom_data

* docs: minor punc fix

docs/README.md

@@ -5,11 +5,11 @@ This directory contains Dsiem documentation pages until there's a need for a ded
 Available topics are:
 
 * [Installation](./installation.md)
-* [Event Processing Flow](./event_processing.md)
-* [Directive and Alarm Processing](./directive_and_alarm.md)
+* [Web Interfaces](./web_interfaces.md)
 * [Dsiem Command and Tools](./commands.md)
-* [Web Interfaces](./web_interface.md)
+* [Event Processing Flow](./event_processing.md)
 * [Dsiem Plugin](./dsiem_plugin.md)
+* [Directive and Alarm](./directive_and_alarm.md)
 * [Threat Intel and Vulnerability Lookup Plugins](./ti_vuln_plugins.md)
 * [Advanced Deployment](./adv_deployment.md)
 * [Notes on Security](./security.md)

docs/adv_deployment.md

@@ -1,14 +1,14 @@
 # Advanced Deployment
 
-Dsiem support clustering mode for horizontal scalability. In this mode, each instance of dsiem will run either as frontend or backend node, with NATS messaging in between to facilitate communication. The architecture is depicted in the following diagram.
+Dsiem supports clustering mode for horizontal scalability. In this mode, each instance of dsiem will run either as frontend or backend node, with NATS messaging in between to facilitate communication. The architecture is depicted in the following diagram.
 
-![Advanced Architecture](/docs/images/advanced-arch.png)
+![Advanced Architecture](./images/advanced-arch.png)
 
 ## About the Architecture
 
-* Frontend nodes is responsible for validating and parsing incoming normalized events from Logstash, and forwarding its results to backend nodes through NATS messaging system. Since frontends do not maintain states, Logstash can be easily configured to load balance between them (for example, using DNS round-robin or Kubernetes load balancer).
+* Frontend nodes are responsible for validating and parsing incoming normalized events from Logstash, and forwarding results to backend nodes through NATS messaging system. Since frontends do not maintain states, Logstash can be easily configured to load balance between them (for example, using DNS round-robin or Kubernetes load balancer).
 
-* Each backend node is assigned with a different set of (exclusive) directive rules to use for processing events. For example, a directive rule for detecting port scan maybe assigned only to backend A, and another directive that alert on SSH failed logins maybe assigned only to backend B. This simple way of distributing workload means that all the backends can work independently, using an in memory storage, and do not have to share states with each other.
+* Each backend node is assigned with a different set of (exclusive) directive rules to use for processing events. For example, a directive rule for detecting port scan maybe assigned only to backend A, and another directive that alert on SSH failed logins maybe assigned only to backend B. This simple way of distributing workload means that all backends can work independently, using an in memory storage, and do not have to sync states with each other.
 
 * That however, does entail that *every* event sent from frontends will have to be delivered/broadcasted to all backends in order to evaluate them against all rules. This could potentially introduce network bottleneck from NATS to backends. It also means that the rules assigned to a failing backend will not be picked up by other nodes.
 

docs/commands.md

@@ -116,7 +116,7 @@ Global Flags:
       --dev     Enable development environment specific setting
 ```
 
-We try to provide sensible defaults, so there's no need to supply additional flags unless there's a specific need for it. For instance, in order to run dsiem in standalone mode you only need to run:
+We try to provide sensible defaults, so there's no need to supply additional flags unless there's a specific need to override them. For instance, in order to run dsiem in standalone mode you only need to run:
 ```shell
 $ ./dsiem serve
 ```

docs/directive_and_alarm.md

@@ -2,7 +2,21 @@
 
 Similar to [OSSIM](https://www.alienvault.com/products/ossim), Dsiem directive contains a set of rules that will be used to evaluate incoming [Normalized Events](./dsiem_plugin.md#normalized-event). Directive triggers alarms when enough of its rules condition are met.
 
-The following is an example of a dsiem directive.
+## About Directive Rules
+
+There are two types of directive rules in Dsiem, `PluginRule` and `TaxonomyRule`. As suggested in the [Normalized Events](./dsiem_plugin.md#normalized-event) table, `PluginRule` differentiates events based on `PluginID` and `Plugin_SID` fields, while TaxonomyRule uses `Product`, `Category`, and optionally `Subcategory` fields.
+
+`PluginRule` should be used if you want to do correlation based on specific events produced by specific brand of devices. On the other hand, `TaxonomyRule` allows correlation to be done based on a group of events that share similar characteristic.
+
+As an example, suppose you have the following security devices in your network: Suricata IDS, SomebrandNG IDS, Pfsense Firewall, SomeRouterNG Firewall. `PluginRule` will allow you to define a directive that says, "Raise alarm if Suricata IDS detects SQL injection or XSS attacks that isn't blocked by SomeRouterNG Firewall". In contrast, `TaxonomyRule` allow definition of a more general directive that says, "Raise alarm if an IDS detects web application attack that isn't blocked by firewall".
+
+Despite its obvious flexibility, `TaxonomyRule` does require you to maintain a custom classification/taxonomy scheme that isn't required by `PluginRule`. In the above example, using `TaxonomyRule` means you will have to know and classify which events from Suricata or SomebrandNG are "web application attack", and which events in PfSense and SomeRouterNG means "not blocking".
+
+As a general guide, `TaxonomyRule` should be preferred when there are similar types of product (like IDS and firewall above) to cover since it will prevent a lot of redundant directives. But if that's not the case, `PluginRule` will likely offer an easier to maintain plugin/parser configuration.
+
+## Directive and Rules Processing
+
+The following is an example of a dsiem directive that has several `PluginRule`.
 
 ```json
 {
@@ -60,12 +74,12 @@ Where:
 
 Given the above, we can calculate that risk value of any backlog will vary from 0.4 when all parameters are at their minimum, to 10 when all parameters are at their maximum. Since alarm will only be created when that value is ≥ 1, we can also deduce that the risk range of any alarm will be from 1 to 10.
 
-By using [Dsiem startup parameter](commands.md#dsiem-command-flags), you can then configure when will an alarm be labeled as Low, Medium or High risk based on that range. The default thresholds are:
+By using [Dsiem startup parameter](commands.md#dsiem-command-flags), you can then configure when should an alarm be labeled as Low, Medium or High risk based on that range. The default thresholds are:
 - Low risk ⟶ risk value of 1 to 2
 - Medium risk ⟶ risk value of 3 to 6
 - High risk ⟶ risk value of 7 to 10 
 
-### Example Directive to Alarm Processing
+### Example Directive ⟶ Alarm Processing
 
 Let's say Dsiem is configured with the above `Ping Flood from SRC_IP` directive, and an `assets_*.json` that defines an asset value of 2 for `10.0.0.0/8` network.
 
@@ -100,4 +114,4 @@ The following processing will take place:
   * the 8th to 15th events match backlog #1 3rd rule condition, and each will  increase the backlog's event count and reset its internal timeout timer.
   * None of these events match backlog #2 2nd rule condition.
 
-Then if no more matching event is found, backlog #2 will expires and be removed after 10 minutes (600s), while backlog #1 will expires in 1 hour (3600s).
+Then if no more matching event is found, backlog #2 will expires and be removed after 10 minutes (600s), while backlog #1 will expires in 1 hour (3600s).