firewalls 0.1.0__py3-none-any.whl

example/EXAMPLE.md

@@ -0,0 +1,55 @@
+# Firewall Configuration: [MACHINE_NAME]
+
+## 📋 Machine Overview
+- **Hostname / Identifier**: `[MACHINE_NAME]` (e.g., `web-server`, `dev-laptop`)
+- **Role**: [Workstation / Web Server / NAS / Local Router]
+- **Network Interface**: `[INTERFACE]` (e.g., `eth0`, `eno1`, `wlan0`)
+- **Operating System**: Gentoo Linux
+- **Firewall Backend**: `nftables`
+- **Default Zone**: `public` (bound to `[INTERFACE]`, target `DROP`)
+- **Egress Policy**: `egress-policy` (target `DROP`, `HOST` -> `ANY`)
+- **Security Model**: **Dual Default Deny (Bidirectional Zero Trust)**.
+  - **Ingress**: No open ports by default unless explicitly permitted. Unsolicited incoming packets are discarded (`DROP`).
+  - **Egress**: Only explicitly authorized outgoing connections are allowed (strict DNS, NTP, HTTP/HTTPS, etc.). Any other outbound traffic is blocked and dropped (`DROP`).
+
+---
+
+## 🛡️ Active Rules and Functional Behavior
+
+### 1. Outgoing Traffic (*Egress Filtering* - `policies/egress-policy.xml`)
+- **Policy**: **DEFAULT DENY (Target `DROP`)**.
+- **Logging**: Dropped connections logged to `/var/log/firewalld/denied.log`.
+
+| Service / Port | Protocol | Status | Functional Justification |
+| :--- | :--- | :--- | :--- |
+| `http` | TCP (80) | **Allowed** | Standard web browsing and package repository downloads. |
+| `https` | TCP (443) / UDP (443) | **Allowed** | Secure web browsing and HTTP/3 (QUIC). |
+| `dns` (Restricted) | UDP / TCP (53) | **Allowed (IPSet)** | DNS queries restricted to the `trusted-dns` IPSet to prevent DNS tunneling and data exfiltration. |
+| `ntp` | UDP (123) | **Allowed** | System time synchronization. |
+| `dhcp` | UDP (67, 68) | **Allowed** | Local network IPv4 DHCP lease renewal (if applicable). |
+| `rsync` | TCP (873) | **Optional** | Gentoo Portage tree synchronization (`emerge --sync`). |
+| **Anti-Spoofing** | `127.0.0.0/8` outbound | **DENIED (DROP)** | Immediate drop for packets with spoofed loopback source addresses. |
+| **Any other outbound** | All | **DENIED (DROP)** | Strict drop for uncatalogued outbound traffic. |
+
+### 2. Incoming Traffic (*Ingress Filtering* - `zones/public.xml`)
+- **Zone**: `public` (Target: `DROP`, Interface: `[INTERFACE]`)
+- **Policy**: **DEFAULT DENY (Target `DROP`)**.
+
+| Service / Port | Protocol | Status | Functional Justification |
+| :--- | :--- | :--- | :--- |
+| `ssh` | TCP (22) | **Configurable** | Disabled by default on workstations; restrict to administration IPs on servers. |
+| **Any other inbound** | All | **DENIED (DROP)** | Absolute drop of all unsolicited incoming traffic. |
+
+---
+
+## 🔒 Security Mechanisms and System Hardening
+
+1. **D-Bus Lockdown (`Lockdown=yes`)**: Protects `firewalld` so non-privileged processes cannot alter rules via D-Bus.
+2. **Strict DNS Filtering (`trusted-dns`)**: Prevents malware from querying arbitrary rogue DNS resolvers.
+3. **Kernel Hardening (`sysctl.d/99-firewall-hardening.conf`)**:
+   - `rp_filter = 1` (Strict IPv4 reverse path filtering / anti-spoofing).
+   - `accept_redirects = 0` (Prevention of ICMP redirect attacks).
+   - `log_martians = 1` (Kernel logging of martian / impossible source addresses).
+4. **Dedicated Logging (`syslog-ng` + `logrotate`)**:
+   - Denied events routed to `/var/log/firewalld/denied.log` with rate limiting (`throttle(30)`).
+   - Keeps `/var/log/messages` and `dmesg` clean and noise-free.

example/etc/firewalld/firewalld.conf

@@ -0,0 +1,33 @@
+# Default configuration for firewalld on Gentoo Linux
+# Documentation: man firewalld.conf
+
+# Default zone
+DefaultZone=public
+
+# Clean up on exit or stop
+CleanupOnExit=yes
+
+# Lockdown (limits D-Bus interface changes to users/commands in lockdown-whitelist.xml)
+Lockdown=yes
+
+# Reverse Path Filter check on IPv6
+IPv6_rpfilter=yes
+
+# Rule individual calls or combined restore
+IndividualCalls=no
+
+# Log denied packets. Options: 'all', 'unicast', 'broadcast', 'multicast', 'off'.
+# 'off' by default to keep dmesg clean; CLI monitors enable it on demand.
+LogDenied=off
+
+# Automatic helper assignment
+AutomaticHelpers=system
+
+# Firewall backend implementation (nftables recommended)
+FirewallBackend=nftables
+
+# Flush all runtime rules on reload
+FlushAllOnReload=yes
+
+# Filter IPv6-in-IPv4 packets as per RFC 3964
+RFC3964_IPv4=yes

