update docs & add intro-gif

superstes · superstes · commit 756560cf328d · 2025-11-01T12:46:15.000+01:00
diff --git a/README.md b/README.md
@@ -8,6 +8,8 @@ A framework for **testing and troubleshooting firewall rulesets**.
 
 [Module on pypi.org](https://pypi.org/project/firewall-test/)
 
+<img src="https://raw.githubusercontent.com/O-X-L/firewall-testing-framework/refs/heads/latest/docs/source/_static/img/opnsense.gif" alt="Intro GIF" width="70%"/>
+
 ----
 
 ## Documentation
diff --git a/docs/source/_static/img/opnsense.gif b/docs/source/_static/img/opnsense.gif
diff --git a/docs/source/dev/1_intro.rst b/docs/source/dev/1_intro.rst
@@ -44,11 +44,17 @@ Out-of-Scope
 Some of this features might be make sense later on.
 
 * Transparent firewalls (layer 2 interception)
+
 * Non-IP traffic (layer 2 ARP/bridge layer)
+
 * Application-Level Protocols
+
 * Automatic connection-simulation
+
 * Rule-based routing (fwmark with routing-table lookup)
+
 * Simulation of dynamic routing (we only use the routes provided to the translate-plugins - static or runtime export)
+
 * Applying multiple DNAT or SNAT rules for a single packet
 
 Principles
@@ -124,23 +130,23 @@ The entrypoints are designed to be executed by the user.
 
 * :code:`cli` can be executed by the command :code:`ftf-cli`
 
- It is designed to be a one-shot simulation of a packet
+  It is designed to be a one-shot simulation of a packet
 
 * :code:`ci` can be executed by the command :code:`ftf-ci`
 
   .. warning::
 
-     To be implemented.
+    To be implemented.
 
- It is designed to simulate many packets. A test-traffic configuration-file needs to be provided!
+  It is designed to simulate many packets. A test-traffic configuration-file needs to be provided!
 
 * :code:`shell` can be executed by the command :code:`ftf-shell`
 
   .. warning::
 
-     To be implemented.
+    To be implemented.
 
- It is designed to be an interactive shell for simulating multiple packets.
+  It is designed to be an interactive shell for simulating multiple packets.
 
 ----
 
@@ -161,7 +167,9 @@ The network-traffic configuration as provided by the user is parsed to packets.
 The configuration-files provided by the user are loaded and parsed as configured for the target firewall-system.
 
 1. Loading the target-system config (:code:`plugins/system/*`)
+
 2. Reading the config-files provided by the user
+
 3. Parsing the configuration as implemented by the target-system-specific translate-plugins (:code:`plugins/translate/*`)
 
 ----
@@ -188,43 +196,43 @@ The configuration-files provided by the user are loaded and parsed as configured
 
 2. **It is checked which kind of traffic-flow applies**
 
-  * If the source or destination IPs are local to the firewall
+   * If the source or destination IPs are local to the firewall
 
-  * Estimated traffic-flow (:code:`input, forward or output`)
+   * Estimated traffic-flow (:code:`input, forward or output`)
 
 3. **The source-route is looked-up**
 
-  * The routing-simulator is queried for the source-route
+   * The routing-simulator is queried for the source-route
 
-  * Updates the inbound-interface
+   * Updates the inbound-interface
 
-  * Throws an error if no source-route was found
+   * Throws an error if no source-route was found
 
-  .. tip::
+   .. tip::
 
-      The detailed function of the :ref:`routing- and firewall-simulators are covered later on <dev_intro_router>`.
+       The detailed function of the :ref:`routing- and firewall-simulators are covered later on <dev_intro_router>`.
 
 4. **Pre-Routing and Pre-DNAT Firewall-Filters are processed**
 
 5. **Destination-NAT is processed**
 
-  * Updating if the destination IP is local to the firewall
+   * Updating if the destination IP is local to the firewall
 
-  * Updates the traffic-flow
+   * Updates the traffic-flow
 
 6. **The destination-route is looked-up**
 
-  * The routing-simulator is queried for the destination-route
+   * The routing-simulator is queried for the destination-route
 
-  * Updates the outbound-interface
+   * Updates the outbound-interface
 
-  * Throws an error if no destination-route was found
+   * Throws an error if no destination-route was found
 
 7. **System-specific filters**
 
-  * These are custom filters that might be outside the control of the firewall-ruleset itself (like Linux kernel)
+   * These are custom filters that might be outside the control of the firewall-ruleset itself (like Linux kernel)
 
-  * Drops traffic to bogon-networks on WAN - if the firewall-system if configured to
+   * Drops traffic to bogon-networks on WAN - if the firewall-system if configured to
 
 8. **Main Firewall-Filters are processed**
 
diff --git a/docs/source/plugins/firewall_opnsense.rst b/docs/source/plugins/firewall_opnsense.rst
@@ -6,6 +6,9 @@
 .. |export_network| image:: ../_static/img/plugin-opnsense-export.png
    :class: wiki-img-sm
 
+.. |intro_gif| image:: ../_static/img/opnsense.gif
+   :class: wiki-img-sm
+
 .. include:: ../_include/head.rst
 
 ===================
@@ -14,16 +17,31 @@ Firewall - OPNsense
 
 .. include:: ../_include/warn_develop.rst
 
+|intro_gif|
+
+Limitations
+###########
+
+* Currently only the main Firewall-Ruleset (:code:`Firewall - Rules`) is supported.
+
+  Support for the new Ruleset (:code:`Firewall - Automation - Filter`) will get added later on - if you have demand for it feel free to `open a feature-request <https://github.com/O-X-L/firewall-testing-framework/issues>`_.
+
+* Only the main match-expressions are currently supported.
+
+  See: :ref:`Config Parsing <plugins_fw_opnsense_cnf>`
+
+----
+
 Config Export
 #############
 
 1. `Download a Config-Backup <https://docs.opnsense.org/manual/backups.html>`_ (referenced as :code:`config.xml`)
 
-    |export_backup|
+   |export_backup|
 
 2. Download the current network status via the WebUI: :code:`Interfaces - Overview - Download Buttom` (referenced as :code:`network.json`)
 
-    |export_network|
+   |export_network|
 
 ----
 
@@ -156,6 +174,8 @@ Source Code
 
 ----
 
+.. _plugins_fw_opnsense_cnf:
+
 Config-Parsing
 ##############
 
diff --git a/docs/source/usage/1_intro.rst b/docs/source/usage/1_intro.rst
@@ -3,6 +3,10 @@
 .. |topology| image:: ../_static/img/topology.svg
    :class: wiki-img
 
+.. |intro_gif| image:: ../_static/img/opnsense.gif
+   :class: wiki-img-sm
+
+
 .. include:: ../_include/head.rst
 
 =========
@@ -11,6 +15,9 @@
 
 |topology|
 
+|intro_gif|
+
+
 Goal / Reason / Why?
 ####################
 
@@ -32,25 +39,25 @@ Automated Regression-Tests
 
 **Why would you want to do ruleset-regression-tests?**
 
-  * You may want/need to periodically verify that the currently active rulesets actually allow/deny the traffic you expect
+* You may want/need to periodically verify that the currently active rulesets actually allow/deny the traffic you expect
 
-    This can be a tedious task - you might overlook some edge-case.
+  This can be a tedious task - you might overlook some edge-case.
 
-  * Especially when a ruleset is administered by teams of engineers over a long time period - it can be a challenge to:
+* Especially when a ruleset is administered by teams of engineers over a long time period - it can be a challenge to:
 
-  * detect configuration errors/mistakes before they can be exploited
+* detect configuration errors/mistakes before they can be exploited
 
-  * make sure the design-choices for the ruleset are adhered to
+* make sure the design-choices for the ruleset are adhered to
 
-  * If you already utilize Infrastructure-as-Code and change-reviews for updating your rulesets you might want to also validate the functionality of that ruleset via automated CI-jobs.
+* If you already utilize Infrastructure-as-Code and change-reviews for updating your rulesets you might want to also validate the functionality of that ruleset via automated CI-jobs.
 
 **How do regression-tests work?**
 
-  * You define test-cases that simulate traffic over one or multiple firewalls
+* You define test-cases that simulate traffic over one or multiple firewalls
 
-  * You assert that the traffic was allowed/denied/rejected
+* You assert that the traffic was allowed/denied/rejected
 
-  * You might even want to assert that the traffic took a specific outbound route or was NATed to a specific IP
+* You might even want to assert that the traffic took a specific outbound route or was NATed to a specific IP
 
 This way you can continuously extend these test-cases and easily verify that the currently active rulesets comply with them.
 
@@ -65,36 +72,40 @@ Please take a took `at the roadmap <https://github.com/O-X-L/firewall-testing-fr
 
 1. **Provide the firewall configuration**:
 
-  * manually pull the current config from the existing firewalls
+   * manually pull the current config from the existing firewalls
 
-  * or utilize existing :code:`pull-plugins` to do so (p.e. via API)
+   * or utilize existing :code:`pull-plugins` to do so (p.e. via API)
 
 2. **Vendor-specific plugins**:
 
-  The vendor-specific configuration gets parsed by :code:`translation-plugins` which output a standardized firewall config-schema.
+   vendor-specific configuration gets parsed by :code:`translation-plugins` which output a standardized firewall config-schema.
 
 3. **Run**:
 
-  * Use the **one-shot CLI** (:code:`command: ftf-cli`)
+   * Use the **one-shot CLI** (:code:`command: ftf-cli`)
 
-  * Enter an interactive shell (:code:`command: ftf-shell`)
+   * Enter an interactive shell (:code:`command: ftf-shell`)
 
-    .. warning::
+     .. warning::
 
-        Still under development.
+         Still under development.
 
-  * Run **automated tests** (:code:`command: ftf-ci`) by providing a test-traffic configuration
+   * Run **automated tests** (:code:`command: ftf-ci`) by providing a test-traffic configuration
 
-    .. warning::
+     .. warning::
 
-        Still under development.
+         Still under development.
 
 
 5. **The Simulator**
 
-  * parses the provided config
-  * generates the network-topology
-  * finds where the packet originates from
-  * finds the route the packet should take
-  * tests the traffic against the rulesets of firewalls that are hops of that route
+   * parses the provided config
+
+   * generates the network-topology
+
+   * finds where the packet originates from
+
+   * finds the route the packet should take
+
+   * tests the traffic against the rulesets of firewalls that are hops of that route
 
diff --git a/docs/source/usage/4_config.rst b/docs/source/usage/4_config.rst
@@ -7,3 +7,21 @@
 ==========
 
 .. include:: ../_include/warn_wip.rst
+
+Multiple Firewalls
+##################
+
+We plan on supporting the simulation of packets across whole network topologies with multiple firewall-hops.
+
+This is currently not yet implemented.
+
+----
+
+CI Mode
+#######
+
+With the CI-Mode you will be able to supply a configuration listing test-packets and the expected outcome to **automate the process of validating** the ruleset.
+
+This can be great for ensuring compliance when changes to the firewalls are done by teams of engineers.
+
+The CI Run-Mode is not yet supported.
