---
title: "Access Control & IP Ban Management"
description: "Documentation for Access Control (IP Bans)"
---

## Table of Contents
1. [Overview & Perimeter Enforcement](#1-overview--perimeter-enforcement)
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 & Access Control Parameters](#5-field-reference--access-control-parameters)
6. [Multi-Source Ingestion & Enforcement Pipeline](#6-multi-source-ingestion--enforcement-pipeline)
7. [Ban Lifecycle & Expiration Governance](#7-ban-lifecycle--expiration-governance)
8. [Operational Best Practices](#8-operational-best-practices)
9. [Verification & Diagnostics](#9-verification--diagnostics)
10. [Model Context Protocol (MCP) AI Integration](#10-model-context-protocol-mcp-ai-integration)
11. [Glossary](#11-glossary)

---

## 1. Overview & Perimeter Enforcement

In **Ring2All SBC**, the **Access Control** module (IP Bans) serves as the unified operational clearinghouse for all blocked IP addresses across the perimeter. Hostile hosts blocked by dynamic subsystems—including the **AI Perimeter Guard**, **Pike Anti-Flood**, **Fail2Ban**, **VoIPBL Public Blacklists**, or manual administrative intervention—are aggregated, tracked, and synchronized across both application memory and operating system packet filters.

```
       ┌─────────────────────────────────────────────────────────────┐
       │             ACCESS CONTROL AGGREGATION PIPELINE             │
       │                   (Table: sbc_admin.ip_bans)                │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
           ┌──────────────┬───────────┼───────────┬──────────────┐
           ▼              ▼           ▼           ▼              ▼
       ┌────────┐    ┌─────────┐ ┌─────────┐ ┌─────────┐    ┌─────────┐
       │  PIKE  │    │ AI SCAN │ │ FAIL2BAN│ │ VOIPBL  │    │ MANUAL  │
       │ (Flood)│    │(Entropy)│ │ (Login) │ │ (Feeds) │    │ (SecOps)│
       └────────┘    └─────────┘ └─────────┘ └─────────┘    └─────────┘
           │              │           │           │              │
           └──────────────┴───────────┼───────────┴──────────────┘
                                      │
                                      ▼
       ┌─────────────────────────────────────────────────────────────┐
       │                 DUAL-LAYER REAL-TIME ENFORCEMENT            │
       ├──────────────────────────────┬──────────────────────────────┤
       │ KAMAILIO SHARED MEMORY       │ LINUX KERNEL PACKET FILTER   │
       │  • sht(ipban=>$si) drop;     │  • nftables set sbc_bans     │
       │  • Zero SQL lookup penalty   │  • Wire-speed kernel drop    │
       └──────────────────────────────┴──────────────────────────────┘
```

By unifying all banned sources into a single operational interface, network engineers and security analysts gain instantaneous visibility into blocked IP addresses, the exact detection mechanism that triggered the ban, remaining lease durations, and the ability to immediately restore service to legitimate carriers.

---

## 2. Business & Operational Significance

* **Rapid Carrier Unblocking**: When a trusted carrier or client PBX triggers a false-positive ban due to temporary misconfiguration, engineers can locate and release the IP in seconds without touching Linux command lines.
* **Unified Threat Visibility**: Consolidates alerts from disparate security engines (Pike, Fail2Ban, AI heuristics) into a single auditable interface with consistent taxonomy and expiration rules.
* **Dual-Layer Kernel & SIP Enforcement**: Synchronizes bans across both Linux kernel `nftables` sets (dropping layer-3/4 packets) and Kamailio memory `htable` registers (terminating layer-7 SIP attempts).
* **Automated Expiration & Self-Pruning**: Automatically transitions temporary bans to expired statuses, preventing routing tables and memory caches from growing unbounded over time.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **NOC Support Engineer** | Carrier Incident Resolution | Search blocked IPs by subnet, inspect detection reasons, and trigger immediate unbans for trusted partners. |
| **SecOps Security Analyst** | Perimeter Threat Hunting | Impose permanent manual IP bans, review detection sources, and trigger Fail2Ban synchronization. |
| **SBC Administrator** | Firewall Policy Enforcement | Push bulk rule synchronizations, execute expired ban purges, and verify active kernel set contents. |
| **Compliance Auditor** | Regulatory Ban Tracking | Export ban journals with timestamps, original source attributions, and administrative operator tags. |
| **AI Security Enforcement Agent / NOC Copilot** | Autonomous Perimeter Blacklisting & Triage | Enforce immediate IP bans, query active blacklist status across Kamailio and database layers, and execute verified unban actions via MCP. |

---

## 4. Visual Interface & Layout

The Access Control interface consists of a high-density DataGrid featuring source badges, countdown expiration timers, operational search tools, and bulk rule controls.

### 4.1 Access Control List View
Displays active IP bans, detection sources, human-readable rationale, ban timestamps, expiration deadlines, and quick-action tools.

![Access Control List View](/screenshots/sbc/admin/access-control/access-control-list.png)

---

## 5. Field Reference & Access Control Parameters

| Field | Type | Constraint | Description |
| :--- | :--- | :--- | :--- |
| **IP Address** | String (IPv4/IPv6) | Primary Key | The IPv4 or IPv6 address blocked from accessing SBC signaling and administrative ports. |
| **Source** | Badge | Enumerated | The subsystem responsible for initiating the ban: `PIKE`, `SCAN`, `MANUAL`, `FAIL2BAN`, `VOIPBL`, `IRSF`, `VELOCITY`, `ADMIN`. |
| **Name / Reason** | Text String | Required | Diagnostic explanation of the ban (e.g., *Exceeded SIP INVITE rate threshold*, *Manual security ban by SecOps*). |
| **Banned Date** | Timestamp | Auto-Generated | The exact date and time when the ban was recorded in the database. |
| **Expires On** | Timestamp / ∞ | Nullable | The scheduled expiration date and time, or `Permanent` (infinity) if created manually without a lease. |
| **Status** | Badge | Active / Expired | Indicates whether the ban is currently actively enforced in memory and kernel sets. |
| **Actions** | Action Icons | Edit / Delete | Controls to adjust ban rationale/expiration or immediately unban the IP. |

---

## 6. Multi-Source Ingestion & Enforcement Pipeline

The Access Control engine ingests bans from multiple native subsystems into the `sbc_admin.ip_bans` table:

```sql
INSERT INTO ip_bans (ip_address, banned_at, expires_at, reason, source, banned_by, is_active)
VALUES ('198.51.100.45', NOW(), NOW() + INTERVAL '24 HOURS', 'Exceeded SIP INVITE rate threshold (Pike)', 'pike', 'system', TRUE)
ON CONFLICT (ip_address) DO UPDATE 
SET expires_at = EXCLUDED.expires_at, is_active = TRUE;
```

### 6.1 Toolbar Action Commands

* **Sync Fail2Ban**: Scans active Fail2Ban jail states on the local host and ingests newly identified brute-force IPs into the central database.
* **Apply Rules**: Re-syncs all active database records into Kamailio's memory `htable:ipban` and the Linux kernel's `nftables set sbc_bans`.
* **Clear Expired**: Purges all bans whose `expires_at` timestamp is earlier than the current system time (`NOW()`), unblocking them across all enforcement layers.
* **+ Add**: Opens the manual ban dialogue allowing operators to add single IP addresses or CIDR blocks with customizable expiration leases.

---

## 7. Ban Lifecycle & Expiration Governance

Bans in Ring2All SBC progress through a predictable lifecycle:

1. **Detection & Commitment**: Offending IP triggers a security subsystem (e.g., Pike rate threshold breach).
2. **Dual-Layer Registration**: Record is inserted into `ip_bans` and pushed to `htable:ipban` and `nftables`.
3. **Active Enforcement**: Packets from the IP are silently discarded or rejected with SIP 403 Forbidden.
4. **Expiration / Manual Release**: Upon reaching `expires_at` or manual deletion by an administrator:
   - Kamailio RPC: `kamcmd htable.delete ipban <ip>`
   - Linux Kernel: `nft delete element inet filter sbc_bans { <ip> }`
   - Database: `UPDATE ip_bans SET is_active = FALSE WHERE ip_address = '<ip>'`

---

## 8. Operational Best Practices

* **Audit Before Unbanning**: Always inspect the `Source` badge and `Reason` before unbanning an IP. An IP banned by `SCAN` or `IRSF` poses significantly higher threat risk than one temporarily throttled by `PIKE`.
* **Set Expirations for Manual Bans**: When manually banning external addresses, prefer setting an expiration lease (e.g., 7 days) rather than permanent, preventing dead configuration accumulation.
* **Avoid Banning Gateway Subnets**: Never manually ban broad subnets (e.g., `/24`) without verifying that no legitimate wholesale carrier interconnects reside within the CIDR block.
* **Regular Expired Ban Pruning**: Schedule automated cleanup jobs or periodically click **Clear Expired** to keep database tables and memory sets lean.

---

## 9. Verification & Diagnostics

### 9.1 Query Active Bans via Database
Inspect all active bans and remaining durations:
```bash
sudo -u postgres psql -d sbc_admin -c "
SELECT ip_address, source, reason, banned_at, expires_at, is_active 
FROM ip_bans 
WHERE is_active = TRUE 
ORDER BY banned_at DESC;
"
```

### 9.2 Verify Live Kamailio Enforcement
Check if an IP is actively present in Kamailio's in-memory ban table:
```bash
kamcmd htable.get ipban "198.51.100.45"
```

### 9.3 Verify Linux Kernel Block
Verify that the IP is registered in the kernel nftables set:
```bash
nft list set inet filter sbc_bans | grep "198.51.100.45"
```

---

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

The **Ring2All SBC MCP Server** exposes dedicated operational access control and blacklist management tools under the `access_control_bans` and `security` tool categories. These tools enable autonomous security agents and the Ring2All SBC NOC Copilot to inspect active perimeter bans, impose immediate blocks against malicious sources, and remove bans for legitimate traffic.

### 10.1 Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `get_banned_ips` | Read-only | `read_only` | Lists and counts all IP addresses currently blocked in Kamailio anti-flood (`pike`), threat intelligence (`apiban`), or all tables. |
| `ban_sbc_ip_address` | Mutating / Defensive | `critical` | Immediately registers a manual IP ban in the PostgreSQL `ip_bans` table and commits it to the active Kamailio `ipban` memory table. |
| `unban_ip_address` | Mutating / Operational | `critical` | Removes a blocked IP address from Kamailio's in-memory ban tables and updates database audit state. |

### 10.2 Tool Schemas & Parameter Definitions

#### `get_banned_ips`
* **Description**: List and count all IP addresses currently blocked by Kamailio anti-flood (Pike) and APIBAN threat intelligence htables.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "table": {
      "type": "string",
      "enum": ["all", "pike", "apiban"],
      "description": "Filter by protection table: 'pike' (rate limits), 'apiban' (global threat intelligence), or 'all' (default)"
    }
  }
}
```

#### `ban_sbc_ip_address`
* **Description**: Immediately ban an IP address across Kamailio memory htable and database access control records.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "ipAddress": {
      "type": "string",
      "description": "The IPv4 or IPv6 address to ban (e.g., '198.51.100.45')"
    },
    "reason": {
      "type": "string",
      "description": "Operational rationale or incident identifier explaining the ban"
    },
    "expiresHours": {
      "type": "number",
      "description": "Optional ban duration in hours (e.g., 24 for 1 day, 168 for 1 week). If omitted, ban is permanent."
    }
  },
  "required": ["ipAddress", "reason"]
}
```

#### `unban_ip_address`
* **Description**: Unblock a banned IP address from the Kamailio security table immediately.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "ipAddress": {
      "type": "string",
      "description": "The IP address to remove from the ban table (e.g., '198.51.100.45')"
    },
    "reason": {
      "type": "string",
      "description": "Reason for unbanning the IP"
    }
  },
  "required": ["ipAddress"]
}
```

### 10.3 Sample Tool Execution Payloads

#### Example 1: Listing All Banned IPs
**Request Payload:**
```json
{
  "tool": "get_banned_ips",
  "parameters": {
    "table": "all"
  }
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "totalBanned": 3,
    "bans": [
      { "ip": "198.51.100.45", "table": "pike", "expires": "2026-09-09T11:45:00Z" },
      { "ip": "203.0.113.88", "table": "apiban", "expires": "2026-09-15T00:00:00Z" },
      { "ip": "185.220.101.5", "table": "ipban", "expires": "permanent" }
    ]
  }
}
```

#### Example 2: Banning an Offending IP Address
**Request Payload:**
```json
{
  "tool": "ban_sbc_ip_address",
  "parameters": {
    "ipAddress": "198.51.100.45",
    "reason": "Repeated SIP scanning attempts detected on port 5060",
    "expiresHours": 24
  }
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "message": "IP 198.51.100.45 banned successfully",
    "ipAddress": "198.51.100.45",
    "expiresAt": "2026-09-09T11:52:00Z",
    "kamailioSync": "ok"
  }
}
```

### 10.4 Bilingual Natural Language Copilot Prompts

#### English Prompts
* *"Show me all IP addresses currently banned by the anti-flood and threat intelligence engines."*
  → Agent calls `get_banned_ips({"table": "all"})`.
* *"Ban IP 198.51.100.45 for 48 hours because of persistent brute-force registration probes."*
  → Agent calls `ban_sbc_ip_address({"ipAddress": "198.51.100.45", "reason": "Persistent brute-force registration probes", "expiresHours": 48})`.
* *"Unban carrier IP 192.0.2.10 immediately because the customer resolved their PBX configuration."*
  → Agent calls `unban_ip_address({"ipAddress": "192.0.2.10", "reason": "Customer resolved PBX configuration"})`.

#### Spanish Prompts (Español)
* *"Muéstrame todas las IPs bloqueadas actualmente en el SBC por anti-flood o listas de amenazas."*
  → Agente invoca `get_banned_ips({"table": "all"})`.
* *"Bloquea la IP 198.51.100.45 durante 48 horas por escaneos masivos en el puerto 5060."*
  → Agente invoca `ban_sbc_ip_address({"ipAddress": "198.51.100.45", "reason": "Escaneos masivos en puerto 5060", "expiresHours": 48})`.
* *"Desbloquea la IP 192.0.2.10 de inmediato ya que el cliente corrigió la configuración de su PBX."*
  → Agente invoca `unban_ip_address({"ipAddress": "192.0.2.10", "reason": "Cliente corrigió configuración PBX"})`.

### 10.5 Enterprise Security & Execution Safeguards

1. **Dual-Layer Synchronization**: `ban_sbc_ip_address` writes to PostgreSQL and dispatches `kamcmd htable.sets ipban <ip> 1` within 3000ms timeout limits to ensure zero lag between database and signaling threads.
2. **Whitelist Cross-Verification**: Before committing a ban, the engine verifies the IP does not match registered trusted carrier endpoints or internal management subnets (`127.0.0.1/32`, RFC 1918).
3. **Audit Trail Logging**: Unban and ban executions require mandatory reason strings which are permanently logged into the administrative audit trail alongside operator session metadata.

---

## 11. Glossary

* **Fail2Ban**: Host-level log parsing daemon that executes firewall actions against IP addresses exhibiting brute-force behavior.
* **Pike**: Kamailio module that tracks request rates per IP over sliding time windows to mitigate denial-of-service and high-frequency SIP floods.
* **htable (ipban)**: High-speed in-memory hash table used by Kamailio to drop packets from blacklisted addresses in zero clock cycles without querying PostgreSQL.
* **nftables Set**: Highly optimized kernel-level data structure designed for ultra-fast lookup and packet filtering of thousands of IP addresses.
* **Model Context Protocol (MCP)**: An open standard enabling autonomous AI assistants and NOC copilots to securely discover and invoke SBC operational tools.