example/etc/firewalld/helpers/.gitkeep

@@ -0,0 +1 @@
+# Placeholder to maintain directory structure

example/etc/firewalld/icmptypes/.gitkeep

@@ -0,0 +1 @@
+# Placeholder to maintain directory structure

example/etc/firewalld/ipsets/trusted-dns.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<ipset type="hash:ip">
+  <short>trusted-dns</short>
+  <description>IPSet of trusted secure DNS resolvers (Cloudflare, Quad9, Google DNS, and local router)</description>
+  <!-- Example local gateway or DNS resolver -->
+  <entry>192.168.1.1</entry>
+  <!-- Cloudflare DNS -->
+  <entry>1.1.1.1</entry>
+  <entry>1.0.0.1</entry>
+  <!-- Quad9 DNS -->
+  <entry>9.9.9.9</entry>
+  <entry>149.112.112.112</entry>
+  <!-- Google DNS -->
+  <entry>8.8.8.8</entry>
+  <entry>8.8.4.4</entry>
+</ipset>

example/etc/firewalld/lockdown-whitelist.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<whitelist>
+  <short>Lockdown Whitelist Template</short>
+  <description>Restricts D-Bus firewall manipulation strictly to root (UID 0) and authorized commands.</description>
+  <user id="0"/>
+  <command name="/usr/bin/python*"/>
+  <command name="/usr/bin/firewall-cmd"/>
+</whitelist>

example/etc/firewalld/policies/egress-policy.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="utf-8"?>
+<policy target="DROP">
+  <short>Egress-Policy-Template</short>
+  <description>Strict egress control: default drop (target DROP). Only explicitly authorized outgoing connections are permitted.</description>
+  <ingress-zone name="HOST"/>
+  <egress-zone name="ANY"/>
+
+  <!-- Anti-Spoofing: Immediate drop of outgoing packets with spoofed loopback addresses -->
+  <rule family="ipv4">
+    <source address="127.0.0.0/8"/>
+    <drop/>
+  </rule>
+
+  <!-- DNS restricted strictly to trusted resolvers (trusted-dns IPSet) -->
+  <rule family="ipv4">
+    <destination ipset="trusted-dns"/>
+    <service name="dns"/>
+    <accept/>
+  </rule>
+
+  <!-- Standard and secure web browsing -->
+  <service name="http"/>
+  <service name="https"/>
+  <!-- HTTP/3 / QUIC -->
+  <port port="443" protocol="udp"/>
+
+  <!-- Time synchronization -->
+  <service name="ntp"/>
+
+  <!-- DHCP client for local network IP renewal -->
+  <service name="dhcp"/>
+
+  <!-- Uncomment if machine synchronizes Gentoo Portage packages via rsync -->
+  <!-- <service name="rsync"/> -->
+
+  <!-- Example rich rule for a specific destination -->
+  <!--
+  <rule family="ipv4">
+    <destination address="192.168.1.50"/>
+    <service name="ssh"/>
+    <accept/>
+  </rule>
+  -->
+</policy>

example/etc/firewalld/services/.gitkeep

@@ -0,0 +1 @@
+# Placeholder to maintain directory structure

example/etc/firewalld/services/example-service.xml.example

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Example custom service definition -->
+<service>
+  <short>custom-app</short>
+  <description>Example custom application service</description>
+  <port protocol="tcp" port="8080"/>
+</service>

example/etc/firewalld/zones/public.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<zone target="DROP">
+  <short>Public</short>
+  <description>Public zone with strict default-drop policy (target DROP). Unsolicited incoming packets are dropped unless explicitly authorized.</description>
+  <!-- Replace 'eth0' with the machine's actual network interface (e.g., eno1, enp3s0, wlan0) -->
+  <interface name="eth0"/>
+  <!-- Example: Enable SSH only if necessary (or restrict with a rich rule by source IP) -->
+  <!-- <service name="ssh"/> -->
+</zone>

example/etc/logrotate.d/firewalld

