---
title: "Anti-Flood Protection & Rate Limiting (Pike)"
description: "Documentation for Anti-flood & Rate Limiting (Pike)"
---

## Table of Contents
1. [Overview & Traffic Shaping Architecture](#1-overview--traffic-shaping-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. [Pike Heuristic Parameters & Sliding Window Math](#5-pike-heuristic-parameters--sliding-window-math)
6. [Rate Limit Exceptions (CPS Tuning)](#6-rate-limit-exceptions-cps-tuning)
7. [Kamailio Integration & RPC Management](#7-kamailio-integration--rpc-management)
8. [Operational Best Practices & Anti-DoS Hardening](#8-operational-best-practices--anti-dos-hardening)
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 & Traffic Shaping Architecture

In **Ring2All SBC**, the **Anti-flood / Pike** module provides automated protection against high-velocity SIP floods, volumetric denial-of-service (DoS) attacks, and rogue user agents attempting registration or call brute-forcing. Driven by Kamailio's native **pike** module and shared memory hash tables, the engine maintains dynamic moving-window request counters per source IP address in kernel-adjacent memory.

```
       ┌─────────────────────────────────────────────────────────────┐
       │                 INCOMING SIP TRAFFIC STREAM                 │
       │                   (INVITE, REGISTER, OPTIONS)               │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
       ┌──────────────────────────────▼──────────────────────────────┐
       │              PIKE SLIDING WINDOW EVALUATION                 │
       │    (sampling_time_unit: 2s | reqs_density_per_unit: 16)     │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
              ┌───────────────────────┴───────────────────────┐
              ▼ (Density <= 16 reqs / 2s)                     ▼ (Density > 16 reqs / 2s)
       ┌──────────────────────────────┐                ┌──────────────────────────────┐
       │       NORMAL TRAFFIC         │                │     FLOOD THRESHOLD BREACH   │
       ├──────────────────────────────┤                ├──────────────────────────────┤
       │ • Check Rate Limit Exception │                │ • Check Group 9 CPS Override │
       │ • Proceed to SIP routing     │                │ • If exceeded: AUTO-BLOCK IP │
       │ • Forward to Core PBX/Trunk  │                │ • Add to pike.top_list table │
       └──────────────────────────────┘                └──────────────────────────────┘
                                                              │
                                                              ▼
                                               ┌──────────────────────────────┐
                                               │      SILENT PACKET DROP      │
                                               │ (drop; during remove_latency)│
                                               └──────────────────────────────┘
```

When an unpeered source IP exceeds the allowable request density, the Pike engine transitions the IP to a temporary blocked state, silently dropping subsequent packets for the duration of the cooldown window without consuming CPU or generating SIP rejection traffic that could amplify the attack.

---

## 2. Business & Operational Significance

* **Autonomous Denial-of-Service Defense**: Defends SIP signaling ports from volumetric INVITE or REGISTER floods that would otherwise saturate Kamailio worker processes and exhaust database connection pools.
* **Granular Carrier CPS Exceptions**: Allows wholesale carriers and high-capacity PSTN trunks to operate at elevated rates (e.g., 50 or 100 CPS) through explicit rate limit exception rules while maintaining strict limits on untrusted sources.
* **Amplification Attack Mitigation**: Silently discards offending packets with `drop;` rather than sending SIP 4xx/5xx responses, preventing the SBC from acting as a reflector in spoofed-IP reflection attacks.
* **Real-Time RPC Telemetry & Unbanning**: Provides operators with live inspection of currently blocked IPs via Kamailio's binary RPC interface (`pike.top_list`), enabling instant, one-click manual unbanning.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **SBC Security Administrator** | Volumetric Flood Defense | Review Pike live blocked IPs, inspect request densities, calibrate `kamailio.cfg` parameters, and execute manual IP releases. |
| **Carrier Interconnect Engineer** | Trunk CPS Capacity Provisioning | Author rate limit exceptions for wholesale carrier gateways, assigning custom Max CPS thresholds to prevent inadvertent carrier throttling. |
| **NOC Systems Operator** | Real-Time DoS Monitoring | Monitor active blocked host lists during traffic spikes and verify recovery following network attacks. |
| **Compliance & Performance Auditor** | Service Level Governance | Ensure DDoS mitigation mechanisms comply with telecom service-level agreements (SLAs) without impacting legitimate call completion rates. |
| **AI Anti-Flood & Rate Limiting Agent / NOC Copilot** | Volumetric DoS Inspection & Rapid Unblocking | Inspect live Pike request velocities, query memory ban lists, audit carrier CPS limits, and execute verified unban actions via MCP. |

---

## 4. Visual Interface & Layout

The Anti-flood Protection interface provides real-time RPC monitoring of active blocked hosts, a configuration dialogue for carrier CPS rate limit exceptions, and a configuration reference guide.

### 4.1 Anti-flood Protection & Rate Limiting View
Displays Pike blocked IPs, active carrier CPS exceptions (e.g., Tier 1 Wholesale Carrier at 50 CPS, Core PBX Cluster at 100 CPS), and `kamailio.cfg` parameter references.

![Anti-flood Protection View](/screenshots/sbc/admin/antiflood-pike/antiflood-pike.png)

---

## 5. Pike Heuristic Parameters & Sliding Window Math

Pike evaluates incoming SIP request velocity using three core configuration parameters:

```
modparam("pike", "sampling_time_unit", 2)
modparam("pike", "reqs_density_per_unit", 16)
modparam("pike", "remove_latency", 4)
```

### 5.1 Parameter Definitions & Impact

| Parameter | Default | Unit | Description |
| :--- | :--- | :--- | :--- |
| **`sampling_time_unit`** | `2` | Seconds | The time interval over which incoming requests from a single IP address are aggregated into a density bucket. |
| **`reqs_density_per_unit`**| `16` | Requests | The maximum number of requests allowed within the `sampling_time_unit` before an IP is marked as a flood source (~8 CPS). |
| **`remove_latency`** | `4` | Seconds | The cooldown window during which an IP remains blocked. If new packets arrive during this window, the cooldown timer resets. |

### 5.2 Mathematical Evaluation Formula
An IP is blocked when:
$$\text{Request Density} > \frac{\text{reqs\_density\_per\_unit}}{\text{sampling\_time\_unit}} = \frac{16 \text{ requests}}{2 \text{ seconds}} = 8 \text{ CPS}$$

---

## 6. Rate Limit Exceptions (CPS Tuning)

Wholesale carrier interconnects, high-volume call centers, and core PBX nodes naturally exceed default consumer rate limits (8 CPS). To prevent false-positive blocks, administrators create **Rate Limit Exceptions**:

| Field | Type | Example | Description |
| :--- | :--- | :--- | :--- |
| **IP Address** | String (IPv4) | `198.51.100.20` | The static IP address of the trusted wholesale gateway or core PBX node. |
| **Max CPS** | Number | `50` | Maximum allowable Calls-Per-Second threshold before traffic throttling is considered. |
| **Operational Tag** | String | `cps:50 (Tier 1 Wholesale)` | Internal metadata stored in `kamailio.address` (Group 9) informing the routing logic of the elevated threshold. |

---

## 7. Kamailio Integration & RPC Management

Pike evaluation is embedded in the initial request routing block of `kamailio.cfg`:

```
route[PIKE_CHECK] {
    # 1. Skip Pike for trusted addresses in Group 9 (Custom CPS handled separately)
    if (check_source_address("9")) {
        return;
    }

    # 2. Evaluate Pike density
    if (!pike_check_req()) {
        xlog("L_ALERT", "PIKE: High traffic flood detected from $si - dropping packet\n");
        drop;
    }
}
```

### 7.1 Real-Time RPC Commands

* **List Blocked Hosts**:
  ```bash
  kamcmd pike.top_list 50
  ```
* **Manually Unblock an IP**:
  ```bash
  kamcmd pike.unblock_ip "198.51.100.45"
  ```

---

## 8. Operational Best Practices & Anti-DoS Hardening

* **Always Whitelist Core PBX Clusters**: Ensure that all Telephony Server media and signaling nodes are registered in the **Rate Limit Exceptions** table with generous CPS allowances (>=100 CPS) to prevent internal cluster traffic from triggering flood filters.
* **Calibrate for SIP Registration Bursts**: In deployments serving large numbers of remote desk phones or softphones, power outages or network reconnects can cause thousands of simultaneous REGISTER messages. Keep `reqs_density_per_unit` calibrated accordingly.
* **Combine Pike with Kernel nftables**: For sustained volumetric attacks exceeding 50,000 packets per second, ensure the AI Perimeter Guard or Fail2Ban pushes the offending IP down to the kernel `nftables` level to spare userspace CPU cycles.
* **Avoid Sending SIP 503 or 403 Replies to Flooders**: Always use `drop;` in Kamailio routing logic when `pike_check_req()` fails; responding to thousands of malicious packets per second doubles outbound bandwidth consumption.

---

## 9. Verification & Diagnostics

### 9.1 Query Live Pike Blocked Hosts via CLI
Inspect the live top list of IPs currently flagged or throttled by Pike:
```bash
kamcmd pike.top_list 20
```

### 9.2 Inspect Rate Limit Exceptions in PostgreSQL
Query all configured CPS rate limit exceptions in `kamailio.address`:
```bash
sudo -u postgres psql -d kamailio -c "
SELECT id, ip_addr, mask, port, tag 
FROM address 
WHERE grp = 9 
ORDER BY id ASC;
"
```

### 9.3 Test Manual Unblock Execution
Test clearing a specific IP from Pike's memory table:
```bash
kamcmd pike.unblock_ip "198.51.100.20"
```

---

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

The **Ring2All SBC MCP Server** exposes dedicated volumetric defense and anti-flood tools under the `antiflood_pike` and `security` categories. Autonomous SecOps agents and the Ring2All SBC NOC Copilot can inspect real-time request density metrics, identify top traffic generators, and quickly release legitimate IP addresses accidentally throttled during sudden call surges.

### 10.1 Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `get_sbc_pike_status` | Read-only | `read_only` | Retrieves the real-time operational status of the Kamailio Pike engine, including sliding window settings, active memory ban counts, and top flagged IP entries. |
| `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. |
| `unban_ip_address` | Mutating / Operational | `critical` | Immediately unblocks a throttled IP address from Kamailio's memory tables and restores SIP traffic processing. |

### 10.2 Tool Schemas & Parameter Definitions

#### `get_sbc_pike_status`
* **Description**: Get live Kamailio Pike anti-flood engine status, current request density metrics, and blocked IP records.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {}
}
```

#### `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)"
    }
  }
}
```

#### `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: Querying Pike Status & Memory Ban Counts
**Request Payload:**
```json
{
  "tool": "get_sbc_pike_status",
  "parameters": {}
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "module": "pike",
    "status": "operational",
    "samplingTimeUnitSec": 2,
    "reqsDensityPerUnit": 16,
    "removeLatencySec": 4,
    "activePikeBans": 3,
    "topOffenders": [
      { "ip": "198.51.100.45", "hits": 48 },
      { "ip": "203.0.113.19", "hits": 34 }
    ]
  }
}
```

#### Example 2: Releasing an Accidental Carrier Ban
**Request Payload:**
```json
{
  "tool": "unban_ip_address",
  "parameters": {
    "ipAddress": "198.51.100.45",
    "reason": "Carrier burst completed; legitimate high-volume traffic"
  }
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "message": "IP 198.51.100.45 unbanned successfully from Kamailio tables",
    "ipAddress": "198.51.100.45",
    "unbannedAt": "2026-09-08T11:54:00Z"
  }
}
```

### 10.4 Bilingual Natural Language Copilot Prompts

#### English Prompts
* *"Check the status of the Pike anti-flood engine and show me any IPs currently being throttled."*
  → Agent calls `get_sbc_pike_status()`.
* *"Show all IP addresses currently blocked by the Pike module."*
  → Agent calls `get_banned_ips({"table": "pike"})`.
* *"Unban carrier IP 198.51.100.45 because they experienced a temporary marketing campaign burst."*
  → Agent calls `unban_ip_address({"ipAddress": "198.51.100.45", "reason": "Marketing campaign traffic burst"})`.

#### Spanish Prompts (Español)
* *"Revisa el estado del motor anti-flood Pike y muéstrame las IPs que están siendo limitadas."*
  → Agente invoca `get_sbc_pike_status()`.
* *"Muéstrame todas las direcciones IP bloqueadas por el módulo Pike."*
  → Agente invoca `get_banned_ips({"table": "pike"})`.
* *"Desbloquea la IP del carrier 198.51.100.45 debido a una ráfaga legítima de tráfico."*
  → Agente invoca `unban_ip_address({"ipAddress": "198.51.100.45", "reason": "Ráfaga legítima de tráfico"})`.

### 10.5 Enterprise Security & Execution Safeguards

1. **Microsecond Binary RPC**: Pike inspections execute via `/var/run/kamailio/kamailio_ctl` binary RPC with strict 3000ms timeouts, avoiding kernel lock contention during active volumetric floods.
2. **Wholesale Exception Verification**: Before an operator or agent unbans an IP repeatedly flagged by Pike, the copilot recommends adding the host to Group 9 (`kamailio.address`) with a calibrated Max CPS threshold.
3. **Audit Journaling**: Manual unbans through `unban_ip_address` require mandatory operational justification strings and are committed to the security audit log.

---

## 11. Glossary

* **Pike**: Native Kamailio traffic-shaping module designed to detect and block IP addresses generating abnormal request velocity.
* **CPS (Calls Per Second)**: Telecommunications metric quantifying the rate of new call setups initiated per second across a trunk or interface.
* **Sliding Window**: Algorithmic technique that evaluates incoming event frequency over moving, overlapping time intervals rather than static clock boundaries.
* **Silent Drop (`drop;`)**: Discarding a network packet without sending an ICMP unreachable or SIP error response back to the originator.
* **Model Context Protocol (MCP)**: An open standard enabling autonomous AI assistants and NOC copilots to securely discover and invoke SBC operational tools.