---
title: "Public Blacklists & Threat Intelligence Feeds (VoIPBL & APIBAN)"
description: "Documentation for Public Blacklists (VoIPBL)"
---

## Table of Contents
1. [Overview & Threat Intelligence Architecture](#1-overview--threat-intelligence-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. [Field Reference & Threat Feed Parameters](#5-field-reference--threat-feed-parameters)
6. [Feed Synchronization & In-Memory Drop Pipeline](#6-feed-synchronization--in-memory-drop-pipeline)
7. [Operational Best Practices & False-Positive Mitigation](#7-operational-best-practices--false-positive-mitigation)
8. [Verification & Diagnostics](#8-verification--diagnostics)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Threat Intelligence Architecture

In **Ring2All SBC**, the **Public Blacklists** module provides real-time community threat intelligence integration. By synchronizing with globally recognized VoIP honeypot feeds—primarily **APIBAN** and **VoIPBL**—the SBC dynamically downloads, caches, and enforces thousands of known bad actors, botnets, and SIP exploit sources before they can interact with local telecom infrastructure.

```
       ┌─────────────────────────────────────────────────────────────┐
       │             GLOBAL THREAT FEEDS (APIBAN & VoIPBL)           │
       │               (Worldwide Distributed Honeypots)             │
       └──────────────────────────────┬──────────────────────────────┘
                                      │ (Automated Sync via REST API)
                                      ▼
       ┌─────────────────────────────────────────────────────────────┐
       │              RING2ALL SBC FEED INGESTION ENGINE             │
       │              (Validated API Key, JSON Parser)               │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
              ┌───────────────────────┴───────────────────────┐
              ▼                                               ▼
       ┌──────────────────────────────┐                ┌──────────────────────────────┐
       │ KAMAILIO MEMORY HASH TABLE   │                │ LINUX NFTABLES KERNEL SET    │
       │      ($sht(voipbl=>$si))     │                │   (set: sbc_public_bans)     │
       ├──────────────────────────────┤                ├──────────────────────────────┤
       │ • Instant SIP-level rejection│                │ • Sub-microsecond packet drop│
       │ • Telemetry drop counters    │                │ • Zero CPU kernel discard    │
       └──────────────────────────────┘                └──────────────────────────────┘
```

The system continuously tracks drop statistics—including cumulative packets dropped and total bandwidth saved—while maintaining automated synchronization cadences without administrative intervention.

---

## 2. Business & Operational Significance

* **Preemptive Zero-Day Protection**: Blocks aggressive SIP scanning botnets within minutes of their first appearance on global honeypots, neutralizing threats before they reach your infrastructure.
* **Radical Reduction in Server Load**: Discards malicious packets directly in the Linux network stack, preserving Kamailio worker threads and Telephony Server RTP resources for revenue-generating client calls.
* **Elimination of Password Guessing**: Prevents credential stuffing against SIP extension passwords by blacklisting distributed botnets actively rotating across cloud VPS providers.
* **Automated Cloud Sync**: Seamlessly polls upstream API feeds, extracts IP indicators of compromise (IoC), and updates local kernel sets without requiring service reboots or manual list management.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **SBC Security Administrator** | Threat Feed Management | Register APIBAN API credentials, enable/disable automated feed synchronization, and trigger on-demand sync operations. |
| **SecOps Analyst** | Threat Intelligence Oversight | Monitor total banned IP volumes, analyze packet and bandwidth drop telemetry, and audit sync status logs. |
| **Carrier Operations Lead** | Interconnect Protection | Ensure high-volume public trunks are insulated from automated attacks without impacting legitimate carrier traffic. |
| **Compliance Auditor** | Cybersecurity Baseline Audit | Verify the deployment of external threat intelligence feeds in compliance with telecom industry standards. |
| **AI Threat Intelligence Agent / NOC Copilot** | Automated Threat Feed Auditing & Synchronization | Inspect APIBAN/VoIPBL module health, query active banned IP volumes and drop counters, and trigger immediate threat feed synchronization via MCP. |

---

## 4. Visual Interface & Layout

The Public Blacklists console provides an intuitive dashboard featuring API key management, service toggle states, synchronization progress indicators, and drop telemetry statistics.

### 4.1 Public Blacklists Management View
Displays API key validation, service status toggles, synchronization metrics, and live packet/bandwidth drop counters.

![Public Blacklists Management View](/screenshots/sbc/admin/public-blacklists/public-blacklists.png)

---

## 5. Field Reference & Threat Feed Parameters

### 5.1 API Key & Service Configuration

| Field | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| **APIBAN API Key** | Secret Key | Enforced | Personal API authentication key issued by APIBAN (e.g., via `https://apiban.org`). Required for feed downloads. |
| **API Key Status** | Badge | Valid / Invalid | Real-time status badge validating cryptographic credential legitimacy against the upstream API server. |
| **Service Status** | Switch Toggle | `Yes` (Active) | Master toggle controlling active threat intelligence enforcement and packet dropping. |
| **Automatic Updates** | Switch Toggle | `Yes` (Auto) | Enables scheduled cron-based background polling to synchronize incremental blacklist updates. |

### 5.2 Synchronization & Telemetry Metrics

| Field | Type | Description |
| :--- | :--- | :--- |
| **Last Synchronization**| Timestamp | The exact date and time of the most recent successful feed download and kernel set ingestion. |
| **Sync Status** | Badge | Operational health indicator (`Success`, `Pending`, or `Error`). |
| **Total Banned IPs** | Metric Counter | Real-time count of active malicious IP addresses currently enforced in memory (e.g., `2,146`). |
| **Packets Dropped** | Metric Counter | Cumulative number of malicious network packets intercepted and discarded by the firewall (e.g., `21,250`). |
| **Data Dropped** | Metric Counter | Total volume of hostile network traffic discarded before reaching application memory (e.g., `6.81 MB`). |

---

## 6. Feed Synchronization & In-Memory Drop Pipeline

When **Sync Blacklist Now** is clicked or the scheduled background worker triggers, the SBC initiates an incremental synchronization workflow:

1. **Incremental Feed Query**:
   ```bash
   GET https://apiban.org/api/<API_KEY>/banned/ID
   ```
2. **Database Ingestion**: Downloaded IPs are committed to the local database with timestamps.
3. **Kernel Set Sync**: The daemon injects newly reported addresses into the `nftables` set:
   ```bash
   nft add element inet filter sbc_public_bans { 198.51.100.89, 203.0.113.14 }
   ```
4. **Kamailio Shared Memory Sync**: The list is pushed to Kamailio's memory table via RPC:
   ```bash
   kamcmd htable.sets voipbl "198.51.100.89" 1
   ```

---

## 7. Operational Best Practices & False-Positive Mitigation

* **Obtain a Dedicated APIBAN Key**: Always generate a dedicated, free API key directly from [apiban.org](https://apiban.org) rather than sharing keys across multiple client installations.
* **Carrier Subnet Exemption**: Verify that local carriers and PSTN gateway IP ranges are explicitly listed in the **AI Perimeter Guard Whitelist** or **ACL Trusted IPs** so that global feed anomalies cannot inadvertently block wholesale partners.
* **Keep Automatic Updates Active**: Threat actors frequently cycle IP addresses across cloud providers within 24–48 hours; maintaining `Automatic Updates` ensures obsolete bans are refreshed with current active threats.
* **Monitor Drop Metrics After Maintenance**: Review `Packets Dropped` counters following network maintenance to verify that threat feeds remain properly bound to public network interfaces.

---

## 8. Verification & Diagnostics

### 8.1 Check Database Blacklist Settings
Query current threat feed parameters and synchronization history:
```bash
sudo -u postgres psql -d sbc_admin -c "SELECT * FROM voipbl_settings;"
```

### 8.2 Inspect Kernel Threat Set
Verify that public blacklist IPs are loaded into the Linux kernel set:
```bash
nft list set inet filter sbc_public_bans | head -n 25
```

### 8.3 Live Sync Daemon Execution
Trigger a manual CLI test of the threat feed synchronization script:
```bash
/usr/local/bin/ring2all-sync-blacklists --verbose
```

---

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

The **Ring2All SBC MCP Server** exposes dedicated threat intelligence tools under the `security` category. Autonomous SecOps agents and the Ring2All SBC NOC Copilot can inspect external blacklist module health, audit IP threat reputations, and trigger asynchronous feed synchronization pipelines.

### 9.1 Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `get_threat_intel_status` | Read-only | `read_only` | Retrieves the status of the APIBAN/VoIPBL public blacklist module, including API key validation, active ban counts, and last synchronization timestamp. |
| `sync_threat_intel` | Mutating / Operational | `operational` | Triggers an immediate background synchronization of upstream APIBAN threat intelligence into Kamailio `htable` and Linux `nftables`. |
| `check_ip_threat_status` | Read-only / Query | `read_only` | Checks whether a specific IP address is currently blocked in Kamailio memory tables (Pike anti-flood or APIBAN threat intel). |

### 9.2 Tool Schemas & Parameter Definitions

#### `get_threat_intel_status`
* **Description**: Get status of the Ring2All SBC Public Blacklist (APIBAN) threat intelligence module and Kamailio in-memory protection.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {}
}
```

#### `sync_threat_intel`
* **Description**: Trigger an immediate background synchronization of APIBAN threat intelligence into Kamailio htable and nftables firewall.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {}
}
```

#### `check_ip_threat_status`
* **Description**: Check if a specific IP address is currently blocked in Kamailio (Pike anti-flood or APIBAN threat intel).
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "ipAddress": {
      "type": "string",
      "description": "The IPv4 address to verify (e.g., '198.51.100.25')"
    }
  },
  "required": ["ipAddress"]
}
```

### 9.3 Sample Tool Execution Payloads

#### Example 1: Ingesting Threat Feed Status
**Request Payload:**
```json
{
  "tool": "get_threat_intel_status",
  "parameters": {}
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "module": "apiban",
    "serviceEnabled": true,
    "apiKeyConfigured": true,
    "lastSyncTimestamp": "2026-09-08T11:30:00Z",
    "syncStatus": "success",
    "totalBannedIps": 2146,
    "packetsDropped": 21250,
    "bandwidthSaved": "6.81 MB"
  }
}
```

#### Example 2: Verifying an External IP's Threat Status
**Request Payload:**
```json
{
  "tool": "check_ip_threat_status",
  "parameters": {
    "ipAddress": "198.51.100.25"
  }
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "ipAddress": "198.51.100.25",
    "isBanned": true,
    "table": "apiban",
    "details": "Present in APIBAN global honeypot blacklist; blocked at wire speed."
  }
}
```

### 9.4 Bilingual Natural Language Copilot Prompts

#### English Prompts
* *"Check the status of the APIBAN public blacklist module and tell me how many IPs are currently blocked."*
  → Agent calls `get_threat_intel_status()`.
* *"Trigger an immediate background synchronization of global threat intelligence feeds."*
  → Agent calls `sync_threat_intel()`.
* *"Is IP 198.51.100.25 currently flagged or blocked in our threat intelligence tables?"*
  → Agent calls `check_ip_threat_status({"ipAddress": "198.51.100.25"})`.

#### Spanish Prompts (Español)
* *"Verifica el estado del módulo de listas negras públicas (APIBAN) y dime cuántas IPs están bloqueadas."*
  → Agente invoca `get_threat_intel_status()`.
* *"Sincroniza de inmediato las fuentes de inteligencia de amenazas globales en el firewall."*
  → Agente invoca `sync_threat_intel()`.
* *"¿Está la IP 198.51.100.25 actualmente marcada o bloqueada en las tablas de inteligencia de amenazas?"*
  → Agente invoca `check_ip_threat_status({"ipAddress": "198.51.100.25"})`.

### 9.5 Enterprise Security & Execution Safeguards

1. **Non-Blocking Background Dispatch**: Executing `sync_threat_intel` launches an asynchronous child worker to fetch remote feeds, preventing HTTP request blocking on Kamailio or the Fastify REST backend.
2. **Rate-Limiting API Protection**: Outgoing API requests to `apiban.org` respect upstream rate limits (maximum 1 request per 4 minutes during polling cycles) to avoid credential throttling.
3. **In-Memory Volatility Protection**: Addresses downloaded from external feeds are cached in persistent PostgreSQL storage and repopulated into memory upon daemon reloads.

---

## 10. Glossary

* **APIBAN**: Free, automated, community-driven threat intelligence system providing IP addresses actively attempting unauthorized SIP interactions.
* **VoIPBL**: Distributed VoIP blacklist that aggregates reports from PBX honeypots worldwide to identify fraudulent and scanning networks.
* **IoC (Indicator of Compromise)**: Forensic evidence on a network or in an operating system that indicates a security breach or active exploit attempt.
* **Kernel Set**: In-memory list structure in Linux packet filtering that allows evaluating thousands of IP addresses with $O(1)$ constant time lookup complexity.
* **Model Context Protocol (MCP)**: An open standard enabling autonomous AI assistants and NOC copilots to securely discover and invoke SBC operational tools.