---
title: "Geo-Firewall & Sovereign SIP Traffic Filtering"
description: "Documentation for Geo Firewall"
---

## Table of Contents
1. [Overview & Geolocation Architecture](#1-overview--geolocation-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & Geolocation Filtering Parameters](#5-field-reference--geolocation-filtering-parameters)
6. [MaxMind GeoIP2 Integration & In-Memory Lookup](#6-maxmind-geoip2-integration--in-memory-lookup)
7. [Operational Policy Design: Allowlist vs Blocklist](#7-operational-policy-design-allowlist-vs-blocklist)
8. [Verification & Diagnostics](#8-verification--diagnostics)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Geolocation Architecture

In **Ring2All SBC**, the **Geo-Firewall** module provides geographic packet filtering and sovereign boundary enforcement for SIP signaling. Operating at the intersection of IP geolocation databases and Kamailio routing logic, the Geo-Firewall allows administrators to visually allow or block SIP traffic originating from specific sovereign nations or geographic territories.

```
       ┌─────────────────────────────────────────────────────────────┐
       │                 INCOMING SIP SIGNALING PACKET               │
       │                   (Source IP: e.g., 185.x.x.x)              │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
       ┌──────────────────────────────▼──────────────────────────────┐
       │             KAMAILIO GEOIP2 IN-MEMORY LOOKUP                │
       │           ($gip(src=>cc) returns ISO Country Code)          │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
              ┌───────────────────────┴───────────────────────┐
              ▼ (Match: e.g. "RU", "CN")                      ▼ (Match: e.g. "US", "CA")
       ┌──────────────────────────────┐                ┌──────────────────────────────┐
       │       GEO-RULE: BLOCK        │                │       GEO-RULE: ALLOW        │
       ├──────────────────────────────┤                ├──────────────────────────────┤
       │ • Silent packet drop or 403  │                │ • Proceed to SIP Auth checks │
       │ • Increment geo hit counter  │                │ • Dispatch to Core PBX trunk │
       │ • Telemetry forensic log     │                │ • Normal call setup flow     │
       └──────────────────────────────┘                └──────────────────────────────┘
```

The system pairs an interactive high-resolution SVG world map with the high-speed **MaxMind GeoIP2** binary database (`/var/lib/GeoIP/GeoLite2-Country.mmdb`), resolving source IP coordinates in sub-microsecond time directly within Kamailio worker processes.

---

## 2. Business & Operational Significance

* **Eradication of Offshore Attack Surfaces**: Instantly neutralizes 95%+ of automated botnet probes, extension scans, and password-guessing bots originating from geographic jurisdictions where the organization conducts no legitimate telecommunications business.
* **Proactive International Toll Fraud Prevention**: Blocks incoming SIP INVITE probes from known high-risk toll fraud regions, eliminating exposure to revenue-share fraud exploitation.
* **Regulatory & Sovereign Compliance**: Helps telecommunications carriers comply with local data sovereignty laws and international sanctions policies by restricting call signaling within approved borders.
* **Visual Map-Based Operations**: Empowers NOC engineers to immediately visualize global traffic allowances, search sovereign nations by name or ISO code, and toggle policies with a single click.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **SBC Security Administrator** | Sovereign Perimeter Policy | Define global country-based filtering policies, search and toggle sovereign nations on the interactive map, and adjust default verdicts. |
| **Fraud Prevention Manager** | Geopolitical Threat Mitigation | Analyze call attempt spikes by country, restrict high-risk originating jurisdictions, and audit blocked attempt metrics. |
| **Carrier Account Manager** | Interconnect Boundary Validation | Verify that partner carrier traffic origins match contracted operational zones and resolve legitimate roaming disputes. |
| **NOC Operations Lead** | Incident Response | Rapidly isolate emergency cyber-attacks originating from specific countries by imposing temporary nationwide blocks. |
| **AI Sovereign Security Agent / NOC Copilot** | Geopolitical Threat Mitigation & Policy Auditing | Inspect country filtering rules, audit hit metrics, and create or toggle sovereign territorial blocking rules via MCP. |

---

## 4. Visual Interface & Layout

The Geo-Firewall console features an interactive vector-based world map interface with dynamic country focus search, visual state coloring, zoom navigation, and atomic rule persistence.

### 4.1 Interactive Geo-Firewall World Map
Displays all sovereign nations, color-coded by policy status (Green for Allowed, Red for Blocked, Slate for Unselected), with rapid zoom and focus controls.

![Geo-Firewall World Map View](/screenshots/sbc/admin/geofirewall/geofirewall-list.png)

---

## 5. Field Reference & Geolocation Filtering Parameters

| Field | Type | Options | Description |
| :--- | :--- | :--- | :--- |
| **Country Name** | String | Search Filter | Common sovereign country name (e.g., *United States*, *Germany*, *Costa Rica*). |
| **ISO Country Code** | String (2 Char) | ISO 3166-1 alpha-2 | Standardized two-character country code (e.g., `US`, `DE`, `CR`, `NL`). |
| **Action** | Toggle / State | `ALLOW` / `BLOCK` | The filtering policy applied to SIP traffic originating from the selected territory. |
| **Hit Count** | Numeric Counter | Read-Only | Cumulative counter tracking the number of SIP packets blocked or filtered under this country rule. |
| **Search Country to Focus** | Autocomplete | Search Input | Rapid lookup field that zooms and centers the interactive vector map on the targeted country. |

---

## 6. MaxMind GeoIP2 Integration & In-Memory Lookup

The Geo-Firewall operates via Kamailio's native `geoip2` module, loading the MaxMind database into memory during initialization:

```
# kamailio.cfg snippet
loadmodule "geoip2.so"
modparam("geoip2", "geoip2_database", "/var/lib/GeoIP/GeoLite2-Country.mmdb")

route[GEO_FILTER] {
    # Resolve source IP country code
    if (geoip2_match("$si", "src")) {
        $var(country) = $gip(src=>cc);

        # Check against blocked countries hash table
        if ($sht(geoblock=>$var(country)) == 1) {
            xlog("L_WARN", "GEO-FIREWALL: Blocked SIP request from $si [Country: $var(country)]\n");
            drop;
        }
    }
}
```

Because the database resides in shared memory, country resolution incurs zero database round-trips and adds less than **0.05 milliseconds** of latency to SIP request processing.

---

## 7. Operational Policy Design: Allowlist vs Blocklist

When designing a sovereign filtering architecture, security architects should choose between two operational models:

### 7.1 Blocklist Model (Default Allow)
* **Approach**: All countries are permitted by default; administrators explicitly select and block specific hostile jurisdictions (e.g., high-risk IRSF originations).
* **Best For**: Wholesale carriers and international transit operators serving global multi-national clients.

### 7.2 Allowlist Model (Default Block)
* **Approach**: All international traffic is blocked by default; administrators explicitly permit only authorized service countries (e.g., domestic operating territory + contracted international carrier nodes).
* **Best For**: Regional enterprise PBX networks, government entities, and domestic service providers with no international customer base.

---

## 8. Verification & Diagnostics

### 8.1 Database Rules Inspection
Query active Geo-Firewall rules stored in PostgreSQL:
```bash
sudo -u postgres psql -d sbc_admin -c "
SELECT country_code, country_name, action, hit_count, updated_at 
FROM geo_firewall_rules 
ORDER BY country_name ASC;
"
```

### 8.2 Verify GeoIP Database Integrity
Confirm that the MaxMind GeoIP2 database file is present and readable:
```bash
ls -lh /var/lib/GeoIP/GeoLite2-Country.mmdb
```

### 8.3 Live IP Country Resolution Test
Test how the SBC resolves a specific test IP address using the `mmdblookup` CLI tool:
```bash
mmdblookup --file /var/lib/GeoIP/GeoLite2-Country.mmdb --ip 185.220.101.5 country iso_code
```

Expected output:
```
"DE" <utf8_string>
```

---

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

The **Ring2All SBC MCP Server** exposes specialized sovereign boundary defense tools under the `geofirewall` tool category. Autonomous SecOps agents and the Ring2All SBC NOC Copilot can inspect active geopolitical filters, query hit telemetry, and dynamically impose or lift country-level blocks in response to localized attack spikes.

### 9.1 Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `list_sbc_geofirewall_rules` | Read-only | `read_only` | Lists all country-level geographic firewall rules with country codes, names, action policies (`ALLOW`/`BLOCK`), and hit telemetry. |
| `add_sbc_geofirewall_rule` | Mutating / Operational | `critical` | Creates or updates a geographic filtering policy for a specific country by ISO 3166-1 alpha-2 code. |
| `toggle_sbc_geofirewall_rule` | Mutating / Operational | `operational` | Enables or disables an existing geographic filtering rule by numerical ID or country code. |

### 9.2 Tool Schemas & Parameter Definitions

#### `list_sbc_geofirewall_rules`
* **Description**: List all geographic firewall rules configured in Ring2All SBC with action and telemetry metrics.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {}
}
```

#### `add_sbc_geofirewall_rule`
* **Description**: Add or configure a sovereign country firewall rule.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "countryCode": {
      "type": "string",
      "description": "Two-letter ISO 3166-1 alpha-2 country code (e.g., 'RU', 'CN', 'US')"
    },
    "countryName": {
      "type": "string",
      "description": "Common country name"
    },
    "action": {
      "type": "string",
      "enum": ["ALLOW", "BLOCK"],
      "description": "Filtering verdict to enforce for traffic originating from this country"
    }
  },
  "required": ["countryCode", "action"]
}
```

#### `toggle_sbc_geofirewall_rule`
* **Description**: Enable or disable a geographic firewall rule by ID or ISO country code.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Numerical primary key ID of the geo-firewall rule"
    },
    "countryCode": {
      "type": "string",
      "description": "Two-letter ISO country code (e.g., 'RU')"
    },
    "enabled": {
      "type": "boolean",
      "description": "True to activate the rule; false to disable it"
    }
  },
  "required": ["enabled"]
}
```

### 9.3 Sample Tool Execution Payloads

#### Example 1: Listing Geo-Firewall Rules
**Request Payload:**
```json
{
  "tool": "list_sbc_geofirewall_rules",
  "parameters": {}
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "total": 4,
    "rules": [
      {
        "id": 1,
        "countryCode": "RU",
        "countryName": "Russian Federation",
        "action": "BLOCK",
        "direction": "INBOUND",
        "enabled": true,
        "hitCount": 14208
      },
      {
        "id": 2,
        "countryCode": "CN",
        "countryName": "China",
        "action": "BLOCK",
        "direction": "INBOUND",
        "enabled": true,
        "hitCount": 9831
      },
      {
        "id": 3,
        "countryCode": "US",
        "countryName": "United States",
        "action": "ALLOW",
        "direction": "INBOUND",
        "enabled": true,
        "hitCount": 542910
      }
    ]
  }
}
```

#### Example 2: Blocking Traffic from a High-Risk Country
**Request Payload:**
```json
{
  "tool": "add_sbc_geofirewall_rule",
  "parameters": {
    "countryCode": "IR",
    "countryName": "Iran",
    "action": "BLOCK"
  }
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "message": "Geo-firewall rule for Iran (IR) configured with action BLOCK",
    "rule": {
      "countryCode": "IR",
      "countryName": "Iran",
      "action": "BLOCK",
      "enabled": true
    }
  }
}
```

### 9.4 Bilingual Natural Language Copilot Prompts

#### English Prompts
* *"List all active Geo-Firewall rules and check the hit counts for blocked countries."*
  → Agent calls `list_sbc_geofirewall_rules()`.
* *"Block all SIP traffic originating from country code 'KP' in the Geo-Firewall."*
  → Agent calls `add_sbc_geofirewall_rule({"countryCode": "KP", "countryName": "North Korea", "action": "BLOCK"})`.
* *"Temporarily disable the Geo-Firewall rule for country code 'DE'."*
  → Agent calls `toggle_sbc_geofirewall_rule({"countryCode": "DE", "enabled": false})`.

#### Spanish Prompts (Español)
* *"Lista todas las reglas del Geo-Firewall y revisa los contadores de intentos bloqueados."*
  → Agente invoca `list_sbc_geofirewall_rules()`.
* *"Bloquea todo el tráfico SIP proveniente del código de país 'KP' en el Geo-Firewall."*
  → Agente invoca `add_sbc_geofirewall_rule({"countryCode": "KP", "countryName": "Corea del Norte", "action": "BLOCK"})`.
* *"Deshabilita temporalmente la regla de Geo-Firewall para el código de país 'DE'."*
  → Agente invoca `toggle_sbc_geofirewall_rule({"countryCode": "DE", "enabled": false})`.

### 9.5 Enterprise Security & Execution Safeguards

1. **Domestic Origin Safeguards**: Applying a `BLOCK` action against the operating country where the SBC cluster itself or its primary registered users reside prompts an operational confirmation safeguard to prevent self-lockout.
2. **ISO Code Normalization**: Country codes are automatically uppercased and validated against standard ISO 3166-1 alpha-2 tables before database insertion.
3. **In-Memory Kamailio Sync**: Commits update PostgreSQL immediately and sync with Kamailio's memory lookup caches to ensure instantaneous wire-speed packet filtering.

---

## 10. Glossary

* **ISO 3166-1 alpha-2**: Standardized two-letter country codes representing countries, dependent territories, and special areas of geographical interest.
* **MaxMind GeoIP2**: Leading IP intelligence and geolocation database used to map IP addresses to countries, regions, and autonomous system numbers (ASNs).
* **Sovereign Filtering**: Network security practice of restricting network packet ingress based on the geopolitical and legal jurisdiction of the originating system.
* **Hit Count**: Telemetry counter recording the number of times incoming packets matched and were acted upon by a specific filtering rule.
* **Model Context Protocol (MCP)**: An open standard enabling autonomous AI assistants and NOC copilots to securely discover and invoke SBC operational tools.