Hash Tables (HTables)

Table of Contents

1. Overview & In-Memory Key-Value Architecture
2. Business & Operational Significance
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Layout
5. Field Reference & Entry Parameters
6. Kamailio htable Script Mechanics & Syntax
7. Security & Rate Limiting Integration
8. Troubleshooting & Verification
9. Model Context Protocol (MCP) AI Integration
10. Glossary

---

1. Overview & In-Memory Key-Value Architecture

In Ring2All SBC, the Hash Tables (HTables) module provides high-speed, in-memory key-value data structures held directly inside Kamailio shared memory (shm). Powered by the native htable module, HTables enable real-time state caching, atomic counter increments, dynamic time-to-live (TTL) expiration, and perimeter security tracking without querying persistent disk storage or external databases.

Incoming SIP Request (e.g. 192.168.11.199)
                  │
                  ▼
┌────────────────────────────────────────────────────────┐
│               Kamailio Shared Memory (shm)             │
│                                                        │
│   ┌────────────────────────────────────────────────┐   │
│   │ Table: ipban (Auto-expire TTL: 3600s)          │   │
│   │ • 192.168.11.199 => "pike_flood" (TTL: 1420s)  │   │─── Matched -> Drop Immediately (403)
│   │ • 10.200.5.88    => "failed_auth" (TTL: 280s)   │   │
│   └────────────────────────────────────────────────┘   │
│                                                        │
│   ┌────────────────────────────────────────────────┐   │
│   │ Table: reg_throttle (Rate Limiting)            │   │
│   │ • 2000@domain    => 12 attempts (Counter)      │   │─── Exceeded -> Reject (429)
│   └────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────┘

When coupled with the DMQ (Distributed Message Queue) cluster module, HTables automatically synchronize security bans and registration counters across all SBC nodes in real time.

---

2. Business & Operational Significance

• Sub-Millisecond Anti-Flood Drops: Intercepts abusive IP addresses at the earliest possible routing phase, terminating malicious floods before packet processing burdens the CPU.
• Brute-Force & Password Spray Mitigation: Tracks failed SIP REGISTER and INVITE authentication attempts in real time, automatically imposing temporary or permanent bans.
• Per-Subscriber Rate Limiting: Maintains atomic transaction counters for call setup attempts, registration frequencies, and concurrent channels without database lock contention.
• Cluster-Wide Threat Defense: Immediately synchronizes detected attackers across all active SBC cluster nodes via DMQ, ensuring that an attacker blocked on Node 1 cannot probe Node 2.

---

3. 🎯 User Roles & Key Capabilities

Role	Primary Use Case	Key Capabilities
SBC Security Engineer	Threat Remediation & Perimeter Defense	Inspect active IP bans, manually revoke or impose blacklists, and adjust table auto-expiration TTLs.
High-Throughput Dialplan Developer	Stateful Routing Logic	Utilize in-memory hash table pseudovariables ($sht) for atomic counters, quotas, and state caching.
Anti-Fraud Specialist	Registration Abuse Investigation	Audit registration throttle tables, track abnormal credential probe spikes, and analyze attack vectors.
Systems Administrator	Shared Memory Allocation Governance	Monitor hash table bucket sizing, slot utilization, and memory fragmentation via the RPC Console.
AI Security Analyst / SOC Automation Agent	Perimeter Threat Mitigation	Query active IP ban hash tables, inject emergency perimeter blocks, revoke false-positive bans, and reload memory tables via MCP.

---

4. Visual Interface & Layout

The HTables interface displays all active hash tables, key-value mappings, associated expiration timestamps, and cluster replication indicators.

---

5. Field Reference & Entry Parameters

Field Name	Data Type	Default	Description
Table Name	String	ipban	Name of the defined hash table (e.g., ipban, reg_throttle, active_calls).
Key Identifier	String	192.168.11.199	The unique lookup key (e.g., IP address, username, Call-ID, or domain string).
Value / Payload	String / Integer	1	Stored data associated with the key (e.g., ban reason, integer counter, or timestamp).
TTL Remaining	Seconds / Time	3420s	Seconds remaining before the key is automatically purged from memory by Kamailio’s garbage collector.
Auto-Expire Flag	Boolean	true	Indicates whether keys in this table expire automatically according to their configured lifetime.
DMQ Replicate	Boolean	true	Specifies whether updates, additions, or deletions to this entry are broadcast across the DMQ mesh cluster.

---

6. Kamailio htable Script Mechanics & Syntax

In the Kamailio routing script, hash tables are accessed using the $sht(table=>key) pseudovariable family:

# Configuration Definition in kamailio.cfg
modparam("htable", "htable", "ipban=>size=12;autoexpire=3600;dmqreplicate=1")
modparam("htable", "htable", "reg_throttle=>size=10;autoexpire=60")

route[CHECK_PERIMETER_IPBAN] {
    # Check if the source IP address ($si) exists in the ipban table
    if ($sht(ipban=>$si) != $null) {
        xlog("L_WARN", "[HTABLE] Dropping packet from banned IP: $si (Reason: $sht(ipban=>$si))\n");
        sl_send_reply("403", "Forbidden - IP Banned");
        exit;
    }
}

route[RECORD_FAILED_AUTH] {
    # Increment failed attempts counter
    $shtinc(reg_throttle=>$si);
    if ($sht(reg_throttle=>$si) > 5) {
        # Ban IP for 1 hour
        $sht(ipban=>$si) = "Brute Force Threshold Exceeded";
        $shtex(ipban=>$si) = 3600;
        xlog("L_ALERT", "[SECURITY] IP $si banned for 3600s due to failed authentications\n");
    }
}

