From ddc211cc8eab0b4d0a67d23606c5a29cf5a4bd78 Mon Sep 17 00:00:00 2001
From: Ad Schellevis <ad@opnsense.org>
Date: Wed, 2 Apr 2025 18:26:37 +0200
Subject: [PATCH] Firewall: Aliases - add URL Table in JSON format type, closes
 https://github.com/opnsense/docs/issues/666

---
 source/manual/aliases.rst | 41 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/source/manual/aliases.rst b/source/manual/aliases.rst
index a1dbb345..bb2e8311 100644
--- a/source/manual/aliases.rst
+++ b/source/manual/aliases.rst
@@ -56,6 +56,10 @@ OPNsense offers the following alias types:
 | URL Tables (IPs) | A table of IP addresses that are fetched on regular  |
 |                  | intervals.                                           |
 +------------------+------------------------------------------------------+
+| URL Table in     | A table of IP addresses that are fetched on regular  |
+| JSON format      | intervals.                                           |
+| (IPs)            | (using a json structure)                             |
++------------------+------------------------------------------------------+
 | GeoIP            | Select countries or whole regions                    |
 +------------------+------------------------------------------------------+
 | Network group    | Combine different network type aliases into one      |
@@ -168,8 +172,7 @@ intervals from the :code:`arp` and :code:`ndp` tables.
 URL Tables
 ..................
 URL tables can be used to fetch a list of IP addresses from a remote server.
-There are several IP lists available for free, most notably are the "Don't Route
-Or Peer" lists from Spamhaus.
+You can specify a :code:`Refresh frequency`` to determine how often this information should be updated.
 
 .. Note::
 
@@ -177,6 +180,40 @@ Or Peer" lists from Spamhaus.
     , colon (:code:`,`), semicolon (:code:`;`), pipe (:code:`|`) or hash (:code:`#`) will be ignored.
 
 
+....................................
+URL Table in JSON format (IPs)
+....................................
+
+URL tables can be used to fetch a list of IP addresses from a remote server and parse their contents when in
+`JSON <https://en.wikipedia.org/wiki/JSON>`__ format, similar to our standard (text based) url table.
+
+
+You can use a :code:`Path expression` to select data from the container, in some cases, when content is "flat" you just need a
+single path reference. For example the spamhause `drop <https://www.spamhaus.org/drop/drop_v4.json>`__ list contains a json
+file per row with a field :code:`cidr`.
+
+More advanced scenarios are also possible as our parser supports `jq <https://jqlang.org/>`__,
+some (simple) examples can be found below in the table below.
+
+
+======================================================================================================== ======================================================================================== ==============================================================
+Content                                                                                                  Path Expression                                                                          Topic
+======================================================================================================== ======================================================================================== ==============================================================
+https://ip-ranges.amazonaws.com/ip-ranges.json                                                           .prefixes[] | select(.region=="us-east-1") | select(.service=="EC2") | .ip_prefix        All ip addresses belonging to service EC2 in region us-east-1
+https://api.github.com/meta                                                                              .web + .api + .git | .[]                                                                 All of GitHubs web, api and git addresses
+https://endpoints.office.com/endpoints/worldwide?clientrequestid=b10c5ed1-bad1-445f-b386-b919946339a7    .[] | select(.serviceArea=="Exchange") | select(".ips")| .ips | .[]?                     Exchange networks from Microsoft
+======================================================================================================== ======================================================================================== ==============================================================
+
+
+
+.. Tip::
+
+    Use `https://play.jqlang.org/ <https://play.jqlang.org/>`__ to fiddle with the jq language before pasting content and
+    path expression in an alias.
+
+
+
+
 ..................
 GeoIP
 ..................