firewalls 0.1.0__tar.gz

firewalls-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: firewalls
+Version: 0.1.0
+Summary: Centralized firewalld configuration and deployment manager for Gentoo Linux
+Author: worky
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: colorama (>=0.4.6,<0.5.0)
+Requires-Dist: poethepoet (>=0.49.0,<0.50.0)
+Description-Content-Type: text/markdown
+
+# Firewalls Configuration
+
+Centralized management and deployment of `firewalld` configurations for Gentoo Linux systems, packaged and managed with **Poetry**.
+
+---
+
+## 🗂️ Project Structure
+
+The public repository contains the CLI deployment tool, log streaming monitors, connectivity probes, and a clean template configuration (`example/`). Machine-specific configurations (private workstations, production servers) can be maintained in a separate private repository or external directory:
+
+```text
+firewalls/
+├── pyproject.toml                # Poetry package configuration and dependencies
+├── firewalls/                    # Python package containing CLI tools
+│   ├── __init__.py
+│   ├── cli.py                    # Deployment and service control
+│   ├── log_control.py            # Dynamic runtime LogDenied manager
+│   ├── monitor.py                # Live real-time dashboard
+│   ├── log_ingress.py            # Inbound blocked traffic monitor
+│   ├── log_egress.py             # Outbound blocked traffic monitor
+│   └── probes.py                 # Network connectivity probes
+├── AI_PROMPT.md                  # Master prompt and guide for generating configurations with AI
+├── README.md
+└── example/                      # Clean machine configuration template
+    ├── EXAMPLE.md                # Functional documentation of rules and services
+    ├── post_deploy.sh.example    # Optional post-deployment script template
+    └── etc/
+        ├── firewalld/
+        │   ├── firewalld.conf    # Main firewalld configuration
+        │   ├── lockdown-whitelist.xml
+        │   ├── zones/            # Zone definitions (e.g. public.xml)
+        │   ├── services/         # Custom service definitions
+        │   ├── ipsets/           # IPSet definitions (e.g. trusted-dns.xml)
+        │   ├── icmptypes/        # ICMP type definitions
+        │   ├── helpers/          # Connection helpers
+        │   └── policies/         # Egress and inter-zone policies (egress-policy.xml)
+        ├── syslog-ng/conf.d/     # Log routing into /var/log/firewalld/
+        ├── logrotate.d/          # Log rotation configuration
+        └── sysctl.d/             # Kernel network hardening (rp_filter, anti-spoofing)
+```
+
+---
+
+## 🤖 Generating Machine Configurations with AI
+
+To easily generate a customized firewall configuration using an AI assistant (Claude, Gemini, ChatGPT, Antigravity, etc.), refer to **[AI_PROMPT.md](AI_PROMPT.md)**. It provides a master prompt ready to customize with your machine's role, network interfaces, and allowed services.
+
+---
+
+## 🚀 Usage
+
+All commands are managed through **Poetry**:
+
+### 1. Deploying a Machine Configuration
+
+Machine configurations can reside in any local directory or private git repository:
+
+1. **Direct path** (absolute or relative):
+   ```bash
+   poetry run firewalls_deploy /path/to/my-firewalls/my_machine
+   ```
+
+2. **Using the `--configs-dir` (`-d`) option**:
+   ```bash
+   poetry run firewalls_deploy my_machine --configs-dir /path/to/my-firewalls
+   ```
+
+3. **Using the environment variable** (Recommended):
+   ```bash
+   export FIREWALLS_DIR="$HOME/my-firewalls"
+   poetry run firewalls_deploy my_machine
+   ```
+
+4. **Template or repository machines** (also checks `~/.config/firewalls/machines/`):
+   ```bash
+   poetry run firewalls_deploy example
+   ```
+
+### 2. Stopping the `firewalld` Service
+
+```bash
+poetry run firewalls_deploy stop
+```
+
+### What `firewalls_deploy` Does:
+1. Resolves and validates the machine configuration across search paths (`--configs-dir`, `$FIREWALLS_DIR`, `~/.config/firewalls/machines/`, direct path, or local directory).
+2. Verifies `root` privileges.
+3. Synchronizes `<machine>/etc/` into system `/etc/` preserving permissions, symlinks, and directory structure.
+4. Enforces `root:root` ownership and secure permissions (`0750` directories, `0644` files) strictly on files written under `/etc/firewalld`, without modifying parent directory permissions of `/etc`.
+5. Re-applies kernel network security parameters from `/etc/sysctl.d/` if present.
+6. Configures and restarts/reloads `syslog-ng` to isolate firewall logs into `/var/log/firewalld/`.
+7. Reloads `firewalld` rules via `firewall-cmd --reload` (or starts the service with OpenRC / systemd if stopped).
+8. Automatically executes the optional `post_deploy.sh` script if present in the machine folder.
+
+---
+
+## 📊 Real-Time Monitoring and Log Analysis
+
+You can monitor, tally, or summarize blocked events with the built-in CLI tools:
+
+```bash
+# Monitor blocked incoming connections (Ingress)
+poetry run firewalls_log_ingress
+poetry run firewalls_log_ingress --summary   # Displays ranked summary
+
+# Monitor blocked outgoing connections (Egress)
+poetry run firewalls_log_egress
+poetry run firewalls_log_egress --summary    # Displays ranked summary
+
+# Live interactive dashboard (Ingress + Egress with reverse DNS PTR)
+poetry run firewalls_monitor                            # Default refresh (3s), top 20 rankings, DNS resolution
+poetry run firewalls_monitor -n 2 -p 5                  # Refresh every 2s showing top 5 entries
+poetry run firewalls_monitor --no-resolve               # Show raw IP addresses without reverse DNS
+```
+
+---
+
+## 🧪 Connectivity Probes (`firewalls_probes`)
+
+The `firewalls_probes` command tests connectivity for both **outgoing (egress)** and **incoming (ingress / listen)** traffic to validate that firewall policies work as expected.
+
+### Command Options
+
+| Parameter | Short | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `--host` | `-H` | Target hostname or IP address for outbound probes | `kde.org` |
+| `--port` | `-p` | Port number to probe | `1555` |
+| `--protocol` | `-proto` | Transport protocol (`tcp` or `udp`) | `tcp` |
+| `--timeout` | `-t` | Maximum socket timeout in seconds | `5.0` |
+| `--count` | `-c` | Number of probe iterations | `1` |
+| `--listen` | `-l` | **Listen Mode (Ingress)**: Opens port locally to wait for incoming connections | Disabled (Outbound) |
+| `--bind` | `-b` | Local interface IP address to bind in listen mode | `0.0.0.0` |
+
+---
+
+### Recommended Verification Test Suite
+
+#### 1. Outgoing Permitted Traffic (Egress - Expected Success)
+
+- **Standard Web Traffic (HTTP/HTTPS)**:
+  ```bash
+  poetry run firewalls_probes -H kde.org -p 80 -proto tcp
+  poetry run firewalls_probes -H kde.org -p 443 -proto tcp
+  ```
+- **Gentoo Portage Sync (rsync)**:
+  ```bash
+  poetry run firewalls_probes -H rsync.gentoo.org -p 873 -proto tcp
+  ```
+- **DNS Resolution and Time Sync (NTP)**:
+  ```bash
+  poetry run firewalls_probes -H 1.1.1.1 -p 53 -proto udp
+  poetry run firewalls_probes -H pool.ntp.org -p 123 -proto udp
+  ```
+
+#### 2. Outgoing Blocked Traffic (Zero Trust - Expected Drop)
+
+- **Unauthorized outbound port (e.g., TCP 1555)**:
+  ```bash
+  poetry run firewalls_probes -H kde.org -p 1555 -proto tcp -t 3.0
+  ```
+  *Expected result*: `[FAILED]` due to `Connection timed out`.
+
+- **Outbound SSH to external host (TCP 22)**:
+  ```bash
+  poetry run firewalls_probes -H github.com -p 22 -proto tcp -t 3.0
+  ```
+  *Expected result*: `[FAILED]` (if outbound SSH is not explicitly allowed).
+
+#### 3. Incoming Traffic (Ingress / Listen Mode)
+
+- **Test if a local port accepts incoming connections**:
+  ```bash
+  # Listens on port 8080 locally for up to 10 seconds waiting for an incoming connection
+  poetry run firewalls_probes -l -p 8080 -t 10.0
+  ```
+- **Listen on local UDP port**:
+  ```bash
+  poetry run firewalls_probes -l -p 51820 -proto udp -t 10.0
+  ```
+
+#### 4. Integrated Verification with Live Monitor
+
+To visually confirm that packet drops are recorded accurately:
+
+1. In one terminal, launch the live dashboard:
+   ```bash
+   poetry run firewalls_monitor -a
+   ```
+2. In a second terminal, execute a blocked probe:
+   ```bash
+   poetry run firewalls_probes -H kde.org -p 1555
+   ```
+3. Observe the denial registered in real time under the **DENIED OUTGOING (EGRESS)** panel, complete with destination IP and reverse DNS PTR hostname.
+
+---
+
+## 🔒 Log Architecture and `dmesg` Protection
+
+To prevent firewall drop logs from flooding the kernel ring buffer (`dmesg`) and `/var/log/messages`:
+
+1. **On-Demand Drop Logging (`LogDenied=off` by default)**:
+   - Traditionally, setting `LogDenied=all` in `firewalld` triggers `printk()` calls at the kernel level via `nf_log_syslog`, polluting `dmesg` with local network broadcast and drop packets.
+   - **Dynamic Solution**: In `firewalld.conf`, `LogDenied` is set to `off` permanently. During normal operation, the firewall operates completely silently.
+   - **Automatic CLI Activation**:
+     - When starting `firewalls_log_ingress`, `firewalls_log_egress`, or `firewalls_monitor` (run as `root`), they dynamically invoke:
+       ```bash
+       firewall-cmd --set-log-denied=all
+       ```
+     - Upon exiting or pressing **Ctrl+C**, the signal handler immediately restores:
+       ```bash
+       firewall-cmd --set-log-denied=off
+       ```
+     - Kernel drop logging only takes place while an administrator is actively monitoring traffic.
+
+2. **syslog-ng Routing**:
+   - `syslog-ng` captures firewall drops and routes them exclusively to `/var/log/firewalld/denied.log`.
+   - Includes a `throttle(30)` directive to prevent disk exhaustion from log flooding attacks.
+   - `firewalls_deploy` automatically configures `@include "/etc/syslog-ng/conf.d/*.conf"` before catch-all rules, guaranteeing with `flags(final);` that firewall drops do not leak into `/var/log/messages`.
+
+---
+
+## ➕ Adding a New Machine
+
+1. Use the instructions and master prompt in **[AI_PROMPT.md](AI_PROMPT.md)** with an AI assistant, or copy the `example/` template:
+   ```bash
+   mkdir -p ~/my-firewalls/server1
+   cp -r example/* ~/my-firewalls/server1/
+   ```
+2. Customize the XML files in `~/my-firewalls/server1/etc/firewalld/` for your host.
+3. Deploy with:
+   ```bash
+   poetry run firewalls_deploy ~/my-firewalls/server1
+   # Or with FIREWALLS_DIR exported:
+   poetry run firewalls_deploy server1
+   ```
+