---

7. Security & Rate Limiting Integration

HTables serve as the real-time cache for multiple perimeter protection modules:

1. Pike Anti-Flood Integration: When Pike detects a packet rate exceeding the threshold (e.g., > 30 requests within 2 seconds), it sets an entry in $sht(ipban=>$si).
2. APIBAN Threat Feed Ingestion: Blacklisted IP addresses ingested from APIBAN are populated directly into HTables for instant, zero-latency rejection.
3. Session Concurrency Guard: Tracks active calls per domain or subscriber, immediately returning SIP 486 Busy Here if a customer exceeds their contracted channel limit.

---

8. Troubleshooting & Verification

Inspecting Table Contents via RPC Console

Dump all keys from the ipban table in the RPC Console:

htable.dump ipban

Output:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "name": "ipban",
      "size": 4096,
      "entries": [
        {
          "key": "192.168.11.199",
          "value": "pike_flood",
          "type": "str",
          "expires": 3412
        }
      ]
    }
  ],
  "id": 1
}

Manually Removing an IP Ban Entry

To unblock a legitimate customer IP address immediately:

htable.delete ipban 192.168.11.199

---

9. Model Context Protocol (MCP) AI Integration

The Hash Tables (HTables) subsystem connects with the Model Context Protocol (MCP) to allow diagnostic and incident-response agents to inspect in-memory tables, dump security ban records, inject temporary blocks, unban whitelisted addresses, and reload memory structures.

Available MCP Tools

Tool Name	Operation Type	Risk Level	Description
list_htables	Status Query	read	List all defined hash tables in Kamailio shared memory with size and auto-expire policies.
get_htable_entries	Content Dump	read	Dump all active key-value entries from a specific hash table (e.g. ipban, reg_throttle).
set_htable_entry	Security Mutation	operational	Set or update a key-value entry in a Kamailio hash table with optional type definition.
delete_htable_entry	Threat Revocation	operational	Remove an entry or unban an IP from a Kamailio hash table immediately.
reload_htables	Operational Reload	operational	Reload a database-backed hash table into Kamailio shared memory via JSON-RPC.

Tool Schemas & Payloads

1. list_htables

Input Schema

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

Output Payload Example

{
  "success": true,
  "data": {
    "totalTables": 3,
    "tables": [
      { "name": "ipban", "size": 4096, "autoexpire": 3600, "dmqreplicate": true },
      { "name": "reg_throttle", "size": 1024, "autoexpire": 60, "dmqreplicate": false },
      { "name": "auth_cache", "size": 2048, "autoexpire": 300, "dmqreplicate": false }
    ]
  }
}

2. get_htable_entries

Input Schema

{
  "type": "object",
  "properties": {
    "table_name": {
      "type": "string",
      "description": "Name of the hash table to dump (e.g. 'ipban')."
    }
  },
  "required": ["table_name"]
}

Output Payload Example

{
  "success": true,
  "data": {
    "tableName": "ipban",
    "totalEntries": 1,
    "entries": [
      {
        "key": "192.168.11.199",
        "value": "pike_flood",
        "type": "str",
        "expires": 3412
      }
    ]
  }
}

3. delete_htable_entry

Input Schema

{
  "type": "object",
  "properties": {
    "table_name": {
      "type": "string",
      "description": "Target hash table (e.g. 'ipban')."
    },
    "key": {
      "type": "string",
      "description": "Key or IP to remove from the table (e.g. '192.168.11.199')."
    }
  },
  "required": ["table_name", "key"]
}

Output Payload Example

{
  "success": true,
  "data": {
    "message": "Key '192.168.11.199' deleted successfully from table 'ipban'.",
    "rpc_response": "OK"
  }
}

Natural Language AI Prompts

English Examples

• “Dump all banned IP addresses currently stored in the ‘ipban’ hash table.”
• “Unban IP address ‘192.168.11.199’ by deleting its entry from the ‘ipban’ table.”
• “List all Kamailio in-memory hash tables and their bucket configurations.”

Spanish Examples (Español)

• “Vuelca todas las direcciones IP bloqueadas actualmente en la tabla hash ‘ipban’.”
• “Desbloquea la dirección IP ‘192.168.11.199’ eliminando su entrada de la tabla ‘ipban’.”
• “Lista todas las tablas hash en memoria de Kamailio y sus configuraciones de buckets.”

Enterprise Safeguards & Access Governance

1. Immediate Cluster Propagation: Entry deletions in DMQ-enabled tables are propagated across the cluster to avoid inconsistent state between SBC nodes.
2. Type Safety Clamping: Entry value types (str or int) are explicitly validated prior to JSON-RPC dispatch.
3. Role Segregation: Unbanning IPs or mutating security tables requires noc_network_engineer or sbc_system_admin privileges.

---

10. Glossary

• HTable (Hash Table): An associative array data structure that stores key-value pairs in memory for $O(1)$ constant-time lookup performance.
• TTL (Time-To-Live): A timer mechanism that automatically deletes an entry from memory after a predetermined duration.
• Atomic Increment ($shtinc): A thread-safe operation that increases an integer counter without risk of race conditions between worker processes.
• DMQ Replication: Automatic synchronization of hash table keys, values, and expiration timers across multiple SBC nodes.