Skip to content

Commit

Permalink
feat: add threat shield dns documentation (#148)
Browse files Browse the repository at this point in the history 
Co-authored-by: Filippo Carletti <[email protected]>
  • Loading branch information
@andre8244 @filippocarletti
andre8244 and filippocarletti authored Feb 11, 2025
1 parent a9df940 commit bee3c9d
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 67 deletions.
120 changes: 65 additions & 55 deletions threat_shield_dns.rst
View file
Original file line number Diff line number Diff line change
@@ -1,102 +1,112 @@
.. _threat_shield_dns-section:

=================
Threat Shield DNS
Threat shield DNS
=================

Threat Shield DNS uses Adblock which blocks any request to a domain considered malicious.
The service can load community-maintained blocklist or use Enterprise feeds provided by Nethesis and Yoroi.
Threat shield DNS uses Adblock which blocks any request to domains considered malicious.
The service can load community-maintained blocklists or use Enterprise feeds provided by `Nethesis <https://www.nethesis.it>`_ and `Yoroy <https://yoroi.company>`_
a leading company focused on CyberSecurity and member of `Cyber Threat Alliance <https://www.cyberthreatalliance.org>`_.

While Threat Shield DNS is primarily configured from the command line, this chapter will guide you through its setup and usage.
Please note that to access the Nethesis and Yoroi blocklists, the unit must have a valid extra entitlement for this service.

Enable Threat Shield DNS
=========================
.. _configuration-section:

To enable Threat Shield DNS, use the following commands: ::
Configuration
=============

echo '{"enabled": true, "zones": ["lan"]}' | /usr/libexec/rpcd/ns.threatshield call dns-edit-settings
uci commit adblock && service adblock restart
.. note:: Please use Threat shield DNS only if you are not already using the FlashStart service. Both services operate at the DNS level and cannot be used together. The UI prevents enabling them simultaneously to avoid conflicts.

This command enables Threat Shield DNS and applies it to the "lan" zone.
After enabling, all DNS requests from the configured zones are redirected to the firewall itself (ports 53 and 853 TCP/UDP).
Note that this port forwarding is not visible from the port forward page.
The service is disabled by default, to enable it navigate to the ``Threat shield DNS`` page under the ``Security`` section.
Access the ``Settings`` tab and activate the ``Status`` switch.

If you want to filter other zones, replace "lan" with the desired zone name.
When the service is enabled, the ``Blocklist sources`` tab will display all available blocklists.
You can enable or disable each blocklist by using the switch on the right side of the list.
Enabled blocklists will be automatically updated at regular intervals.

.. note:: Please use Threat Shield DNS only if you are not already using the FlashStart service because if used together, they may conflict.
To specify on which zones the service should be active, select them in the ``Force DNS redirection on these zones`` combobox.

Manage blocklists
=================

By default, a machine has access to all community free categories, if the machine has a subscription and a valid entitlement for Enterprise lists,
it will have automatically access to enterprise categories.
``Redirected ports`` allows you to specify which ports should be redirected to Threat shield DNS service.

1. List available blocklists: ::
.. _community_blocklists-section:

/usr/libexec/rpcd/ns.threatshield call dns-list-blocklist | jq
Community blocklists
--------------------

2. Enable a specific blocklist (e.g., malware_lvl2): ::
Community blocklists are sourced from community contributors and block various domains related to: ads, malware, spam,
tracker, explicit sexual content, piracy and so on.
NethSecurity makes them available as they are.
The type of usage license may vary depending on the provider, so if the use is not personal, you may need to inquire with the provider.

echo '{"blocklist": "malware_lvl2", "enabled": true}' | /usr/libexec/rpcd/ns.threatshield call dns-edit-blocklist | jq
.. rubric:: Community lists maintenance

3. Apply changes: ::
Each blocklist is maintained by its specific provider. NethSecurity already includes the URLs for downloading the feeds,
which are valid at the time of the release. However, because these URLs are hard-coded, if the provider changes them, some blocklists may no longer
be downloadable.

uci commit adblock && service adblock restart
.. _enterprise_blocklists-section:

4. Check the status: ::
Enterprise blocklists
---------------------

/etc/init.d/adblock status
.. admonition:: Subscription required

Bypass Threat Shield DNS
========================
This feature is available only if the unit has a valid :ref:`Community or Enterprise subscription <subscription-section>`.

Some hosts may need to bypass Threat Shield DNS filtering.
To bypass filtering for specific hosts, execute: ::
Enterprise blocklists are specifically focused on security and offer several advantages over community-maintained blocklists:

echo '{"address": "192.168.1.22"}' | /usr/libexec/rpcd/ns.threatshield call dns-add-bypass
1. **Quality and accuracy**: Enterprise blocklists, such as the ones provided by Nethesis and Yoroi, are curated and maintained by reputable cybersecurity companies.
These companies have dedicated teams that continuously monitor and update the blocklists to ensure they are accurate and effective in blocking malicious traffic.
This results in a higher level of quality and accuracy compared to community-maintained blocklists, which may not receive the same level of attention and updates.

Replace ``192.168.1.22`` with the IP address of the host you want to bypass.
2. **Timeliness**: Enterprise blocklists are frequently updated to include the latest threats and malicious IP addresses.
Cybersecurity companies like Nethesis and Yoroi actively track emerging threats and promptly add them to their blocklists.
This ensures that your system is protected against the most recent and evolving threats.

Apply changes: ::
3. **Reduced false positives**: False positives occur when legitimate traffic is mistakenly blocked.
Enterprise blocklists are designed to minimize false positives by carefully curating and verifying the listed IP addresses and hostnames.
The companies behind Enterprise blocklists have robust processes in place to ensure that only malicious entities are included in the blocklists.
This reduces the chances of legitimate traffic being blocked, minimizing disruptions to your network or services.

uci commit adblock && service adblock restart
4. **Enterprise support**: Enterprise blocklists often come with additional support and services tailored for enterprise environments.
This includes access to technical support, documentation, and integration assistance.
If any issues or questions arise while using the Enterprise blocklists, you can rely on the support provided by the cybersecurity companies to help you
address them effectively.

.. note::

To preserve the effectiveness of the content filter it is suggested blocking alternative DNS protocols (DoT, DoH)
via :ref:`dpi_filter-section` and by enabling the ``doh_vpn_tor_proxy`` blocklist.
Yoroi and Nethesis blocklists are Enterprise blocklists.
These lists will be listed only if the unit has a valid :ref:`Enterprise or Community subscription <subscription-section>` and a valid entitlement for the Threat Shield service.

.. _block_website-section:
.. _filter_bypass-section:

Block certain websites
======================
Filter bypass
=============

To block specific domains, you can use the Threat Shield service.
Add the domains that you want to block to the blocklist: ::
Some hosts or subnets may need to bypass Threat shield DNS filtering. To configure filter bypass, navigate to the ``Filter bypass`` tab of Threat shield DNS.
Use the :guilabel:`Add bypass` button to add a new address to the list.
The address can be a valid IPv4/IPv6 address with optional CIDR notation.

cat << EOF > /etc/adblock/adblock.blacklist
domain1.com
domain2.com
domain3.net
EOF
.. _local_blocklist-section:

Changes made to the blocklist require a reload of the service: ::
Local blocklist
===============

/etc/init.d/adblock reload
To block specific domains not included in the blocklists, you can navigate to the ``Local blocklist`` tab of Threat shield DNS.
Use the :guilabel:`Add domain` button to add a domain to the list; you can add a description to the domain to help you remember why it was added.

.. warning::

The DNS resolution for the names listed in the blocklist will also affect the firewall itself
The DNS resolution for the names listed in the blocklist will also affect the unit itself

.. _advanced_configuration-section:

Advanced configuration
======================

When Threat Shield DNS is enabled:
When Threat shield DNS is enabled:

- A new category source file is generated based on the machine registration and entitlement.
- A new category source file is generated based on the unit registration and entitlement.
- All DNS queries are redirected to the local machine.
- Adblock is configured to use the new category source file and will be started automatically.

Even if not recommended, it's possible to use Adblock without Threat Shield DNS.
Even if not recommended, it's possible to use Adblock without Threat shield DNS.
For more detailed configuration options, please refer to the `developer manual <https://dev.nethsecurity.org/packages/ns-threat_shield/#ts-dns>`_.
24 changes: 12 additions & 12 deletions threat_shield_ip.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,26 @@ Threat shield IP
================

NethSecurity is equipped with various tools and integrations useful for countering threats coming from the internet.
One of these tools is Threat Shield, which blocks any traffic coming from compromised IP addresses or destined to them as well as any requests addressed to hostnames that could be malicious.
One of these tools is Threat Shield IP, which blocks any traffic coming from compromised IP addresses or destined to them as well as any requests addressed to hostnames that could be malicious.

The service can load community-maintained blocklists or can rely on high-quality blocklists very frequently updated and maintained by `Nethesis <https://www.nethesis.it>`_ and `Yoroy <https://yoroi.company>`_
a leading company focused on CyberSecurity and member of `Cyber Threat Alliance <https://www.cyberthreatalliance.org>`_.
Yoroi blacklists ensure great effectiveness and high confidence, minimizing the possibility of false positives.

Please note that to access the Nethesis and Yoroi blocklist, the machine must have a valid extra entitlement for this service.
Please note that to access the Nethesis and Yoroi blocklists, the machine must have a valid extra entitlement for this service.

Configuration
=============

The service is disabled by default, to enable it navigate to the ``Threat shield`` page under the ``Security`` section.
The service is disabled by default, to enable it navigate to the ``Threat shield IP`` page under the ``Security`` section.
Access the ``Settings`` tab and activate the ``Status`` switch.

When the service is enabled, the ``Blocklist`` tab will display all available blocklists.
When the service is enabled, the ``Blocklist feeds`` tab will display all available blocklists.
You can enable or disable each blocklist by using the switch on the right side of the list.
Enabled blocklist will be automatically updated at regular intervals.
Enabled blocklists will be automatically updated at regular intervals.
NethSecurity 8 allows the use of Community and Enterprise blocklists.

Community Blocklists
Community blocklists
--------------------

Community blocklists are sourced from community contributors and cover various areas: Ads blocking, Malware blocking, Spam blocking,
Expand All @@ -47,26 +47,26 @@ Enterprise blocklists

Enterprise blocklists are specifically focused on security and offer several advantages over community-maintained blocklists:

1. **Quality and Accuracy**: Enterprise blocklists, such as the ones provided by Nethesis and Yoroi, are curated and maintained by reputable cybersecurity companies.
1. **Quality and accuracy**: Enterprise blocklists, such as the ones provided by Nethesis and Yoroi, are curated and maintained by reputable cybersecurity companies.
These companies have dedicated teams that continuously monitor and update the blocklists to ensure they are accurate and effective in blocking malicious traffic.
This results in a higher level of quality and accuracy compared to community-maintained blocklists, which may not receive the same level of attention and updates.

2. **Timeliness**: Enterprise blocklists are frequently updated to include the latest threats and malicious IP addresses.
Cybersecurity companies like Nethesis and Yoroi actively track emerging threats and promptly add them to their blocklists.
This ensures that your system is protected against the most recent and evolving threats.

3. **Reduced False Positives**: False positives occur when legitimate traffic is mistakenly blocked.
3. **Reduced false positives**: False positives occur when legitimate traffic is mistakenly blocked.
Enterprise blocklists are designed to minimize false positives by carefully curating and verifying the listed IP addresses and hostnames.
The companies behind Enterprise blocklists have robust processes in place to ensure that only malicious entities are included in the blocklists.
This reduces the chances of legitimate traffic being blocked, minimizing disruptions to your network or services.

4. **Enterprise Support**: Enterprise blocklists often come with additional support and services tailored for enterprise environments.
4. **Enterprise support**: Enterprise blocklists often come with additional support and services tailored for enterprise environments.
This includes access to technical support, documentation, and integration assistance.
If any issues or questions arise while using the Enterprise blocklists, you can rely on the support provided by the cybersecurity companies to help you
address them effectively.

Yoroi and Nethesis blocklists are Enterprise blocklists.
These lists will be listed only if the machine has a valid :ref:`Enterprise or Community subscription <subscription-section>` and a valid entitlement for the Threat Shield service.
These lists will be listed only if the machine has a valid :ref:`Enterprise or Community subscription <subscription-section>` and a valid entitlement for the Threat Shield IP service.

Logging
-------
Expand All @@ -78,7 +78,7 @@ The logging section allows you to configure which types of blocked packets are l
which processes packets before they enter the routing table.

2. Log packets blocked in input chain: his option, when activated, logs packets blocked in the input chain, which handles packets destined
to the firewall itself. Plese not that this option can generate a large number of logs if the firewall is under heavy traffic.
to the firewall itself. Please note that this option can generate a large number of logs if the firewall is under heavy traffic.

3. Log packets blocked in forward chain: Enabling this logs packets blocked in the forward chain, which processes packets being routed through the firewall.

Expand Down Expand Up @@ -129,7 +129,7 @@ It's also a good practice to include a descriptive comment for each entry to hel
Block brute force attacks
=========================

When Threat Shield is enabled, the system automatically starts checking for brute force attack attempts on firewall services.
When Threat Shield IP is enabled, the system automatically starts checking for brute force attack attempts on firewall services.
By default, the monitored services include SSH access and the login to NethSecurity UI.
The system detects login attempts and automatically blocks IPs that have failed to enter the correct credentials.

Expand Down

0 comments on commit bee3c9d

Please sign in to comment.