Skip to content

Commit 7663ea4

Browse files
superstessuperstes
committed
extend plugin-docs
1 parent 541be35 commit 7663ea4

File tree

6 files changed

+160
-22
lines changed

6 files changed

+160
-22
lines changed

‎docs/meta/sitemap.xml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@
77
<url><loc>https://ftf.oxl.app/usage/3_run.html</loc></url>
88
<url><loc>https://ftf.oxl.app/usage/4_config.html</loc></url>
99

10+
<url><loc>https://ftf.oxl.app/plugins/firewall_netfilter.html</loc></url>
11+
<url><loc>https://ftf.oxl.app/plugins/firewall_opnsense.html</loc></url>
12+
<url><loc>https://ftf.oxl.app/plugins/os_linux.html</loc></url>
13+
1014
<url><loc>https://ftf.oxl.app/dev/1_intro.html</loc></url>
1115
<url><loc>https://ftf.oxl.app/dev/2_plugins.html</loc></url>
1216
</urlset>

‎docs/source/plugins/firewall_netfilter.rst‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
.. _plugins_fw_netfilter:
2+
3+
.. include:: ../_include/head.rst
4+
5+
====================
6+
Firewall - Netfilter
7+
====================
8+
9+
Config Export
10+
#############
11+
12+
You have to simply run this command:
13+
14+
.. code-block:: bash
15+
16+
sudo nft -j list ruleset > ruleset.json
17+
18+
Optional: To get a more readable JSON-output, you can use the :code:`jq` tool to format it:
19+
20+
.. code-block:: bash
21+
22+
sudo apt install jq # json-query
23+
24+
sudo nft -j list ruleset | jq > ruleset.json
25+
26+
27+
----
28+
29+
Source Code
30+
###########
31+
32+
* **System Config**: `system/system_linux_netfilter.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/system/system_linux_netfilter.py>`_
33+
34+
* **Config Parsing**: `translate/netfilter/ <https://github.com/O-X-L/firewall-testing-framework/tree/latest/src/firewall_test/plugins/translate/netfilter>`_
35+
36+
* **Traffic Matching**: `system/firewall_netfilter.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/system/firewall_netfilter.py>`_
37+
38+
----
39+
40+
Config-Parsing
41+
##############
42+
43+
The current implementation focused on supporting the most widely used rule matches like:
44+
45+
* Layer 3 Protocol (IPv4/IPv6)
46+
* Layer 4 Protocol (tcp/udp/icmp)
47+
* Source- and Destination-IP filters
48+
* Source- and Destination-Port filters
49+
* Source- and Destination-NAT (including masquerade)
50+
* Inbound- and Outbound-Network-Interfaces
51+
* CT-State
52+
53+
The main match-parsing logic can be found here: `translate/netfilter/elements.py NftMatch & NftRule <https://github.com/O-X-L/firewall-testing-framework/tree/latest/src/firewall_test/plugins/translate/netfilter/elements.py>`_
54+
55+
If we were not able to parse any match from the rule-config - the rule will be skipped.
56+
57+
If this happens you will see a warning at runtime! (:code:`Unsupported rule`)
58+
59+
Unsupported Expressions
60+
=======================
61+
62+
Rules only containing unsupported expressions will be skipped for now.
63+
64+
If this happens you will see a warning at runtime! (:code:`Unsupported rule-expression`)
65+
66+
These rule-expressions are unsupported for now:
67+
68+
* :code:`log`
69+
* :code:`comment`
70+
* :code:`limit`
71+
* :code:`set` (*static sets are supported - but dynamic ones like meters are not!*)
72+
* :code:`vmap`
73+
* :code:`counter`
74+
* :code:`xt` (*only SNAT-masquerade is currently supported*)
75+
* :code:`ct helper`
76+
* :code:`&`
77+
* TCP flags

‎docs/source/plugins/firewall_opnsense.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
.. _plugins_fw_opnsense:
2+
3+
.. include:: ../_include/head.rst
4+
5+
===================
6+
Firewall - OPNsense
7+
===================
8+
9+
.. warning::
10+
11+
This plugin is still in early development!
12+
13+
Config Export
14+
#############
15+
16+
1. `Download a Config-Backup <https://docs.opnsense.org/manual/backups.html>`_
17+
18+
2. `Supply the runtime routes manually <https://docs.opnsense.org/manual/routes.html#status>`_ or `query them via API <https://docs.opnsense.org/development/api/core/diagnostics.html#id6>`_
19+
20+
----
21+
22+
Source Code
23+
###########
24+
25+
* **System Config**: `system/system_opnsense.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/system/system_opnsense.py>`_
26+
27+
* **Config Parsing**: `translate/opnsense/ <https://github.com/O-X-L/firewall-testing-framework/tree/latest/src/firewall_test/plugins/translate/opnsense>`_
28+
29+
* **Traffic Matching**: `system/firewall_opnsense.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/system/firewall_opnsense.py>`_
30+

