---
title: "Geo Firewall Module Documentation"
description: "Documentation for Geo Firewall"
---

## 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 **Geo Firewall** module (`public.geo_firewall_rules`, `public.geo_ip_ranges`) provides country-level geographical IP filtering for **Ring2All Billing**. In telecommunications and billing operations, malicious connection attempts, credential attacks, and toll fraud schemes frequently originate from specific geographic regions where the operating company maintains no legitimate business presence, carrier interconnects, or customer accounts.

By leveraging an integrated MaxMind GeoLite2 / DB-IP database and high-performance Linux kernel sets (`nftables` sets / `ipset`), the Geo Firewall evaluates the geographic origin of every inbound packet at wire speed. Countries can be marked as **Allowed** (emerald green) or **Blocked** (crimson red). Blocked countries are dropped at the kernel `PREROUTING` stage before consuming application server memory or Fastify event-loop cycles.

### Data Model & Architecture Diagram

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │                 Geo Firewall Entity (public.geo_firewall_rules)        │
 │  • id: bigint (Primary Key)                                            │
 │  • country_code: CHAR(2) (ISO 3166-1 Alpha-2, e.g. 'RU', 'CN', 'US')   │
 │  • country_name: VARCHAR(100)                                          │
 │  • action: 'allow' | 'block'                                           │
 │  • notes: text                                                         │
 │  • enabled: boolean                                                    │
 │  • updated_at: timestamptz                                             │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           ▼                                                   ▼
 ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
 │       MaxMind GeoIP Database      │               │     Linux Kernel nftables Set     │
 │ • Binary lookup / CIDR blocks     │               │ • nft add set inet filter geo_drop│
 │ • Updated weekly via cron         │               │ • O(1) hash lookup per packet     │
 └───────────────────────────────────┘               └───────────────────────────────────┘
```

### PostgreSQL Schema Architecture

* **`public.geo_firewall_rules`**:
  * `id`: Numeric primary key (`bigserial`).
  * `country_code`: Standard ISO 3166-1 Alpha-2 two-character country code.
  * `country_name`: Full formal geographic name.
  * `action`: Enforcement directive (`'allow'` or `'block'`).
  * `enabled`: Active state flag.
  * `updated_at`: Timestamp recording when the regional policy was modified.

---

## 2. Module Overview (Commercial & Business Value)

* **95%+ Attack Surface Reduction:** Blocking countries outside the carrier's operating footprint immediately eliminates the vast majority of automated botnet scans, unauthorized SIP registrations, and SSH brute-force campaigns.
* **Toll Fraud & IRSF Mitigation:** Prevents rogue actors in offshore jurisdictions from scanning billing self-care portals or intercepting online rating mechanisms.
* **Server Resource Preservation:** Dropping unwanted geographical traffic in the kernel eliminates up to 90% of useless socket allocations, ensuring the Fastify API and OCS balance deduction engines run with minimal latency.

---

## 3. 🎯 User Roles & Key Capabilities

| User Role | Key Permissions | Core Responsibilities & Workflows |
| :--- | :--- | :--- |
| **Super Administrator** | Full Control (`RW` on Geo-Firewall) | Configures national allow/block lists, toggles regional access policies, and saves changes to kernel netfilter tables. |
| **Security Officer / SecOps** | Geographic Threat Analysis | Analyzes attack origins on the AI Perimeter Guard dashboard, identifies malicious clusters, and updates Geo-Firewall rules accordingly. |
| **Billing Operations Lead** | Read-Only (Territorial Coverage) | Verifies that countries where new enterprise customers or carrier interconnects are located are properly marked as **Allowed**. |

---

## 4. Visual Interface & Form Structure

### Level 1 — Geo Firewall Interactive World Map
The interface presents an interactive vector world map (`WorldMap.tsx` / `jsvectormap`) rendering global geographical boundaries. Allowed countries are rendered in emerald green, while blocked regions illuminate in vivid crimson red.

![Geo Firewall World Map](/screenshots/billing/admin/firewall/geo-firewall/geo-firewall-list.png)

#### Controls & Parameters Reference
* **Interactive World Map:** Click any nation to toggle its filtering status between **Allowed** and **Blocked**. Hovering displays the country name, two-letter code, and current state.
* **Search Country Selector:** Dropdown search box in the header toolbar allowing rapid lookup and centering of any nation.
* **Map Zoom Controls:** Bottom-left floating controls providing **Zoom In (+)**, **Zoom Out (-)**, and **Reset View**.
* **Sticky Action Bar:** Floating bottom toolbar featuring the **Save** button to persist modified country lists and recompile kernel sets.

---

## 5. Architectural Flow & Security Governance

```
  ┌──────────────┐         1. Inbound Network Packet              ┌────────────────────────┐
  │ Foreign Host ├───────────────────────────────────────────────►│ Linux Kernel Netfilter │
  └──────────────┘                                                └───────────┬────────────┘
                                                                              │
                                                                 2. O(1) Set Lookup Against
                                                                    GeoIP Subnets (nftables)
                                                                              ▼
                                                    ┌───────────────────────────────────────────┐
                                                    │ Match in Blocked Regional CIDR Set?       │
                                                    └─────┬───────────────────────────────┬─────┘
                                                          │ Yes                           │ No
                                                          ▼                               ▼
                                               ┌─────────────────────┐         ┌─────────────────────┐
                                               │ Silent Kernel DROP  │         │ Fastify 5 API / Web │
                                               │ (0 CPU overhead)    │         │ Session Evaluation  │
                                               └─────────────────────┘         └─────────────────────┘
