--- title: "Firewall Settings Module Documentation" description: "Documentation for Firewall Settings" --- ## 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 Settings** module (`public.firewall_settings`) governs the master operating state of host-level packet filtering and daemonized intrusion prevention on the **Ring2All Billing** application server. Operating as the control plane for underlying Linux network utilities (`nftables`/`iptables` and `fail2ban`), this module ensures that telecommunications rating APIs, web interfaces, and administrative ports are protected behind a deterministic, stateful security perimeter. When enabled, the firewall enforces default-deny ingress policies, admitting only traffic explicitly whitelisted by services, rules, or access control entries. Concurrently, the Intrusion Detection subsystem scans log files for authentication abuse, actively applying dynamic jail bans to persistent attackers. ### Data Model & Architecture Diagram ``` ┌────────────────────────────────────────────────────────────────────────┐ │ Firewall Settings Entity (public.firewall_settings) │ │ • id: bigint (Primary Key) │ │ • firewall_enabled: boolean (Master nftables/iptables Ingress Filter) │ │ • fail2ban_enabled: boolean (Daemonized Log Parsing & Jail Monitor) │ │ • default_policy: 'drop' | 'reject' | 'accept' │ │ • log_dropped_packets: boolean │ │ • updated_at: timestamptz │ └───────────────────────────────────┬────────────────────────────────────┘ │ ┌─────────────────────────┴─────────────────────────┐ ▼ ▼ ┌───────────────────────────────────┐ ┌───────────────────────────────────┐ │ Linux netfilter Subsystem │ │ Fail2Ban Daemon Monitor │ │ • Default Ingress: DROP │ │ • Monitors /var/log/nginx/access │ │ • Established/Related: ACCEPT │ │ • Monitors Fastify auth logs │ │ • Allowed Services: TCP/UDP ports │ │ • Jail: ring2all-billing-auth │ └───────────────────────────────────┘ └───────────────────────────────────┘ ``` ### PostgreSQL Schema Architecture * **`public.firewall_settings`**: * `id`: Numeric primary key (`bigserial`). * `firewall_enabled`: Master switch. When `true`, systemd service `nftables.service` (or `iptables`) is kept in an active running state with strict chain filtering. * `fail2ban_enabled`: Controls the operational state of `fail2ban.service`. When active, specialized jail filters parse Fastify 401 unauthorized responses and NGINX error streams. * `updated_at`: Timestamp recording when the security posture was modified. --- ## 2. Module Overview (Commercial & Business Value) * **Enterprise Hardening Out of the Box:** Eliminates accidental exposure of internal billing microservices, database listening ports (`5432`), or Redis cache instances (`6379`) to the public Internet. * **Defense-in-Depth Against Infrastructure Takeover:** Combines stateful packet filtering with dynamic log-based intrusion detection to stop automated port scans and brute force attacks before they consume server CPU cycles. * **Operational Simplicity:** Provides telecom system administrators with a simple, high-level control panel to govern host security without requiring manual SSH command-line intervention for core service toggling. --- ## 3. 🎯 User Roles & Key Capabilities | User Role | Key Permissions | Core Responsibilities & Workflows | | :--- | :--- | :--- | | **Super Administrator** | Full Control (`RW` on Firewall Settings) | Activates or deactivates the host packet filtering engine, enables Fail2Ban intrusion detection, and commits security profile changes. | | **Security Officer / SecOps** | Audit & Verification | Audits current firewall and intrusion detection daemon states, verifies compliance against internal security baselines, and recommends policy updates. | | **Billing Operator** | Read-Only (Status View) | Inspects whether the firewall is active to rule out network filtering issues during third-party payment gateway integration. | --- ## 4. Visual Interface & Form Structure ### Level 1 — Firewall Settings View The interface presents clear, high-contrast operational cards organizing host firewall filtering and daemon intrusion detection controls, with a sticky action bar for committing changes. ![Firewall Settings View](/screenshots/billing/admin/firewall/firewall-settings/firewall-settings.png) #### Fields & Parameters Reference * **Firewall Status (Toggle):** Master switch controlling host packet filtering. * *Active (Yes):* Linux kernel packet filtering rules are applied. All ports not explicitly defined in **Services** or **Rules** are blocked. * *Inactive (No):* Kernel filtering is disabled; incoming traffic reaches listening sockets freely. * **Intrusion Detection (Fail2Ban) (Toggle):** Controls automated log-based banning. * *Active (Yes):* Fail2Ban daemon actively scans authentication logs, automatically banning source IPs that fail authentication repeatedly. * *Inactive (No):* Intrusion monitoring is suspended; no automated bans are initiated. * **Save Button:** Commits the configuration to PostgreSQL and signals the backend security agent to synchronize systemd services. --- ## 5. Architectural Flow & Security Governance ``` ┌──────────────┐ 1. PUT /api/firewall/settings ┌────────────────────────┐ │ System Admin ├───────────────────────────────────────────────►│ Fastify 5 API Route │ └──────────────┘ └───────────┬────────────┘ │ 2. Update │ 3. Dispatch System Database │ Command Event ▼ ┌────────────────────────┐ │ ss_billing Database │ │ (firewall_settings) │ └────────────────────────┘ │ ┌────────────────────────────────┴────────────────────────────────┐ ▼ ▼ ┌──────────────────────────┐ ┌──────────────────────────┐ │ systemctl start nftables │ │ systemctl start fail2ban │ └──────────────────────────┘ └──────────────────────────┘ ``` 1. **Administration Trigger:** The administrator toggles the desired subsystem and clicks **Save**. 2. **Atomic Persistence:** The Fastify API validates administrative privileges and records the state in `public.firewall_settings`. 3. **Daemon Synchronization:** The backend security runner triggers the platform orchestration command via `systemctl`, ensuring system services reflect the configured state. --- ## 6. Common Scenarios & Operational Playbooks ### Playbook 1: Enabling Production Firewall Protection 1. Navigate to **ADMIN > Firewall > Firewall Settings**. 2. Verify under **ADMIN > Firewall > Services** that essential ports (HTTP: 80, HTTPS: 8443, API: 3003, SSH: 22) are correctly defined. 3. Return to **Firewall Settings**. 4. Toggle **Firewall Status** to **Yes**. 5. Toggle **Intrusion Detection (Fail2Ban)** to **Yes**. 6. Click **Save** in the bottom-right action bar. 7. Verify immediate server responsiveness on active administrative sessions. ### Playbook 2: Temporarily Suspending Filtering for Network Diagnosis 1. Navigate to **ADMIN > Firewall > Firewall Settings**. 2. Toggle **Firewall Status** to **No**. 3. Click **Save**. 4. Perform end-to-end network latency or port reachability diagnosis with the carrier provider. 5. Immediately return to **Firewall Settings**, toggle **Firewall Status** back to **Yes**, and click **Save**. --- ## 7. Troubleshooting & Diagnostic Commands ### Checking Service States via Systemd ```bash # Verify status of Linux packet filter systemctl status nftables || systemctl status iptables # Verify status of Fail2Ban intrusion detection daemon systemctl status fail2ban # Check Fail2Ban active jails and banned IPs fail2ban-client status ``` ### Inspecting Database Settings ```bash sudo -u postgres psql -d ss_billing -c \ "SELECT id, firewall_enabled, fail2ban_enabled, updated_at FROM firewall_settings;" ``` --- ## 8. Model Context Protocol (MCP) AI Integration The **Firewall Settings** module connects directly to the **Ring2All BSS MCP Server**, providing security administrators and AI infrastructure assistants with read-only visibility into master firewall operating parameters and intrusion defense states. ### Available MCP Tools | Tool Name | Access Role | Description & Primary Function | Example Arguments | | :--- | :--- | :--- | :--- | | `get_firewall_settings` | `Super Administrator` | Retrieves core firewall operating state, default policies, and Fail2Ban service status. | `{}` | ### Sample MCP Tool Execution: `get_firewall_settings` #### Request Payload ```json { "name": "get_firewall_settings", "arguments": {} } ``` #### Response Payload ```json { "firewallEnabled": true, "fail2banEnabled": true, "defaultPolicy": "DROP", "synFloodProtection": true, "pingProtection": false, "backend": "nftables", "updatedAt": "2026-09-08T10:00:00Z" } ``` ### Conversational AI Prompts for Copilot * *"Is the host firewall currently enabled and enforcing default-drop policies?"* * *"What is the status of the Fail2Ban intrusion detection daemon?"* * *"Verify if SYN flood protection is active on the billing server."* --- ## 9. Glossary * **Packet Filtering:** The process of inspecting incoming and outgoing IP packets and either accepting, dropping, or rejecting them based on IP, port, and protocol. * **Fail2Ban:** An open-source intrusion prevention framework that monitors application log files for suspicious activity and creates dynamic firewall rules. * **Default Deny:** A security posture where all network traffic is blocked by default, requiring explicit rules to permit desired communication. * **Stateful Inspection:** Tracking the state of active network connections to automatically permit returning traffic belonging to recognized sessions. * **Model Context Protocol (MCP):** Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.