@@ -0,0 +1,19 @@
+/var/log/firewalld/*.log {
+    weekly
+    missingok
+    rotate 12
+    compress
+    delaycompress
+    notifempty
+    create 0640 root root
+    sharedscripts
+    postrotate
+        if [ -f /run/syslog-ng.pid ]; then
+            kill -HUP $(cat /run/syslog-ng.pid) 2>/dev/null || true
+        elif command -v rc-service >/dev/null 2>&1; then
+            rc-service syslog-ng reload 2>/dev/null || true
+        elif command -v systemctl >/dev/null 2>&1; then
+            systemctl reload syslog-ng 2>/dev/null || true
+        fi
+    endscript
+}

example/etc/sysctl.d/99-firewall-hardening.conf

@@ -0,0 +1,26 @@
+# Network Hardening, Anti-Spoofing, and Kernel Protections for Gentoo Linux
+# Location: /etc/sysctl.d/99-firewall-hardening.conf
+
+# 1. Enable strict Reverse Path Filtering (IPv4 Anti-Spoofing)
+net.ipv4.conf.all.rp_filter = 1
+net.ipv4.conf.default.rp_filter = 1
+
+# 2. Disable ICMP redirect acceptance and transmission (prevents MITM attacks)
+net.ipv4.conf.all.accept_redirects = 0
+net.ipv4.conf.default.accept_redirects = 0
+net.ipv4.conf.all.secure_redirects = 0
+net.ipv4.conf.default.secure_redirects = 0
+net.ipv4.conf.all.send_redirects = 0
+net.ipv4.conf.default.send_redirects = 0
+
+# 3. Disable IP source routing acceptance (prevents malicious routing)
+net.ipv4.conf.all.accept_source_route = 0
+net.ipv4.conf.default.accept_source_route = 0
+
+# 4. Log martian packets (impossible or unroutable source addresses)
+net.ipv4.conf.all.log_martians = 1
+net.ipv4.conf.default.log_martians = 1
+
+# 5. Ignore ICMP echo broadcast and bogus error responses
+net.ipv4.icmp_echo_ignore_broadcasts = 1
+net.ipv4.icmp_ignore_bogus_error_responses = 1

example/etc/syslog-ng/conf.d/firewalld.conf

@@ -0,0 +1,29 @@
+# syslog-ng configuration for firewalld on Gentoo Linux
+# /etc/syslog-ng/conf.d/firewalld.conf
+
+# 1. Daemon service logs for firewalld
+filter f_firewalld { program("firewalld"); };
+destination d_firewalld { file("/var/log/firewalld/firewalld.log"); };
+log { source(src); filter(f_firewalld); destination(d_firewalld); flags(final); };
+
+# 2. Denied and dropped packet logs (LogDenied=all or unicast)
+filter f_firewalld_all_denied {
+    match("_REJECT|_DROP|_DENIED|FINAL_REJECT|FINAL_DROP" value("MESSAGE") flags(ignore-case));
+};
+
+# Noise exclusions to prevent log flooding (adjust according to your network environment):
+filter f_firewalld_denied {
+    filter(f_firewalld_all_denied)
+    # Example: discard local network mDNS noise (UDP port 5353)
+    and not match("DPT=5353" value("MESSAGE"))
+    # Example: discard ICMPv6 router advertisement noise
+    and not match("PROTO=ICMPv6" value("MESSAGE") flags(ignore-case));
+};
+
+# Rate-limiting with throttle(30) to prevent disk exhaustion from DoS or log flooding attacks
+destination d_firewalld_denied { file("/var/log/firewalld/denied.log" throttle(30)); };
+log { source(src); filter(f_firewalld_denied); destination(d_firewalld_denied); flags(final); };
+
+# 3. Discard any remaining firewall drop logs (the excluded noise above)
+# so they do not leak into /var/log/messages or subsequent catch-all destinations
+log { source(src); filter(f_firewalld_all_denied); flags(final); };

example/post_deploy.sh.example

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Example post-deployment script
+# Automatically executed upon completion of 'poetry run firewalls_deploy <machine>'
+# (Rename to post_deploy.sh to activate on the corresponding machine directory)
+
+set -euo pipefail
+
+# Example: Dynamically resolve a domain and add its IP to a firewalld IPSet
+# DOMAIN="example.ddns.net"
+# IPSET_NAME="trusted-hosts"
+#
+# echo "Resolving IP for '$DOMAIN'..."
+# IP_ADDR=$(getent hosts "$DOMAIN" | awk '{print $1}')
+# if [ -n "$IP_ADDR" ]; then
+#     echo "Adding IP $IP_ADDR to IPSet '$IPSET_NAME'..."
+#     firewall-cmd --quiet --ipset="$IPSET_NAME" --add-entry="$IP_ADDR" 2>/dev/null || true
+# fi
+
+echo "Post-deploy completed for example machine."

firewalls/__init__.py

@@ -0,0 +1,25 @@
+"""Firewalls management package."""
+
+import datetime
+import gettext
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+__version__ = "0.1.0"
+__version_datetime__ = datetime.datetime(2026, 10, 26, 13, 2, tzinfo=ZoneInfo("Europe/Madrid"))
+__version_date__ = __version_datetime__.date()
+
+LOCALE_DIR = Path(__file__).resolve().parent / "locale"
+try:
+    _translation = gettext.translation("firewalls", localedir=LOCALE_DIR, fallback=True)
+    _ = _translation.gettext
+except Exception:
+    _ = lambda s: s
+
+__all__ = [
+    "__version__",
+    "__version_datetime__",
+    "__version_date__",
+    "_",
+    "LOCALE_DIR",
+]