From bb4973024273db9ee07716c4ec8fc8d54e6ddaf5 Mon Sep 17 00:00:00 2001
From: Douglas Schilling Landgraf <dougsland@redhat.com>
Date: Thu, 8 Feb 2024 09:56:32 -0500
Subject: [PATCH] doc: add information about firewall in the docs

Add documentation to users regarding firewalld and iptables
for BlueChi.

Fixes: https://github.com/eclipse-bluechi/bluechi/issues/648

Signed-off-by: Douglas Schilling Landgraf <dougsland@redhat.com>
Signed-off-by: Michael Engel <mengel@redhat.com>
---
 doc/docs/network/index.md | 43 +++++++++++++++++++++++++++++++++++++++
 doc/mkdocs.yml            |  2 ++
 2 files changed, 45 insertions(+)
 create mode 100644 doc/docs/network/index.md

diff --git a/doc/docs/network/index.md b/doc/docs/network/index.md
new file mode 100644
index 0000000000..c66da525aa
--- /dev/null
+++ b/doc/docs/network/index.md
@@ -0,0 +1,43 @@
+<!-- markdownlint-disable-file MD013 MD033 -->
+# Network
+
+The BlueChi controller is exposed on TCP port 842, making it subject to attacks from malacious actors within the network. However, similar to other services, protective measures can be employed to defend it. By configuring firewall rules within the system, VLANs or network devices.
+
+As example, let's see Distributed Denial of Service (DDoS) attacks scenario. These attacks can overwhelm its infrastructure by flooding it with an immense volume of traffic, disrupting normal operations and potentially causing significant downtime.
+
+Below some examples to defend it using firewalld and iptables:
+
+## Setup firewall rules
+
+``` 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, users can also utilize iptables to block connections from any IP address that attempts excessive connections, such as reaching a count of **1000**.
+
+``` 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
+```
+
+## Securing connections
+
+Briefly mentioning that the communication between the BlueChi components is, by default, not secured and that the getting started guide provides an possible approach using a double proxy to achieve that.
+
+For more information, [see our documentation page](../getting_started/securing_multi_node.md).
diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index 3670765440..68e937862b 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -19,6 +19,8 @@ nav:
   - 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