---
title: "Public Blacklists (APIBAN) Module Documentation"
description: "Documentation for Public Blacklists"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [User Roles & Key Capabilities](#-user-roles--key-capabilities)
7. [Configuration Sections](#4-configuration-sections)
8. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
9. [Common Scenarios & Examples](#6-common-scenarios--examples)
10. [Limitations & Important Notes](#7-limitations--important-notes)
11. [Troubleshooting Tips & CLI Commands](#8-troubleshooting-tips--cli-commands)
12. [Glossary](#9-glossary)

---

## Navigation & Access

To access the Public Blacklists 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 **Public Blacklists** (`/admin/firewall/voipbl`).
4. Enter or update your **APIBAN API Key** and click **Test & Save Key** to validate connectivity.
5. Toggle **Module Status** and **Automatic Updates** according to operational requirements.
6. Click **Sync Now** in the bottom action bar to trigger an on-demand threat intelligence synchronization.

---

## Screenshots & Visual Interface

### Public Blacklists (APIBAN) Dashboard
The Public Blacklists interface manages real-time threat intelligence synchronization: verifying APIBAN API keys, enabling automated periodic updates, reporting last synchronization timestamps and total banned IPs (over 3,300 active malicious hosts), and tracking mitigation statistics (packets dropped and mitigated bandwidth).
![Public Blacklists Dashboard](/screenshots/admin/firewall/public-blacklists-form.png)

---

## 1. Module Overview (Technical)

### What Is the Public Blacklists Module?

The **Public Blacklists** module provides real-time distributed threat intelligence integration with **APIBAN** (an automated global honeypot network specifically designed for VoIP and SIP systems). It actively retrieves and enforces a curated, high-confidence list of known malicious IP addresses, protecting the Ring2All SBC and PBX from:
- Automated SIP scanners and credential brute-force attempts (Friendly-Scanner, SIPVicious, etc.).
- Toll fraud and unauthorized PSTN routing attempts.
- SIP Distributed Denial of Service (DDoS) and flood attacks.

### Dual-Layer Protection Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│           Public Blacklists (APIBAN) Architecture               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Ring2All Platform UI / REST API / MCP AI Copilot               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  • API Key: [ ****************************** ] [Validated]│   │
│  │  • Module Status: [Active]                               │   │
│  │  • Auto-Update:   [Enabled - Daily Cron]                 │   │
│  │  • Threat Feed:   [2,144+ Active Malicious IPs]          │   │
│  └──────────────────┬───────────────────────────────────────┘   │
│                     │                                           │
│                     ▼ [Paginated APIBAN Sync]                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        generate-nftables.sh / voipblService.ts           │   │
│  │                                                          │   │
│  │  1. GET https://apiban.org/api/{KEY}/banned              │   │
│  │  2. Loop batches of 250 IPs via cursor (ID)             │   │
│  │  3. Save to /var/lib/voipbl/voipbl.txt                  │   │
│  │  4. Populate Linux nftables Set (voipbl_blocked_v4)      │   │
│  │  5. Populate Kamailio in-memory htable (apiban)         │   │
│  └──────────┬─────────────────────────────┬─────────────────┘   │
│             │                             │                     │
│             ▼ [Kernel-Level Drop]         ▼ [Application Drop]  │
│  ┌──────────────────────────────┐ ┌──────────────────────────┐  │
│  │          nftables            │ │     Kamailio Core        │  │
│  │                              │ │                          │  │
│  │ table inet filter {          │ │ request_route {          │  │
│  │   set voipbl_blocked_v4 {    │ │   if ($sht(apiban=>$si)) │  │
│  │     elements = { ... }       │ │     { drop; exit; }      │  │
│  │   }                          │ │ }                        │  │
│  │   chain input {              │ │                          │  │
│  │     ip saddr @voipbl_... drop│ │ Silent drop before SIP   │  │
│  │   }                          │ │ parsing begins           │  │
│  │ }                            │ │                          │  │
│  └──────────────────────────────┘ └──────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value: VoIPBL vs. APIBAN

| Metric / Feature | Legacy VoIPBL | Ring2All APIBAN Integration |
| :--- | :--- | :--- |
| **Data Freshness** | Stale static dump (accumulates IPs for 10+ years). | **Real-time Honeypots** with strict **7-day TTL**. |
| **False Positive Rate** | **High:** Blocks clean residential/carrier IPs. | **Zero False Positives:** Only active attackers. |
| **Resource Efficiency** | Requires loading 93,000+ flat entries. | Ultra-lightweight (~2,000 to 5,000 active threat IPs). |
| **Cost** | Free (Unmaintained). | **100% Free API Key** generated in 30 seconds. |
| **Kernel Performance** | High memory overhead in packet filtering. | Instant lookup via `nftables` and Kamailio hash tables. |

### Key Business Benefits
1. **Zero Downtime Toll Fraud Protection**: Prevents unauthorized PBX trunk hijack before credentials can be guessed.
2. **Clean CDRs & Telephony Logs**: Eliminates log noise caused by automated SIP port sniffers.
3. **Bandwidth & CPU Preservation**: Drops malicious network packets at the kernel level without waking userland daemons.

---

## 3. Module Overview (End User/Administrator)

### What Can You Do in This Module?

1. **Configure APIBAN API Key**:
   - Enter your personal API Key obtained for free from [https://apiban.org](https://apiban.org).
   - Use the **"Test & Save Key"** button to validate communication with APIBAN servers.
   - Built-in mask/unmask eye toggle for secure credentials display.
2. **Master Module Activation**:
   - Toggle **Module Status** (`Active` / `Inactive`). *Note: Requires a valid API Key to enable.*
3. **Automated Synchronization**:
   - Toggle **Automatic Updates** to keep the threat list refreshed on a recurring schedule.
4. **Manual On-Demand Sync**:
   - Click the bottom-right **"Sync Now"** button to immediately pull the newest threat intelligence feed.
5. **IP Threat Lookup**:
   - Use the header search button to verify if any specific IPv4 address is currently blocked.
6. **Mitigation Metrics**:
   - Real-time telemetry displaying total packets dropped and total bandwidth mitigated.

---

## 🎯 User Roles & Key Capabilities

The Public Blacklists (APIBAN) module distributes community threat intelligence responsibilities across platform operational roles:

| User Role | Key Permissions & Responsibilities | Common Tasks & Workflows |
|:---|:---|:---|
| **System Super Administrator / Security Director** | Master API key management, scheduler configuration, and kernel mitigation oversight. | Register free APIBAN API key, test credentials connectivity, toggle automated background sync (every 4 hours), monitor dropped packet metrics. |
| **NOC & Security Operations Engineer** | Real-time IP threat verification, investigating reported false positives, and whitelist override administration. | Query IP reputation status via Copilot or UI search, determine if a blocked carrier/client IP was flagged for scanning, create high-priority firewall whitelist overrides. |
| **Tenant Administrator** | Read-only visibility into community threat mitigation metrics. | Review total blocked malicious hosts, inspect bandwidth and CPU cycles saved by kernel-level drops, verify platform protection status. |
| **Cybersecurity Auditor** | Verification of threat intelligence hygiene and compliance with data retention benchmarks. | Verify automated list aging (7-day TTL vs permanent legacy blocklists), validate near-zero false-positive rates on active attacker addresses. |

---

## 4. Configuration Sections

### 1. APIBAN API Key Panel
- **API Key Input**: Secure password/text field with instant validation badges:
  - `VALID API KEY` (Green): Key verified and active.
  - `INVALID KEY` (Amber/Red): Key rejected by APIBAN authentication.
  - `NOT CONFIGURED` (Slate): Module waiting for initial key setup.
- **Link**: Direct quick-link to [https://apiban.org](https://apiban.org) to obtain free keys.

### 2. Status & Automation Toggles
- **Module Status**: Master switch. When disabled, the `voipbl_blocked_v4` set is cleared.
- **Automatic Updates**: Enables background cron synchronization every 4 hours.

### 3. Synchronization & Mitigation Status
- **Last Synchronization**: Timestamp of the most recent sync.
- **Sync State**: Real-time status (`Success`, `Syncing...`, `Failed`, or `Idle`).
- **Total Banned IPs**: Total number of active malicious IPs currently blocked in the firewall.
- **Packets Dropped**: Total network packets intercepted and discarded.
- **Bytes Mitigated**: Bandwidth saved by dropping malicious traffic at the kernel level.

---

## Model Context Protocol (MCP) AI Integration

The Public Blacklists module is integrated with the **Ring2All Platform Copilot MCP Server**, enabling natural language threat intelligence querying, on-demand synchronization, and IP reputation lookups:

### 🛠️ Available MCP Tools

| Tool Name | Operation | Access Level | Description | Key Parameters |
|:---|:---|:---|:---|:---|
| `get_voipbl_status` | Read | SuperAdmin / Auditor | Returns the current APIBAN provider state, API Key validity, last sync timestamp, and total blocked malicious scanner IPs. | None |
| `sync_threat_intelligence` | Write (Guarded) | SuperAdmin Only | Triggers an immediate background synchronization with the APIBAN threat database and updates kernel nftables sets. | None |
| `check_ip_threat_status` | Read | SuperAdmin / Auditor | Queries whether a specific IPv4 address is actively flagged in the community threat intelligence database. | `ipAddress` (string, required) |

### 📋 JSON Tool Schemas & Sample Executions

#### `get_voipbl_status`

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

*Sample Successful Response:*
```json
{
  "success": true,
  "data": {
    "provider": "APIBAN",
    "enabled": true,
    "autoUpdate": true,
    "syncStatus": "SUCCESS",
    "lastSyncAt": "2026-09-08T08:00:15Z",
    "hasApiKey": true,
    "totalBlockedMaliciousIps": 3412
  }
}
```

#### `check_ip_threat_status`

```json
{
  "name": "check_ip_threat_status",
  "arguments": {
    "ipAddress": "198.51.100.25"
  }
}
```

*Sample Successful Response:*
```json
{
  "success": true,
  "data": {
    "ipAddress": "198.51.100.25",
    "isBlocked": true,
    "provider": "APIBAN"
  }
}
```

### 💬 Natural Language Prompt Examples

#### English Prompts
- *"What is the current status of the APIBAN threat intelligence feed?"*
- *"Check if IP '198.51.100.25' is currently blocked in the public threat blacklist."*
- *"Trigger an immediate background synchronization of the public blacklist."*
- *"How many malicious scanner IPs are currently blocked by APIBAN?"*

#### Ejemplos en Español (Spanish Prompts)
- *"¿Cuál es el estado actual de la sincronización de amenazas de APIBAN?"*
- *"Verifica si la IP '198.51.100.25' está bloqueada en la lista negra pública."*
- *"Ejecuta una sincronización inmediata de la lista de amenazas de APIBAN."*
- *"¿Cuántas direcciones IP de escáners maliciosos están bloqueadas actualmente por APIBAN?"*

### 🛡️ Enterprise Safeguards & Best Practices
1. **Sync Cooldown & Anti-Flooding**: Rapid manual sync calls are rate-limited to avoid APIBAN upstream HTTP 429 throttling and preserve local database connection pools.
2. **Strict 7-Day TTL**: Unlike unmaintained legacy VoIPBL feeds that retain stale entries indefinitely, APIBAN enforces a rolling 7-day TTL, dramatically reducing false-positive rates on recycled residential IP pools.
3. **Emergency Whitelist Precedence**: High-priority ACCEPT rules configured in the *Firewall Rules* module take precedence over APIBAN kernel sets, ensuring legitimate client or carrier traffic can be restored immediately.

---

## 6. Common Scenarios & Examples

### Scenario 1: First-Time Setup
1. Visit [https://apiban.org](https://apiban.org) and register for a free API Key.
2. Navigate to **Admin -> Firewall -> Public Blacklists**.
3. Paste the API Key into the input field and click **"Test & Save Key"**.
4. Once validated (green badge), toggle **Module Status** to **Active**.
5. Enable **Automatic Updates** and click **"Sync Now"**.
6. The system will download ~2,000+ active threat IPs into `nftables` and Kamailio.

### Scenario 2: Verifying a Blocked Remote Worker
If a remote employee or trunk is having connectivity problems:
1. Click the **Search** icon in the upper right header of the Public Blacklists module.
2. Enter the remote worker's public IP address (e.g. `198.51.100.44`).
3. If the IP is listed in APIBAN (meaning it was flagged for attacking a honeypot in the last 7 days), you can:
   - Add a high-priority **ACCEPT** rule in **Firewall Rules** to override the blacklist.
   - Advise the user to release/renew their dynamic ISP IP.

---

## 7. Limitations & Important Notes

> [!NOTE]
> **Dynamic Pagination**: The APIBAN REST API returns 250 IPs per call. Ring2All automatically loops through all cursors (`last_id`) until the entire active feed is downloaded.

> [!IMPORTANT]
> **Kernel vs. Application Drops**: Packets dropped by `nftables` will not appear in `sngrep` captures because they are discarded at layer 3/4 before reaching the SIP socket.

---

## 8. Troubleshooting Tips & CLI Commands

### Verifying on the Server CLI

```bash
# 1. Check the downloaded threat feed file
wc -l /var/lib/voipbl/voipbl.txt

# 2. Inspect the populated nftables set
nft list set inet filter voipbl_blocked_v4

# 3. Verify drop rules in the input chain
nft list chain inet filter input | grep voipbl

# 4. (If Kamailio SBC is used) Inspect in-memory hash table
kamcmd htable.dump apiban
```

### Common Issues and Solutions

| Symptom | Cause | Solution |
| :--- | :--- | :--- |
| `Invalid API Key` on Test | Typo or inactive key | Verify key on https://apiban.org or generate a new free key. |
| Sync downloads only 250 IPs | Old script version | Ensure `generate-nftables.sh` pagination loop is deployed. |
| Packets Dropped shows 0 | Fresh deployment or reboot | Counters accumulate over time as scanners hit the server. |

---

## 9. Glossary

| Term | Definition |
| :--- | :--- |
| **APIBAN** | Automated Public IP Blacklist for SIP & VoIP honeypots. |
| **TTL (Time to Live)** | 7-day expiration period for threat intelligence entries. |
| **nftables** | Linux kernel packet classification and firewall framework. |
| **htable** | Kamailio in-memory high-speed hash table module. |

---

*Documentation last updated: August 2026*