firewalls-0.1.0/README.md

@@ -0,0 +1,235 @@
+# Firewalls Configuration
+
+Centralized management and deployment of `firewalld` configurations for Gentoo Linux systems, packaged and managed with **Poetry**.
+
+---
+
+## 🗂️ Project Structure
+
+The public repository contains the CLI deployment tool, log streaming monitors, connectivity probes, and a clean template configuration (`example/`). Machine-specific configurations (private workstations, production servers) can be maintained in a separate private repository or external directory:
+
+```text
+firewalls/
+├── pyproject.toml                # Poetry package configuration and dependencies
+├── firewalls/                    # Python package containing CLI tools
+│   ├── __init__.py
+│   ├── cli.py                    # Deployment and service control
+│   ├── log_control.py            # Dynamic runtime LogDenied manager
+│   ├── monitor.py                # Live real-time dashboard
+│   ├── log_ingress.py            # Inbound blocked traffic monitor
+│   ├── log_egress.py             # Outbound blocked traffic monitor
+│   └── probes.py                 # Network connectivity probes
+├── AI_PROMPT.md                  # Master prompt and guide for generating configurations with AI
+├── README.md
+└── example/                      # Clean machine configuration template
+    ├── EXAMPLE.md                # Functional documentation of rules and services
+    ├── post_deploy.sh.example    # Optional post-deployment script template
+    └── etc/
+        ├── firewalld/
+        │   ├── firewalld.conf    # Main firewalld configuration
+        │   ├── lockdown-whitelist.xml
+        │   ├── zones/            # Zone definitions (e.g. public.xml)
+        │   ├── services/         # Custom service definitions
+        │   ├── ipsets/           # IPSet definitions (e.g. trusted-dns.xml)
+        │   ├── icmptypes/        # ICMP type definitions
+        │   ├── helpers/          # Connection helpers
+        │   └── policies/         # Egress and inter-zone policies (egress-policy.xml)
+        ├── syslog-ng/conf.d/     # Log routing into /var/log/firewalld/
+        ├── logrotate.d/          # Log rotation configuration
+        └── sysctl.d/             # Kernel network hardening (rp_filter, anti-spoofing)
+```
+
+---
+
+## 🤖 Generating Machine Configurations with AI
+
+To easily generate a customized firewall configuration using an AI assistant (Claude, Gemini, ChatGPT, Antigravity, etc.), refer to **[AI_PROMPT.md](AI_PROMPT.md)**. It provides a master prompt ready to customize with your machine's role, network interfaces, and allowed services.
+
+---
+
+## 🚀 Usage
+
+All commands are managed through **Poetry**:
+
+### 1. Deploying a Machine Configuration
+
+Machine configurations can reside in any local directory or private git repository:
+
+1. **Direct path** (absolute or relative):
+   ```bash
+   poetry run firewalls_deploy /path/to/my-firewalls/my_machine
+   ```
+
+2. **Using the `--configs-dir` (`-d`) option**:
+   ```bash
+   poetry run firewalls_deploy my_machine --configs-dir /path/to/my-firewalls
+   ```
+
+3. **Using the environment variable** (Recommended):
+   ```bash
+   export FIREWALLS_DIR="$HOME/my-firewalls"
+   poetry run firewalls_deploy my_machine
+   ```
+
+4. **Template or repository machines** (also checks `~/.config/firewalls/machines/`):
+   ```bash
+   poetry run firewalls_deploy example
+   ```
+
+### 2. Stopping the `firewalld` Service
+
+```bash
+poetry run firewalls_deploy stop
+```
+
+### What `firewalls_deploy` Does:
+1. Resolves and validates the machine configuration across search paths (`--configs-dir`, `$FIREWALLS_DIR`, `~/.config/firewalls/machines/`, direct path, or local directory).
+2. Verifies `root` privileges.
+3. Synchronizes `<machine>/etc/` into system `/etc/` preserving permissions, symlinks, and directory structure.
+4. Enforces `root:root` ownership and secure permissions (`0750` directories, `0644` files) strictly on files written under `/etc/firewalld`, without modifying parent directory permissions of `/etc`.
+5. Re-applies kernel network security parameters from `/etc/sysctl.d/` if present.
+6. Configures and restarts/reloads `syslog-ng` to isolate firewall logs into `/var/log/firewalld/`.
+7. Reloads `firewalld` rules via `firewall-cmd --reload` (or starts the service with OpenRC / systemd if stopped).
+8. Automatically executes the optional `post_deploy.sh` script if present in the machine folder.
+
+---
+
+## 📊 Real-Time Monitoring and Log Analysis
+
+You can monitor, tally, or summarize blocked events with the built-in CLI tools:
+
+```bash
+# Monitor blocked incoming connections (Ingress)
+poetry run firewalls_log_ingress
+poetry run firewalls_log_ingress --summary   # Displays ranked summary
+
+# Monitor blocked outgoing connections (Egress)
+poetry run firewalls_log_egress
+poetry run firewalls_log_egress --summary    # Displays ranked summary
+
+# Live interactive dashboard (Ingress + Egress with reverse DNS PTR)
+poetry run firewalls_monitor                            # Default refresh (3s), top 20 rankings, DNS resolution
+poetry run firewalls_monitor -n 2 -p 5                  # Refresh every 2s showing top 5 entries
+poetry run firewalls_monitor --no-resolve               # Show raw IP addresses without reverse DNS
+```
+
+---
+
+## 🧪 Connectivity Probes (`firewalls_probes`)
+
+The `firewalls_probes` command tests connectivity for both **outgoing (egress)** and **incoming (ingress / listen)** traffic to validate that firewall policies work as expected.
+
+### Command Options
+
+| Parameter | Short | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `--host` | `-H` | Target hostname or IP address for outbound probes | `kde.org` |
+| `--port` | `-p` | Port number to probe | `1555` |
+| `--protocol` | `-proto` | Transport protocol (`tcp` or `udp`) | `tcp` |
+| `--timeout` | `-t` | Maximum socket timeout in seconds | `5.0` |
+| `--count` | `-c` | Number of probe iterations | `1` |
+| `--listen` | `-l` | **Listen Mode (Ingress)**: Opens port locally to wait for incoming connections | Disabled (Outbound) |
+| `--bind` | `-b` | Local interface IP address to bind in listen mode | `0.0.0.0` |
+
+---
+
+### Recommended Verification Test Suite
+
+#### 1. Outgoing Permitted Traffic (Egress - Expected Success)
+
+- **Standard Web Traffic (HTTP/HTTPS)**:
+  ```bash
+  poetry run firewalls_probes -H kde.org -p 80 -proto tcp
+  poetry run firewalls_probes -H kde.org -p 443 -proto tcp
+  ```
+- **Gentoo Portage Sync (rsync)**:
+  ```bash
+  poetry run firewalls_probes -H rsync.gentoo.org -p 873 -proto tcp
+  ```
+- **DNS Resolution and Time Sync (NTP)**:
+  ```bash
+  poetry run firewalls_probes -H 1.1.1.1 -p 53 -proto udp
+  poetry run firewalls_probes -H pool.ntp.org -p 123 -proto udp
+  ```
+
+#### 2. Outgoing Blocked Traffic (Zero Trust - Expected Drop)
+
+- **Unauthorized outbound port (e.g., TCP 1555)**:
+  ```bash
+  poetry run firewalls_probes -H kde.org -p 1555 -proto tcp -t 3.0
+  ```
+  *Expected result*: `[FAILED]` due to `Connection timed out`.
+
+- **Outbound SSH to external host (TCP 22)**:
+  ```bash
+  poetry run firewalls_probes -H github.com -p 22 -proto tcp -t 3.0
+  ```
+  *Expected result*: `[FAILED]` (if outbound SSH is not explicitly allowed).
+
+#### 3. Incoming Traffic (Ingress / Listen Mode)
+
+- **Test if a local port accepts incoming connections**:
+  ```bash
+  # Listens on port 8080 locally for up to 10 seconds waiting for an incoming connection
+  poetry run firewalls_probes -l -p 8080 -t 10.0
+  ```
+- **Listen on local UDP port**:
+  ```bash
+  poetry run firewalls_probes -l -p 51820 -proto udp -t 10.0
+  ```
+
+#### 4. Integrated Verification with Live Monitor
+
+To visually confirm that packet drops are recorded accurately:
+
+1. In one terminal, launch the live dashboard:
+   ```bash
+   poetry run firewalls_monitor -a
+   ```
+2. In a second terminal, execute a blocked probe:
+   ```bash
+   poetry run firewalls_probes -H kde.org -p 1555
+   ```
+3. Observe the denial registered in real time under the **DENIED OUTGOING (EGRESS)** panel, complete with destination IP and reverse DNS PTR hostname.
+
+---
+
+## 🔒 Log Architecture and `dmesg` Protection
+
+To prevent firewall drop logs from flooding the kernel ring buffer (`dmesg`) and `/var/log/messages`:
+
+1. **On-Demand Drop Logging (`LogDenied=off` by default)**:
+   - Traditionally, setting `LogDenied=all` in `firewalld` triggers `printk()` calls at the kernel level via `nf_log_syslog`, polluting `dmesg` with local network broadcast and drop packets.
+   - **Dynamic Solution**: In `firewalld.conf`, `LogDenied` is set to `off` permanently. During normal operation, the firewall operates completely silently.
+   - **Automatic CLI Activation**:
+     - When starting `firewalls_log_ingress`, `firewalls_log_egress`, or `firewalls_monitor` (run as `root`), they dynamically invoke:
+       ```bash
+       firewall-cmd --set-log-denied=all
+       ```
+     - Upon exiting or pressing **Ctrl+C**, the signal handler immediately restores:
+       ```bash
+       firewall-cmd --set-log-denied=off
+       ```
+     - Kernel drop logging only takes place while an administrator is actively monitoring traffic.
+
+2. **syslog-ng Routing**:
+   - `syslog-ng` captures firewall drops and routes them exclusively to `/var/log/firewalld/denied.log`.
+   - Includes a `throttle(30)` directive to prevent disk exhaustion from log flooding attacks.
+   - `firewalls_deploy` automatically configures `@include "/etc/syslog-ng/conf.d/*.conf"` before catch-all rules, guaranteeing with `flags(final);` that firewall drops do not leak into `/var/log/messages`.
+
+---
+
+## ➕ Adding a New Machine
+
+1. Use the instructions and master prompt in **[AI_PROMPT.md](AI_PROMPT.md)** with an AI assistant, or copy the `example/` template:
+   ```bash
+   mkdir -p ~/my-firewalls/server1
+   cp -r example/* ~/my-firewalls/server1/
+   ```
+2. Customize the XML files in `~/my-firewalls/server1/etc/firewalld/` for your host.
+3. Deploy with:
+   ```bash
+   poetry run firewalls_deploy ~/my-firewalls/server1
+   # Or with FIREWALLS_DIR exported:
+   poetry run firewalls_deploy server1
+   ```

firewalls-0.1.0/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.

firewalls-0.1.0/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

firewalls-0.1.0/example/etc/firewalld/helpers/.gitkeep

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

firewalls-0.1.0/example/etc/firewalld/icmptypes/.gitkeep

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

firewalls-0.1.0/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>

firewalls-0.1.0/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>

firewalls-0.1.0/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>

firewalls-0.1.0/example/etc/firewalld/services/.gitkeep

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

firewalls-0.1.0/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>

firewalls-0.1.0/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>