--- title: "Firewall Rules Module Documentation" description: "Documentation for Rules" --- ## Table of Contents 1. [Module Overview (Technical)](#1-module-overview-technical) 2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value) 3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities) 4. [Visual Interface & Form Structure](#4-visual-interface--form-structure) 5. [Architectural Flow & Security Governance](#5-architectural-flow--security-governance) 6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks) 7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands) 8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration) 9. [Glossary](#9-glossary) --- ## 1. Module Overview (Technical) The **Firewall Rules** module (`public.firewall_rules`) provides the policy orchestration engine for **Ring2All Billing**, enabling system operators to construct complex, multi-variable packet filtering statements. While the **Services** module defines ports and protocols, and **Access Control** manages quick IP whitelists and blacklists, **Firewall Rules** connects services, source subnets, destination interfaces, and evaluation actions into an ordered rule hierarchy. Each firewall rule defines an explicit Action (`Accept`, `Drop`, or `Reject`), directionality (`Input`, `Output`, or `Forward`), an associated named Service, a numeric evaluation Priority, source and destination CIDR boundaries, and optional interface binding. When committed via **Apply Rules**, the platform synchronizes the state directly with the underlying Linux netfilter engine (`nftables`/`iptables`). ### Data Model & System Linkage ``` ┌────────────────────────────────────────────────────────────────────────┐ │ Firewall Rule Entity (public.firewall_rules) │ │ • id: bigint (Primary Key) │ │ • name: VARCHAR(100) (Rule Name, e.g. 'Allow Fastify API from VPN') │ │ • action: 'accept' | 'drop' | 'reject' │ │ • direction: 'input' | 'output' | 'forward' │ │ • service_id: bigint (FK to public.firewall_services) │ │ • priority: integer (Execution Evaluation Order, e.g. 10, 20, 30) │ │ • source_address: VARCHAR(100) (e.g. '10.8.0.0/24', '192.168.10.0/24')│ │ • destination_address: VARCHAR(100) (Optional Local VIP or Interface) │ │ • interface: VARCHAR(50) (e.g. 'eth0', 'tun0', 'wg0') │ │ • enabled: boolean (Active State Toggle) │ └───────────────────────────────────┬────────────────────────────────────┘ │ ┌─────────────────────────┴─────────────────────────┐ ▼ ▼ ┌───────────────────────────────────┐ ┌───────────────────────────────────┐ │ Service Definition Lookup │ │ Linux Netfilter Pipeline │ │ • Extracts TCP/UDP protocol │ │ • Rules sorted by priority ASC │ │ • Extracts single port or range │ │ • Injected into nftables chain │ └───────────────────────────────────┘ └───────────────────────────────────┘ ``` ### PostgreSQL Schema Architecture * **`public.firewall_rules`**: * `id`: Numeric primary key (`bigserial`). * `name`: Concise, meaningful label identifying the policy purpose. * `action`: * `accept`: Allows packet traversal immediately. * `drop`: Discards packet silently without ICMP notification. * `reject`: Discards packet and issues an explicit ICMP unreachable response. * `direction`: Traffic vector (`input`, `output`, `forward`). * `service_id`: Foreign key pointing to `public.firewall_services.id`. * `priority`: Numeric weight controlling evaluation sequence. Rules are sorted in ascending order (`ORDER BY priority ASC`). * `source_address`: CIDR notation or specific IP restricting where traffic originates. * `destination_address`: Optional target IP constraint. * `interface`: Restricts policy application to a specific network interface. * `enabled`: Master switch controlling whether the rule is compiled into the running kernel firewall. --- ## 2. Module Overview (Commercial & Business Value) * **Zero-Trust Network Architecture:** Restricts sensitive billing administration and database replication exclusively to authorized corporate subnets, VPN tunnels, and trusted interconnects. * **Carrier SLA Assurance:** Protects carrier rating engines from distributed denial-of-service (DDoS) exhaustion, ensuring high-volume Call Detail Record (CDR) ingestion remains uninterrupted. * **Granular Policy Auditability:** Clean separation of concerns allows compliance auditors to verify that administrative interfaces (SSH, database, API) are never exposed directly to public ingress interfaces. --- ## 3. 🎯 User Roles & Key Capabilities | User Role | Key Permissions | Core Responsibilities & Workflows | | :--- | :--- | :--- | | **Super Administrator** | Full Control (`CRUD` on Firewall Rules) | Authors enterprise security policies, designs network segregation rules, reorders priority evaluation chains, and applies rules to the kernel. | | **Security Officer / SecOps** | Policy Audit & Optimization | Reviews rule ordering to eliminate shadowing and redundancy, validates source subnet restrictions, and verifies compliance with ISO 27001. | | **Network Engineer** | Read & Test (Routing & Interfaces) | Verifies interface bindings (e.g., ensuring internal telecom nodes communicate across `tun0`/`wg0` while customer portals bind to `eth0`). | --- ## 4. Visual Interface & Form Structure ### Level 1 — Firewall Rules List View The policy catalog displays all active rules ordered by priority, displaying rule names, target services, actions, direction, interface bindings, active statuses, and execution controls. ![Firewall Rules List View](/screenshots/billing/admin/firewall/rules/rules-list.png) ### Level 2 — Add Firewall Rule Modal The policy creation modal provides structured input fields to configure actions, services, priorities, and source/destination addresses. ![Add Firewall Rule Modal](/screenshots/billing/admin/firewall/rules/rules-modal.png) #### Fields & Parameters Reference * **Rule Name:** Descriptive title (e.g., `Allow HTTPS Portal Web`, `Restrict SSH to Management VPN`). * **Action:** Filtering decision (`Accept`, `Drop`, `Reject`). * **Direction:** Flow perspective (`Input`, `Output`, `Forward`). * **Service:** Dropdown selecting a preconfigured definition from the **Services** module. * **Priority:** Numeric execution order (e.g., `10`, `20`, `30`). Lowest numbers evaluate first. * **Source Address:** Origin CIDR subnet or IP address (e.g., `10.8.0.0/24` or `192.168.10.0/24`). Leave blank for any source (`0.0.0.0/0`). * **Destination Address:** Target CIDR subnet or local host IP. Leave blank for any local address. * **Interface:** Hardware or virtual interface binding (e.g., `eth0`, `ens33`, `tun0`, `wg0`). * **Enabled:** Operational toggle. Set to `Yes` to include the rule in kernel compilation. --- ## 5. Architectural Flow & Security Governance ``` ┌──────────────┐ 1. POST /api/firewall/rules ┌────────────────────────┐ │ System Admin ├───────────────────────────────────────────────►│ Fastify 5 API Route │ └──────────────┘ └───────────┬────────────┘ │ 2. Insert Rule Record into ss_billing ▼ ┌──────────────┐ 4. Atomic Rule Translation ┌────────────────────────┐ │ Linux Kernel ◄────────────────────────────────────────────────┤ nftables Synchronizer │ │ netfilter │ └────────────────────────┘ └──────────────┘ ▲ │ 3. User Clicks 'Apply Rules' ``` 1. **Rule Configuration:** The administrator defines the policy parameters in the modal dialog. 2. **Database Persistence:** The Fastify API performs boundary validation and records the rule in `public.firewall_rules`. 3. **Compilation Trigger:** The administrator clicks **Apply Rules** in the top-right toolbar. 4. **Kernel Synthesis:** The synchronizer queries all enabled rules ordered by priority, resolves associated service port definitions, generates an atomic `nftables` transaction, and loads it directly into the kernel without interrupting active sessions. --- ## 6. Common Scenarios & Operational Playbooks ### Playbook 1: Restricting SSH Access to Management VPN Only 1. Navigate to **ADMIN > Firewall > Rules**. 2. Click **+ Add** in the top-right toolbar. 3. Enter **Rule Name:** `Restrict SSH to OpenVPN Subnet`. 4. Set **Action:** `Accept`. 5. Set **Direction:** `Input`. 6. Select **Service:** `SSH Management` (Port 22). 7. Set **Priority:** `15`. 8. In **Source Address**, enter the VPN pool CIDR: `10.8.0.0/24`. 9. In **Interface**, enter: `tun0`. 10. Toggle **Enabled** to `Yes` and click **Create**. 11. Click **Apply Rules** to commit changes to the kernel. ### Playbook 2: Allowing Public Customer Access to Billing Web Portal 1. Navigate to **ADMIN > Firewall > Rules**. 2. Click **+ Add**. 3. Enter **Rule Name:** `Allow Public HTTPS Web Portal`. 4. Set **Action:** `Accept`. 5. Set **Direction:** `Input`. 6. Select **Service:** `HTTPS Portal Web` (Port 8443). 7. Set **Priority:** `20`. 8. Leave **Source Address** blank (`0.0.0.0/0`) to allow all public traffic. 9. Toggle **Enabled** to `Yes` and click **Create**. 10. Click **Apply Rules**. --- ## 7. Troubleshooting & Diagnostic Commands ### Querying Rules in Database ```bash # Display all rules sorted by priority sudo -u postgres psql -d ss_billing -c \ "SELECT r.priority, r.name, r.action, r.direction, s.name AS service, s.port, r.source_address, r.enabled \ FROM firewall_rules r \ JOIN firewall_services s ON r.service_id = s.id \ ORDER BY r.priority ASC;" ``` ### Inspecting Running Kernel Rules ```bash # View active nftables ruleset in human-readable format nft -a list ruleset | grep -A 5 "chain input" # View rule packet and byte counters nft list table inet filter ``` --- ## 8. Model Context Protocol (MCP) AI Integration The **Firewall Rules** module connects directly to the **Ring2All BSS MCP Server**, empowering security copilots and network automation tools to audit ordered rule sets and packet actions safely. ### Available MCP Tools | Tool Name | Access Role | Description & Primary Function | Example Arguments | | :--- | :--- | :--- | :--- | | `list_firewall_rules` | `Super Administrator` | Lists granular packet filtering firewall rules with evaluation priority, action (ACCEPT/DROP), and service associations. | `{}` | ### Sample MCP Tool Execution: `list_firewall_rules` #### Request Payload ```json { "name": "list_firewall_rules", "arguments": {} } ``` #### Response Payload ```json [ { "id": 1, "name": "Allow HTTPS Public Web", "action": "accept", "direction": "in", "priority": 10, "serviceName": "Billing HTTP/HTTPS", "sourceAddress": "any", "enabled": true }, { "id": 2, "name": "Drop Unauthenticated Management", "action": "drop", "direction": "in", "priority": 90, "serviceName": "SSH Management", "sourceAddress": "!192.168.10.0/24", "enabled": true } ] ``` ### Conversational AI Prompts for Copilot * *"List all active firewall rules sorted by evaluation priority."* * *"Show all DROP rules configured in the input chain."* * *"Verify if public access to port 443 is permitted."* --- ## 9. Glossary * **Evaluation Priority:** The chronological order in which the firewall tests incoming packets against rule definitions; first-match semantics terminate evaluation. * **Shadowing:** A configuration error where an overly broad high-priority rule prevents a more specific lower-priority rule from ever being evaluated. * **Interface Binding:** Limiting a firewall policy strictly to traffic flowing through a specific network interface (e.g., `tun0` for OpenVPN). * **ICMP Unreachable:** A reject response informing the client that the destination port or host is administratively filtered. * **Model Context Protocol (MCP):** Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.