added documentation for BlueChi's revised SELinux policy

This PR reorders the table of contents for the readthedoc
and bundles the mTLS as well as the networking and the
new SELinux subsection together under the Security section.

Signed-off-by: Michael Engel <mengel@redhat.com>

doc/docs/security/index.md

@@ -0,0 +1,36 @@
+<!-- markdownlint-disable-file MD013-->
+# Security
+
+As a distributed system, BlueChi is subject to attacks from malicious actors within the network.
+However, similar to other services, protective measures can be employed to defend against such scenarios. By setting up [firewall rules](#setup-firewall-rules) and [IP address filter](#setup-ip-address-filter) the attack surface can be reduced. The security of the system can be enhanced even further by leveraging [BlueChi's SELinux policy](./selinux.md) as well as setting up a [double proxy for mTLS encryption](./securing_multi_node.md).
+
+## Setup firewall rules
+
+By using [firewalld](https://firewalld.org/), rules can be defined to secure BlueChi and the overall system:
+
+``` bash
+# Install firewalld
+$ sudo dnf install firewalld
+
+# Enable and start the service
+$ sudo systemctl enable --now firewalld
+
+# Allow communication on port 842/tcp
+$ sudo firewall-cmd --permanent --zone=public --add-port=842/tcp
+
+# Block a specific IP address from a malicious agent
+$ sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="ADD_HERE_MALICIOUS_IP_FROM_BAD_ACTOR" port port="842" protocol="tcp" drop'
+
+# Reload firewalld with the new configuration
+$ sudo firewall-cmd --reload
+```
+
+## Setup IP address filter
+
+Additionally, [iptables](https://linux.die.net/man/8/iptables) can be utilized to block connections from any IP address that attempts excessive connections:
+
+``` bash
+sudo iptables -A INPUT -p tcp --dport 842 -m conntrack --ctstate NEW -m recent --name BLUECHIRULE --set
+
+sudo iptables -A INPUT -p tcp --dport 842 -m conntrack --ctstate NEW -m recent --name BLUECHIRULE --update --seconds 60 --hitcount 5 -j DROP
+```

doc/docs/getting_started/securing_multi_node.md → doc/docs/security/securing_multi_node.md

@@ -6,7 +6,7 @@ not only between bluechi-agent and systemd, but also between bluechi-controller
 
 The problem is that D-Bus mainly targets local inter-process communication on top of Unix sockets
 and therefore does not natively support encryption or authentication.
-One possible solution is to use SSH, however, SSH between nodes is too large of a tunnel.
+One possible solution is to use SSH. However, SSH between nodes is too large of a tunnel.
 
 ## The double proxy approach
 

doc/docs/security/selinux.md

@@ -0,0 +1,44 @@
+<!-- markdownlint-disable-file MD013-->
+# BlueChi's SELinux policy
+
+BlueChi provides a custom SELinux policy, limiting access of the `bluechi-controller` and `bluechi-agent`. It can be installed via
+
+```bash
+dnf install bluechi-selinux
+```
+
+By default, the package allows `bluechi-controller` to bind and `bluechi-agent` to connect to any port so that changes of the [ControllerPort](../man/bluechi-agent-conf.md#controllerport-uint16_t) are not being blocked.
+
+## Enforce port restrictions
+
+In order to allow BlueChi to only use one port, the usage of any needs to be disabled with [setsebool](https://linux.die.net/man/8/setsebool):
+
+```bash
+# Turn off the any policy for bluechi-controller
+setsebool -P bluechi_controller_port_bind_any 0
+
+# Turn off the any policy for bluechi-agent
+setsebool -P bluechi_agent_port_connect_any 0
+```
+
+Subsequently, the desired port needs to be allowed by using [semanage](https://linux.die.net/man/8/semanage):
+
+```bash
+# Set the allowed port for bluechi-controller
+semanage port -a -t bluechi_port_t -p tcp <port>
+
+# Set the allowed port for bluechi-agent
+semanage port -a -t bluechi_agent_port_t -p tcp <port>
+```
+
+## Change from enforcing to permissive
+
+By default, BlueChi will enforce its SELinux policy. By using [semanage](https://linux.die.net/man/8/semanage) the permissive property can be added so that violations are blocked and create only an AVC entry:
+
+```bash
+# add the permissive property to bluechi-controller
+semanage permissive -a bluechi_t
+
+# add the permissive property to bluechi-agent
+semanage permissive -a bluechi_agent_t
+```

doc/mkdocs.yml

@@ -14,23 +14,24 @@ nav:
     - Multi-Node Setup: getting_started/multi_node.md
     - Using bluechictl: getting_started/examples_bluechictl.md
     - Cross-node dependencies: getting_started/cross_node_dependencies.md
-    - Securing connection with mTLS: getting_started/securing_multi_node.md
-  - Configuration: configuration.md
-  - Ansible:
-    - ansible/index.md
+  - BlueChi's API:
+    - Description: api/description.md
+    - Using the D-Bus API: api/examples.md
+    - Generating clients: api/client_generation.md
   - Monitoring:
     - monitoring/index.md
     - Peer Listener: monitoring/peers.md
-  - Network:
-    - network/index.md
   - Cross-Node Dependencies:
     - cross_node_dependencies/index.md
     - Proxy Services: cross_node_dependencies/proxy_services.md
     - Using Proxy Services: cross_node_dependencies/usage.md
-  - BlueChi's API:
-    - Description: api/description.md
-    - Using the D-Bus API: api/examples.md
-    - Generating clients: api/client_generation.md
+  - Ansible:
+    - ansible/index.md
+  - Security:
+    - security/index.md
+    - Securing connection with mTLS: security/securing_multi_node.md
+    - SELinux: security/selinux.md
+  - Configuration: configuration.md
   - MAN Pages:
     - Binaries:
       - bluechi-controller(1): man/bluechi-controller.md