---
title: "AI Telephony Guard & PBX Shield Documentation"
description: "Documentation for AI Telephony Guard"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [User Roles & Key Capabilities](#-user-roles--key-capabilities)
4. [Overview & Defense Architecture](#1-overview--defense-architecture)
5. [Threat Vectors Mitigated](#2-threat-vectors-mitigated)
6. [Real-Time Telemetry & Heuristic Engine](#3-real-time-telemetry--heuristic-engine)
7. [Community Threat Intelligence (APIBAN & VoIPBL)](#4-community-threat-intelligence-apiban--voipbl)
8. [Configuration & Sensitivity Thresholds](#5-configuration--sensitivity-thresholds)
9. [Incidents, Blacklists & Manual Unblocking](#6-incidents-blacklists--manual-unblocking)
10. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
11. [Glossary](#7-glossary)

---

## Navigation & Access

To access the AI Telephony Guard module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`) with administrative credentials.
2. In the left navigation sidebar, locate and expand **Admin**.
3. Under the **Firewall** section, click **AI Telephony Guard** (`/admin/firewall/ai-guard`).
4. Review real-time KPIs, 24-hour voice quality trends (MoS), financial toll fraud defenses, and active quarantine statuses across tabs:
   - **Threat Overview**: Live telemetry, estimated cost protected, active threat score breakdown, and quarantine status.
   - **Incident Log**: Chronological incident records, attack vectors (toll fraud, SIP floods, credential stuffing), threat probability scores, and quarantine/resolve actions.
   - **Voice Quality (MoS)**: Mean Opinion Score degradation monitoring and telemetry triggers.
   - **Voice AI Safety**: Token exhaustion and synthetic loop defense controls.
   - **Guard Settings**: Heuristic thresholds, automatic quarantine timers, and notification webhooks.

---

## Screenshots & Visual Interface

### AI Telephony Guard Threat Overview
The Threat Overview dashboard presents unified situational awareness: real-time calls analyzed over ESL, toll threats neutralized, estimated financial loss protected, average Mean Opinion Score (MoS) metrics, 24-hour activity trends, and quarantine engine states.
![AI Telephony Guard Threat Overview](/screenshots/admin/firewall/ai-telephony-guard-overview.png)

### Incident Log & Threat Quarantine
The Incident Log provides detailed forensic visibility into security anomalies flagged by heuristic models, showing severity levels (`CRITICAL`, `HIGH`, `MEDIUM`), attack types, targeted extension IDs, source IPs, calculated threat scores, and instant isolation actions.
![AI Telephony Guard Incident Log](/screenshots/admin/firewall/ai-telephony-guard-incidents.png)

---

## 🎯 User Roles & Key Capabilities

The AI Telephony Guard orchestrates automated IPS heuristics and voice security monitoring across key platform roles:

| User Role | Key Permissions & Responsibilities | Common Tasks & Workflows |
|:---|:---|:---|
| **CISO / Head of Information Security** | Master policy ownership of real-time PBX intrusion prevention, toll fraud protection, and AI voice safety rules. | Establish toll fraud loss thresholds, approve automated extension quarantine timers, review 24-hour threat score trends, verify SOC incident response procedures. |
| **Fraud & Telephony Security Analyst** | Investigating flagged anomalies, analyzing attack vectors, and managing quarantine lifecycles. | Review incident forensics (source IP, targeted extension, attack classification), execute instant quarantine on compromised endpoints, clear false-positive locks. |
| **VoIP / Network Quality Engineer** | Monitoring voice telemetry, Mean Opinion Score (MoS) trends, and Kamailio Pike packet flood rates. | Inspect call quality degradation alerts, calibrate token-bucket rate limits on SIP INVITE traffic, analyze audio packet loss and jitter telemetry. |
| **Tenant Administrator** | Scoped organizational visibility into security alerts and quarantined employee extensions. | Inspect why an extension was placed in quarantine, submit verification tickets to unblock remote agents, ensure employees adhere to strong SIP credential standards. |

---

## 1. Overview & Defense Architecture

The **AI Telephony Guard** is an active intrusion prevention system (IPS) designed specifically for real-time SIP and VoIP communication networks. Operating as a protective shield around Telephony Server and Kamailio SBC, it continuously monitors incoming SIP packets, registration frequencies, DTMF dialing velocities, and authentication failures.

When anomaly patterns indicate malicious automation (e.g. distributed SIP scanners, SIP INVITE floods, or toll fraud brute-forcing), the Guard immediately:
1. Blocks the offending IP address in kernel-level packet filters (iptables/nftables or Kamailio `htable`).
2. Terminates unauthorized live call attempts.
3. Broadcasts the attack signature across all nodes in the cluster.

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                          AI Telephony Guard Perimeter Shield                           │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│   Inbound SIP Traffic (Internet / WAN)                                                 │
│   [SIP INVITE / REGISTER / OPTIONS]                                                    │
│          │                                                                             │
│          ▼                                                                             │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐  │
│   │                      Layer 1: Perimeter Pre-Filter                              │  │
│   │  ├─ APIBAN / VoIPBL Known Malicious IP Database (Cached in Memory)              │  │
│   │  └─ Kamailio Pike / Anti-Flood Hash Table (CPS & Burst Limiting)                │  │
│   └──────────────────────────────────────┬──────────────────────────────────────────┘  │
│                                          │ (Clean Traffic)                             │
│                                          ▼                                             │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐  │
│   │                      Layer 2: AI Telemetry & Heuristic Engine                   │  │
│   │  ├─ Failed Auth Anomaly Detector (Exponential Backoff Tracking)                 │  │
│   │  ├─ Toll Fraud Pattern Matcher (High-rate international dialing velocity)      │  │
│   │  └─ SIP User-Agent Scanners (Friendly-scanner, sipcli, Sundayddos signatures)   │  │
│   └──────────────────────────────────────┬──────────────────────────────────────────┘  │
│                                          │                                             │
│                     Threat Detected? ────┴──── Clean SIP Session                       │
│                     │                                   │                              │
│                     ▼ YES                               ▼                              │
│   ┌──────────────────────────────────────┐     ┌──────────────────────────────────┐    │
│   │ Instant Action:                      │     │ Telephony Core Telephony Engine │    │
│   │ ├─ Drop Packet (Silently / 603)      │     │ ├─ Normal Registration           │    │
│   │ ├─ Add IP to Guard Blocklist         │     │ └─ Legitimate Call Routing       │    │
│   │ └─ Push Alert to Admin Dashboard     │     └──────────────────────────────────┘    │
│   └──────────────────────────────────────┘                                             │
│                                                                                        │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

---

## 2. Threat Vectors Mitigated

| Threat Vector | Attack Profile | AI Telephony Guard Defense |
|---------------|----------------|----------------------------|
| **Brute-Force SIP Registration** | Automated botnet attempts thousands of extension/password combinations. | Limits authentication attempts per IP/CIDR; enforces progressive exponential backoff and temporary IP isolation after 3 failed attempts. |
| **Toll Fraud (International Scams)** | Compromised extension dials expensive international premium destinations (e.g., satellite, Caribbean premium rate numbers). | Velocity algorithms detect sudden spikes in outbound call volume or unfamiliar country prefixes; blocks destination and triggers emergency admin alert. |
| **SIP INVITE Flood (DoS)** | High Calls-Per-Second (CPS) bursts aimed at exhausting Telephony Server channel licenses and CPU. | Token-bucket rate limiting at the Kamailio perimeter drops excess packets before they consume PBX resources. |
| **Reconnaissance Scanners** | Probing tools like `sipvicious`, `friendly-scanner`, and `sipcli`. | Signature detection drops packets matching scanner headers with zero SIP response to prevent fingerprinting. |

---

## 3. Real-Time Telemetry & Heuristic Engine

The AI Telephony Guard collects telemetry from:
- **Telephony Server Auth Events**: Monitored via ESL socket event listeners.
- **Kamailio Pike Alerts**: High-speed traffic bursts tracked in shared memory.
- **CDR Duration Anomalies**: Multiple sub-second calls followed by sudden long-duration international calls.

---

## 4. Community Threat Intelligence (APIBAN & VoIPBL)

The Telephony Guard integrates with global threat intelligence feeds:
- **APIBAN Client**: Regularly syncs with the APIBAN threat database, pre-emptively blocking known hostile scanners before they transmit a single packet to your PBX.
- **VoIPBL Integration**: Real-time DNSBL checks and CIDR range blacklisting.

---

## 5. Configuration & Sensitivity Thresholds

Configured under **Admin → AI → Telephony Guard**:
- **Sensitivity Level**: `Low` (broad tolerance for office NAT networks), `Medium` (Recommended for hosted PBX), `High` (Aggressive lockouts for high-security environments).
- **Failed Auth Threshold**: Maximum failed registration attempts allowed before blocking (Default: `5 attempts in 60 seconds`).
- **Temporary Block Duration**: Duration an offensive IP remains banned (Default: `3600 seconds / 1 hour`; repeated offenses escalate to permanent block).

---

## 6. Incidents, Blacklists & Manual Unblocking

- **Active Incidents Table**: Displays timestamp, offensive IP, targeted extension, threat classification, and current ban status.
- **One-Click Whitelist / Unblock**: If a remote employee enters the wrong password repeatedly from home, administrators can click **Unblock IP** or **Add to Whitelist** to instantly clear the ban without restarting firewall services.

---

## Model Context Protocol (MCP) AI Integration

The AI Telephony Guard integrates with the **Ring2All Platform Copilot MCP Server**, enabling automated threat hunting, extension quarantine, and voice quality diagnostics:

### 🛠️ Available MCP Tools

| Tool Name | Operation | Access Level | Description | Key Parameters |
|:---|:---|:---|:---|:---|
| `diagnose_pbx_security_threats` | Read | Security / SuperAdmin | Analyzes real-time SIP threat telemetry, active toll fraud vectors, brute-force anomalies, and cluster threat probability scores. | None |
| `quarantine_compromised_extension` | Write (Guarded) | Security / SuperAdmin | Places a suspected or compromised extension into immediate quarantine, disconnecting active calls and blocking outbound PSTN routes. | `extension` (string, required), `reason` (string, required), `quarantineDurationMinutes` (number, optional) |
| `inspect_call_quality_mos` | Read | Operations / SuperAdmin | Computes real-time and 24-hour Mean Opinion Score (MoS) metrics, analyzing jitter, latency, and packet loss anomalies. | `timeframeHours` (number, optional), `domainId` (number, optional) |
| `get_ai_voice_safety_metrics` | Read | Security / SuperAdmin | Inspects real-time safety metrics for AI voice agents (token burn rates, synthetic loop prevention, prompt injection attempts). | None |

### 📋 JSON Tool Schemas & Sample Executions

#### `diagnose_pbx_security_threats`

```json
{
  "name": "diagnose_pbx_security_threats",
  "arguments": {}
}
```

*Sample Successful Response:*
```json
{
  "success": true,
  "data": {
    "overallThreatScore": 14,
    "status": "SECURE",
    "threatsNeutralized24h": 87,
    "estimatedLossProtected": "$12,450.00",
    "quarantinedExtensions": [
      {
        "extension": "1042",
        "quarantinedAt": "2026-09-08T09:12:00Z",
        "reason": "Abnormal velocity: 45 outbound international calls in 3 minutes",
        "expiresAt": "2026-09-08T11:12:00Z"
      }
    ],
    "activeIncidents": []
  }
}
```

#### `quarantine_compromised_extension`

```json
{
  "name": "quarantine_compromised_extension",
  "arguments": {
    "extension": "1042",
    "reason": "Confirmed toll fraud credential leak",
    "quarantineDurationMinutes": 120
  }
}
```

*Sample Successful Response:*
```json
{
  "success": true,
  "data": {
    "extension": "1042",
    "status": "QUARANTINED",
    "quarantinedUntil": "2026-09-08T12:45:00Z",
    "activeChannelsTerminated": 2,
    "message": "Extension 1042 has been isolated and active calls terminated."
  }
}
```

### 💬 Natural Language Prompt Examples

#### English Prompts
- *"Diagnose the current security posture and check if any extensions are in quarantine."*
- *"Quarantine extension 1042 immediately due to suspicious international call velocity."*
- *"Inspect current Mean Opinion Score (MoS) and call quality trends across the PBX."*
- *"Show me AI voice agent safety metrics and token exhaustion defenses."*

#### Ejemplos en Español (Spanish Prompts)
- *"Diagnostica el estado de seguridad actual y comprueba si hay extensiones en cuarentena."*
- *"Pon en cuarentena la extensión 1042 inmediatamente por velocidad sospechosa de llamadas internacionales."*
- *"Inspecciona la métrica de calidad de voz (MoS) y tendencias de jitter en la centralita."*
- *"Muéstrame las métricas de seguridad de los agentes de voz IA y defensas contra bucles sintéticos."*

### 🛡️ Enterprise Safeguards & Best Practices
1. **Immediate Call Termination**: Placing an extension into quarantine atomically sends ESL hangup signals to any live channels on Telephony Server (`uuid_kill`), stopping active financial toll leaks.
2. **Audit Logging & Automatic Notification**: Quarantining an extension dispatches high-priority webhooks and creates an entry in `public.audit_logs` with the originating user/AI context.
3. **Timed Expiration**: Quarantines can specify automatic expiration timers, preventing forgotten permanent lockouts of legitimate corporate extensions.

---

## 7. Glossary

| Term | Definition |
|------|------------|
| **Pike** | Kamailio anti-flood module that tracks IP request rates in real time. |
| **APIBAN** | Global honeypot network providing active IP addresses attacking VoIP platforms. |
| **Toll Fraud** | Unauthorized hijacking of telephony routes to dial premium rate revenue-sharing numbers. |
| **CPS** | Calls Per Second; a metric of inbound call volume. |

---

*Documentation updated: September 2026*