Deciso: Extended Blocklists: add documentation

source/third_party_plugins.rst

@@ -24,6 +24,7 @@ Deciso
    vendor/deciso/opncentral
    vendor/deciso/opnproxy
    vendor/deciso/opnwaf
+   vendor/deciso/extended_dnsbl
 
 --------------------
 Sunnyvalley

source/vendor/deciso/extended_dnsbl.rst

@@ -0,0 +1,95 @@
+===========================
+Deciso: Extended Blocklists
+===========================
+
+As part of the OPNsense Business Edition, Deciso offers the extended blocklists module as
+part of the standard Business Edition installation. With this module you are able
+to configure DNS blocking policies in a more fine-grained manner by specifying networks on which the blocklists
+should apply.
+
+The extended blocklists can be found under :menuselection:`Services->Unbound DNS->Extended Blocklists`.
+
+Blocklists
+----------------------------
+
+Blocklists are configured in the same manner as with regular blocklists, except they are listed
+in a grid, where multiple blocklists and multiple networks may be defined per grid entry to ease administration
+for a large amount of networks. An optional description may be provided for your own reference.
+
+Source networks are provided as IP addresses in CIDR notation, or singular IP addresses. The validation
+for this field is strict, meaning that setting host bits in a CIDR notation is not allowed.
+
+.. Note::
+
+    If you'd like to use the extended blocklists module, keep in mind that the regular blocklists, if configured,
+    are still active. They define a policy for all networks, and are given preference above the extended blocklists.
+    Therefore it's possible that a conflict arises between blocklists for a specific network and regular blocklists.
+    Please verify that the relevant blocklists are not configured in :menuselection:`Services->Unbound DNS->Blocklist`.
+
+    If you're not sure if a policy would overlap in this manner, please use the tester as described below.
+
+Custom
+----------------------------
+
+In the Custom tab you are able to configure custom domains to block, also per source network. The domains can either
+be exact matches, or entered as a wildcard in a separate field. Wildcard entries will block every subdomain of
+the configured domain name. It's not possible to block a first-level domain such as 'com'.
+
+To prevent cluttering in the grid, the relevant domains and wildcards are not shown in the grid. Therefore
+it's mandatory to add a description for your own reference so you can easily locate a custom policy. You can view
+the blocked domains/wildcards by clicking "edit" on the grid entry.
+
+
+Tester
+----------------------------
+
+If you'd like to verify whether a specified domain is correctly being blocked, or if you want to know
+if a domain is part of a specific list, you can use the tester to see the policy that's applied to a DNS request.
+Here you're able to enter a domain, as well as a source IP address to simulate a request from a specific address.
+Note that no actual DNS request is sent if a domain were to pass, it's kept isolated as part of the blocklisting mechanism.
+
+It's also possible to verify whether a domain overlaps with another policy. For example, if you configured the facebook blocklist,
+the output would look something like this:
+
+.. code-block:: json
+
+    {
+        "status": "OK",
+        "action": "Block",
+        "policy": {
+            "bl": "ext_blf0",
+            "wildcard": false,
+            "source_net": [
+                "192.168.2.0/24",
+                "192.168.1.0/24",
+                "10.0.0.0/8"
+            ]
+        }
+    }
+
+However, if you also enabled the facebook blocklist in the regular blocklist section, you would get:
+
+.. code-block:: json
+
+    {
+        "status": "OK",
+        "action": "Block",
+        "policy": {
+            "bl": "blf0",
+            "wildcard": false,
+            "collisions": [
+                {
+                    "bl": "ext_blf0",
+                    "wildcard": false,
+                    "source_net": [
+                        "192.168.2.0/24",
+                        "192.168.1.0/24",
+                        "10.0.0.0/8"
+                    ]
+                }
+            ],
+            "source_net": []
+        }
+    }
+
+which would tell you that a regular list is conflicting with an extended blocklist policy.