Geo-Firewall & Sovereign SIP Traffic Filtering

Overview & Geolocation Architecture
Business & Operational Significance
🎯 User Roles & Key Capabilities
Visual Interface & Layout
Field Reference & Geolocation Filtering Parameters
MaxMind GeoIP2 Integration & In-Memory Lookup
Operational Policy Design: Allowlist vs Blocklist
Verification & Diagnostics
Model Context Protocol (MCP) AI Integration
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

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:

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:

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:

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:

{
  "type": "object",
  "properties": {}
}

`add_sbc_geofirewall_rule`

Description: Add or configure a sovereign country firewall rule.
Input Schema:

{
  "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:

{
  "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:

{
  "tool": "list_sbc_geofirewall_rules",
  "parameters": {}
}

Response Payload:

{
  "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