Access Control & IP Ban Management

Overview & Perimeter Enforcement
Business & Operational Significance
🎯 User Roles & Key Capabilities
Visual Interface & Layout
Field Reference & Access Control Parameters
Multi-Source Ingestion & Enforcement Pipeline
Ban Lifecycle & Expiration Governance
Operational Best Practices
Verification & Diagnostics
Model Context Protocol (MCP) AI Integration
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

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:

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;

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:

Detection & Commitment: Offending IP triggers a security subsystem (e.g., Pike rate threshold breach).
Dual-Layer Registration: Record is inserted into ip_bans and pushed to htable:ipban and nftables.
Active Enforcement: Packets from the IP are silently discarded or rejected with SIP 403 Forbidden.
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:

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:

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:

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:

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

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

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

{
  "tool": "get_banned_ips",
  "parameters": {
    "table": "all"
  }
}

Response Payload:

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