‎docs/source/plugins/system_linux.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
.. _plugins_sys_linux:
2+
3+
.. include:: ../_include/head.rst
4+
5+
==============
6+
System - Linux
7+
==============
8+
9+
Config Export
10+
#############
11+
12+
This plugin only supports `iproute2 <https://wiki.linuxfoundation.org/networking/iproute2>`_!
13+
14+
You have to simply run these commands:
15+
16+
.. code-block:: bash
17+
18+
ip -j address show > interfaces.json
19+
ip -j route show table all > routes.json
20+
ip -j rule show > route-rules.jso
21+
22+
Optional: To get a more readable JSON-output, you can use the :code:`jq` tool to format it:
23+
24+
.. code-block:: bash
25+
26+
sudo apt install jq # json-query
27+
28+
ip -j address show | jq > interfaces.json
29+
ip -j route show table all | jq > routes.json
30+
ip -j rule show | jq > route-rules.jso
31+
32+
----
33+
34+
Source Code
35+
###########
36+
37+
* **System Config**: `system/system_linux_netfilter.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/system/system_linux_netfilter.py>`_
38+
39+
* **Config Parsing**: `translate/linux.py <https://github.com/O-X-L/firewall-testing-framework/tree/latest/src/firewall_test/plugins/translate/linux.py>`_

‎docs/source/usage/2_system_support.rst‎

Lines changed: 9 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -35,37 +35,30 @@ For Firewall-Ruleset parsing.
3535

3636
- Support
3737

38-
- Config-Export Command
39-
40-
- Source Code
38+
- Plugin Docs
4139

4240
* - `Netfilter <https://www.netfilter.org/>`_ on Linux
4341

4442
- `NFTables <https://www.netfilter.org/projects/nftables/index.html>`_ or `IPTables <https://www.netfilter.org/projects/iptables/index.html>`_
4543

4644
- Experimental
4745

48-
- :code:`sudo nft -j list ruleset > ruleset.json`
46+
- :ref:`Plugins - Firewall Netfilter <plugins_fw_netfilter>`
4947

50-
- `system/firewall_netfilter.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/system/firewall_netfilter.py>`_,
51-
`translate/netfilter/ <https://github.com/O-X-L/firewall-testing-framework/tree/latest/src/firewall_test/plugins/translate/netfilter>`_
5248

5349
* - `OPNsense <https://opnsense.org/>`_
5450

5551
- \-
5652

5753
- Development
5854

59-
- `Download a Config-Backup <https://docs.opnsense.org/manual/backups.html>`_, `Querying runtime routes via API <https://docs.opnsense.org/development/api/core/diagnostics.html#id6>`_
55+
- :ref:`Plugins - Firewall OPNsense <plugins_fw_opnsense>`
6056

61-
- `system/firewall_opnsense.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/system/firewall_opnsense.py>`_,
62-
`system/system_opnsense.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/system/system_opnsense.py>`_,
63-
`translate/opnsense/ <https://github.com/O-X-L/firewall-testing-framework/tree/latest/src/firewall_test/plugins/translate/opnsense>`_
6457

6558
----
6659

67-
Operating System Support
68-
########################
60+
Networking System Support
61+
#########################
6962

7063
For Routing- and Network-Interface parsing.
7164

@@ -74,23 +67,18 @@ For Routing- and Network-Interface parsing.
7467
:widths: 10 10 10 45 25
7568
:header-rows: 1
7669

77-
* - OS
70+
* - System
7871

7972
- Description
8073

8174
- Support
8275

83-
- Config-Export Command
84-
85-
- Source Code
76+
- Plugin Docs
8677

8778
* - Linux
8879

89-
- iproute2
80+
- `iproute2 <https://wiki.linuxfoundation.org/networking/iproute2>`_
9081

9182
- Yes
9283

93-
- :code:`ip -j address show > interfaces.json && ip -j route show table all > routes.json && ip -j rule show > route-rules.json`
94-
95-
- `system/system_linux_netfilter.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/system/system_linux_netfilter.py>`_,
96-
`translate/linux.py <https://github.com/O-X-L/firewall-testing-framework/blob/latest/src/firewall_test/plugins/translate/linux.py>`_
84+
- :ref:`Plugins - System Linux <plugins_sys_linux>`

‎src/firewall_test/plugins/translate/netfilter/elements.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -377,7 +377,7 @@ def __init__(self, table: NftTable, chain: NftChain, raw: dict, seq: int, sets:
377377
e in expression for e in IGNORE_RULE_EXPRESSIONS
378378
)
379379
if not ignored:
380-
log_warn('Firewall Plugin', f'Got unsupported rule-expression: "{expression}"')
380+
log_warn('Firewall Plugin', f'Unsupported rule-expression: "{expression}"')
381381

382382
for match in self.matches:
383383
if match.value_is_set:

0 commit comments

Comments
 (0)