feat(ips): add snort3 chapter (#137)

index.rst

@@ -99,6 +99,7 @@ NethSecurity administrator manual
    :maxdepth: 2
    :caption: Advanced (CLI)
 
+   ips
    ddns
    smtp
    snmp

ips.rst

@@ -0,0 +1,174 @@
+====================================
+Intrustion Prevention System (Snort)
+====================================
+
+Snort 3 is an open-source network Intrusion Prevention System that is capable of performing real-time traffic analysis and packet logging on IP networks.
+It can perform protocol analysis, content searching/matching, and can be used to detect a variety of attacks and probes, such as buffer overflows,
+stealth port scans, CGI attacks, SMB probes, OS fingerprinting attempts, and much more.
+
+Snort uses a list of rules that help define malicious traffic. These rules are used to detect and block attacks.
+
+Rules are grouped into policies, each policy is a set of rules that are optimized for a specific use case. The policies are:
+
+- **connectivity**: prioritizes performance over security, minimizing false positives and ensuring high device performance while detecting common threats.
+- **balanced**: recommended for initial deployments, balancing security and performance.
+  and relatively high performance rate with evaluation and testing tools.
+- **security**: for high-security environments with lower bandwidth and higher false positive tolerance.
+  It provides the maximum protection while minimizing the risk of bringing the network down.
+- **max-detect**: this policy is for testing environments, not optimized for performance, and not suitable for production.
+
+Enable and start the IPS
+========================
+
+Before configuring Snort 3 you need to select a policy, then download the rules.
+The module supports the following rulesets:
+
+- Snort `Community Rules <https://www.snort.org/downloads/#rule-downloads>`_
+- Snort `Subscription Rules <https://www.snort.org/products#rule_subscriptions>`_ using the :ref:`Oinkcode <oinkcode-section>`
+
+Rules are automatically updated once a day, during the night.
+They are not part of the backup to avoid large backups and generating a new remote backup every time rules are updated.
+
+Enable Snort using `security` rule policy: ::
+
+  echo '{"enabled": true, "set_home_net": true, "include_vpn": false, "ns_policy": "security", "ns_disabled_rules": []}' | /usr/libexec/rpcd/ns.snort call setup
+  ns-snort-rules --download
+  uci commit snort
+  /etc/init.d/snort restart
+
+When enabled, the IPS will analyze all traffic that goes through the firewall, specifically the traffic that goes through the ``forward`` chain.
+
+In this configuration, the system will automatically identify the home network and use it as the network to protect.
+VPN are considered as part of the external network.
+If the VPN should be considered as part of the home network, set `include_vpn` to `true`.
+
+You can change the policy to `balanced` or `connectivity` by changing the `ns_policy` option.
+
+To change the policy to `balanced` and download the rules: ::
+
+  echo '{"enabled": true, "set_home_net": true, "include_vpn": false, "ns_policy": "balanced", "ns_disabled_rules": []}' | /usr/libexec/rpcd/ns.snort call setup
+  uci commit snort
+  ns-snort-rules --restart
+
+Enable extra alert rules
+------------------------
+
+Rules that are not part of any policy are excluded by default.
+It is possible to include them as alert rules by setting the `ns_alert_excluded` option to `1`: ::
+
+  uci set snort.snort.ns_alert_excluded=1
+  uci commit snort
+  /etc/init.d/snort restart
+
+Traffic matching these rules will generate alerts but will not be blocked.
+
+.. _oinkcode-section:
+
+Set the Oinkcode
+----------------
+
+If you have a Snort subscription, you can use the Oinkcode to download the rules.
+The Oinkcode is a unique code that identifies your subscription and allows you to download the rules.
+To set the Oinkcode use the `oinkcode` option: ::
+
+  uci set snort.snort.oinkcode=your_oinkcode
+  uci commit snort
+  ns-snort-rules --download
+  /etc/init.d/snort restart
+
+Source and destination bypass
+=============================
+
+All traffic that goes through the firewall is analyzed by the IPS.
+To bypass the IPS for specific source or destination IP addresses, the system supports bypass rules both for IPv4 and IPv6 addresses.
+
+The following options are supported inside ``snort.nfq`` section:
+
+- ``bypass_dst_v4``: bypass IPS for destination IPv4 addresses
+- ``bypass_src_v4``: bypass IPS for source IPv4 addresses
+- ``bypass_dst_v6``: bypass IPS for destination IPv6 addresses
+- ``bypass_src_v6``: bypass IPS for source IPv6 addresses
+
+Example, the traffic generated by 192.168.100.23 and 192.168.100.28 IPs will not be analyzed by Snort: ::
+
+  uci add_list snort.nfq.bypass_src_v4=192.168.100.23
+  uci add_list snort.nfq.bypass_src_v4=192.168.100.28
+  uci commit snort
+  /etc/init.d/snort restart
+
+Disable rules
+=============
+
+In some environments, rules can be too restrictive or generate too many false positives.
+To avoid this, it is possible to disable some rules.
+A disabled rule is a rule that is not include in the Snort ruleset.
+
+To disable some rules use the ``ns_disabled_rules`` option inside UCI, under the ``snort.snort`` section.
+The option is a list of entries in this format: ``<gid>,<sid>,<description>``.
+
+- ``gid``: the rule GID, it is a number and usually is always `1`
+- ``sid``: the rule SID, it is a number
+- ``description``: a description of the disabled rule, it is optional and can be omitted; the following characters are not allowed: comma, space and newlines
+
+Example, disable rules with SID 24225 and 24227: ::
+    
+  uci add_list snort.snort.ns_disabled_rules=1,24225,false_positive
+  uci add_list snort.snort.ns_disabled_rules=3,24227
+  uci commit snort
+  /etc/init.d/snort restart
+
+Suppress rules
+==============
+
+A suppression rule is a rule that is ignored by Snort for a specific IP address or CIDR.
+The rule is still evaluated for all other IP addresses.
+
+To add a suppress rule use the ``ns_suppress`` option inside UCI ``snort.snort`` section.
+Each suppress rule is a comma separated list of values: ``gid,sid,direction,ip,description``:
+
+- ``gid``: the rule GID, it is a number and usually is always ``1``
+- ``sid``: the rule SID, it is a number
+- ``direction``: the direction of the rule, it can be `by_src` or `by_dst`
+- ``ip``: the IPv4 address or CIDR to suppress
+- ``description``: a description of the suppress rule, it is optional and can be omitted; the following characters are not allowed: comma, space and newlines
+
+Example, suppress rule 1234 for source IP 1.2.3.4 and destination IP 8.8.8.8: ::
+
+  uci add_list snort.snort.ns_suppress='1,1234,by_src,1.2.3.4,very_bad'
+  uci add_list snort.snort.ns_suppress='1,1234,by_dst,8.8.8.8,noisy_rule'
+  uci commit snort
+  /etc/init.d/snort restart
+
+Alerts and logs
+===============
+
+Snort generates alerts when a rule is matched, not matter if the traffic is blocked or not.
+The alerts are logged in the system log and can be viewed using ``less /var/log/messages``.
+
+An example of an alert is: ::
+
+  Dec  4 12:06:00 fw.example.com snort: [1:1852:11] "SERVER-WEBAPP robots.txt access" [Classification: Access to a potentially vulnerable web application] [Priority: 2] {TCP} 203.0.113.1:24455 -> 192.0.2.1:80
+
+Alerts are also stored in JSON format in the ``/var/log/snort`` directory.
+Snort will create a file for each queue and store the alerts in the file.
+Example of a file name: ``1_alert_json.txt``.
+
+To inspect the file use: ::
+
+  cat /var/log/snort/1_alert_json.txt | jq .
+
+To get a report about what has been blocked or alerted, use: ::
+
+  snort-mgr report
+
+Each alert is generated by a rule, the rule is identified by a GID and SID.
+To see more info about the rule that generated the alert, use this URL: ``https://www.snort.org/rule_docs/<GID>-<SID>``.
+
+Disable and stop the IPS
+========================
+
+To disable Snort: ::
+
+  echo '{"enabled": false}' | /usr/libexec/rpcd/ns.snort call setup
+  uci commit snort
+  /etc/init.d/snort stop