```

1. **Ingress Arrival:** A packet arrives from an external IP address.
2. **Kernel Set Inspection:** The Linux `nftables` netfilter chain references the compiled `geo_drop` set.
3. **Instant Mitigation:** If the IP belongs to a blocked country's CIDR ranges, the packet is silently dropped at `PREROUTING` before any application code executes.
4. **Allowed Path:** Packets from permitted countries proceed to standard port filtering and authentication.

---

## 6. Common Scenarios & Operational Playbooks

### Playbook 1: Blocking High-Risk Jurisdictions Following a Brute-Force Surge
1. Review the **AI Perimeter Guard** telemetry to identify the top attack origins (e.g., Russian Federation, Eastern Asia).
2. Navigate to **ADMIN > Firewall > Geo Firewall**.
3. Use the search selector in the top toolbar to locate the offending country (e.g., `Russian Federation`).
4. Click on the country on the world map to toggle its state from **Allowed** (Green) to **Blocked** (Red).
5. Repeat for any other target regions (e.g., `China`).
6. Click **Save** in the bottom-right action bar.
7. The system regenerates the kernel IP set and applies the block immediately.

### Playbook 2: Unblocking a Country for International Expansion
1. When onboarding a new customer or carrier interconnect in a previously blocked country (e.g., Germany or Brazil):
2. Navigate to **ADMIN > Firewall > Geo Firewall**.
3. Locate the country on the map or type its name in the search bar.
4. Click the territory so it changes to **Allowed** (Green).
5. Click **Save** to commit the changes and remove the country's IP subnets from the kernel drop set.

---

## 7. Troubleshooting & Diagnostic Commands

### Inspecting Configured Geo Rules in Database
```bash
sudo -u postgres psql -d ss_billing -c \
  "SELECT country_code, country_name, action, enabled, updated_at \
   FROM geo_firewall_rules WHERE action = 'block' ORDER BY country_name ASC;"
```

### Checking Linux nftables Geo Drop Sets
```bash
# Count total CIDR elements loaded into the geo drop set
nft list set inet filter geo_drop | grep -c "elements"

# Verify if a specific IP belongs to a blocked geo set
nft "get element inet filter geo_drop { 198.51.100.1 }"
```

---

## 8. Model Context Protocol (MCP) AI Integration

The **Geo Firewall** module connects directly to the **Ring2All BSS MCP Server**, providing security copilots and network automation tools with instant visibility into geographic filtering policies and blocked territory counts.

### Available MCP Tools

| Tool Name | Access Role | Description & Primary Function | Example Arguments |
| :--- | :--- | :--- | :--- |
| `get_geo_firewall_status` | `Super Administrator` | Retrieves geographical IP blocking status, blocked country count, and database version. | `{}` |

### Sample MCP Tool Execution: `get_geo_firewall_status`

#### Request Payload
```json
{
  "name": "get_geo_firewall_status",
  "arguments": {}
}
```

#### Response Payload
```json
{
  "geoFirewallEnabled": true,
  "blockedCountriesCount": 18,
  "allowedCountriesCount": 231,
  "geoDbVersion": "GeoLite2-Country-2026.09",
  "kernelSetLoaded": true,
  "topBlockedCountries": ["RU", "CN", "IR", "KP", "NG"]
}
```

### Conversational AI Prompts for Copilot
* *"What is the status of the Geo Firewall and how many countries are blocked?"*
* *"List the top blocked country codes enforced at the kernel level."*
* *"Verify if the GeoIP database is current and loaded into nftables."*

---

## 9. Glossary

* **ISO 3166-1 Alpha-2:** Two-letter country codes representing countries and dependent territories (e.g., `US`, `DE`, `MX`).
* **GeoIP Database:** A structured mapping table connecting public IPv4 and IPv6 address ranges to geographic countries, cities, and autonomous system numbers (ASNs).
* **PREROUTING:** The earliest stage in the Linux network stack where incoming packets can be evaluated before routing decisions are made.
* **O(1) Set Lookup:** Constant-time algorithmic lookup provided by kernel hash tables (`nftables` sets / `ipset`), ensuring zero latency impact regardless of table size.
* **Model Context Protocol (MCP):** Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.