Anti-Flood Protection & Rate Limiting (Pike)

Overview & Traffic Shaping Architecture
Business & Operational Significance
🎯 User Roles & Key Capabilities
Visual Interface & Layout
Pike Heuristic Parameters & Sliding Window Math
Rate Limit Exceptions (CPS Tuning)
Kamailio Integration & RPC Management
Operational Best Practices & Anti-DoS Hardening
Verification & Diagnostics
Model Context Protocol (MCP) AI Integration
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

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:
Terminal window
```
kamcmd pike.top_list 50
```
Manually Unblock an IP:
Terminal window
```
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:

kamcmd pike.top_list 20

9.2 Inspect Rate Limit Exceptions in PostgreSQL

Query all configured CPS rate limit exceptions in kamailio.address:

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:

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:

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

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

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

{
  "tool": "get_sbc_pike_status",
  "parameters": {}
}

Response Payload:

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