AI Perimeter Guard Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial & Business Value)
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Structure
5. Architectural Flow & Security Governance
6. Common Scenarios & Operational Playbooks
7. Troubleshooting & Diagnostic Commands
8. Model Context Protocol (MCP) AI Integration
9. Glossary

---

1. Module Overview (Technical)

The AI Perimeter Guard module (public.ai_security_events, public.ai_guard_settings, public.firewall_ip_bans) delivers autonomous, heuristic-driven threat detection and automated IP mitigation for Ring2All Billing. In telecommunications environments, billing engines and online charging systems (OCS) are primary targets for International Revenue Share Fraud (IRSF), distributed credential stuffing against customer self-care portals, automated SIP scan floods, and API scraping.

The AI Perimeter Guard continuously evaluates telemetry streams from the Fastify API access logs, NGINX perimeter proxies, and telecom signaling nodes, scoring incoming connection vectors against neural anomaly models. When an anomaly threshold is breached, the engine autonomously pushes kernel-level IP bans to Linux nftables/iptables and Kamailio memory tables (htable).

Data Model & Architecture Diagram

 ┌────────────────────────────────────────────────────────────────────────┐
 │                   AI Perimeter Engine & Telemetry Stream               │
 │  • NGINX HTTPS Reverse Proxy Logs                                      │
 │  • Fastify REST API Authentication Requests (/api/v1/auth/login)       │
 │  • OCS Balance Deduction & Webhook Callbacks                           │
 │  • Kamailio SIP Signaling & Pike Flood Meters                          │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Anomaly & Risk Evaluation Engine                  │
 │  • Entropy Calculation: Header randomness, user-agent fuzzing          │
 │  • Velocity Metering: Requests/second per IP and ASN                   │
 │  • Toll Fraud Pattern Correlation: Sequential high-cost destination calls│
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           ▼                                                   ▼
 ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
 │    ai_security_events Table       │               │      firewall_ip_bans Table       │
 │ • event_type: 'brute_force'       │               │ • ip_address: '198.51.100.44'     │
 │ • severity: 'critical'            │               │ • ban_type: 'kernel_drop'         │
 │ • ai_confidence: 0.96             │               │ • duration_seconds: 86400         │
 │ • mitigation_action: 'ban'        │               │ • trigger_rule: 'ai_perimeter'    │
 └───────────────────────────────────┘               └─────────────────┬─────────────────┘
                                                                       │
                                                     Autonomous Push   ▼
                                                     ┌───────────────────────────────────┐
                                                     │   Linux nftables & iptables Drop  │
                                                     │   Kamailio htable blacklist ban   │
                                                     └───────────────────────────────────┘

PostgreSQL Schema Architecture

• public.ai_security_events:

  • id: Numeric primary key (bigserial).
  • event_type: Attack category ('brute_force', 'distributed_scan', 'toll_fraud', 'malformed_sip', 'api_abuse').
  • severity: Threat ranking ('low', 'medium', 'high', 'critical').
  • ip_address: Offending IPv4 or IPv6 address.
  • ai_confidence: Statistical confidence score generated by the model (0.00 to 1.00).
  • mitigation_action: Active countermeasure deployed ('monitored', 'rate_limited', 'ban', 'diverted').
  • created_at: High-resolution microsecond timestamp.

• public.ai_guard_settings:

  • enabled: Master toggle activating autonomous enforcement.
  • sensitivity_level: Operational posture ('low', 'balanced', 'aggressive').
  • auto_ban_threshold: Confidence cut-off required to trigger immediate kernel drop.
  • ban_duration_hours: Default quarantine period before IP expiration.
  • telephony_toll_fraud_guard: Dedicated toggle correlating rating CDR spikes with origin IPs.

---

2. Module Overview (Commercial & Business Value)

• Direct Toll Fraud & IRSF Prevention: Automated detection of anomalous call surges stops International Revenue Share Fraud in milliseconds, protecting carriers and VoIP providers from multi-thousand-dollar wholesale carrier disputes.
• Elimination of 24/7 Security Burnout: Autonomous mitigation neutralizes zero-day brute force and botnet floods instantly, freeing Network Operations Center (NOC) engineers from manual IP blocking during off-hours.
• Preservation of Legitimate Customer Traffic: Machine learning cross-references customer geolocation, historic billing activity, and ASN reputation to avoid false positives, ensuring valid paying customers are never locked out of their self-care portals.

---

3. 🎯 User Roles & Key Capabilities

User Role	Key Permissions	Core Responsibilities & Workflows
Super Administrator	Full Control (RW on AI Defense & Kernel Bans)	Calibrates AI sensitivity parameters, adjusts auto-ban confidence thresholds, overrides kernel bans, and binds AI analysis providers.
Security Officer / SecOps	Forensic Read & Ban Management	Investigates attack vectors, inspects forensic telemetry payloads, validates threat posture, and manually releases mistakenly banned enterprise IPs.
Billing & NOC Auditor	Read-Only (Dashboard & Event Stream)	Reviews security posture metrics, cross-references security incident spikes with customer dispute tickets, and monitors carrier billing integrity.

---

4. Visual Interface & Form Structure

Level 1 — AI Perimeter Guard Threat Overview

The main telemetry dashboard delivers real-time situational awareness, displaying active kernel bans, today’s attack volume, toll fraud blocks, top attacking origin countries, 7-day vector distribution, and 24-hour threat velocity.

Level 2 — Defense Settings Tab

The settings view enables granular calibration of detection heuristics, auto-ban triggers, quarantine duration, and telemetry refresh cadences.

Fields & Parameters Reference

• AI Defense Shield (Master Toggle): Enables or disables real-time evaluation of perimeter traffic.
• Sensitivity Posture: Configures detection aggression:
  • Balanced (Recommended): Optimized for standard telecom and billing traffic; minimizes false positives.
  • Aggressive: Lower tolerance for credential retry failures; immediately bans repeated 401/403 responses.
  • Permissive: Observational mode; logs events to database without executing kernel drops.
• Auto-Ban Threshold Score: Minimum AI model confidence (e.g., 85%) required before executing an automated kernel ban.
• Quarantine Duration (Hours): Duration an offending IP remains blocked in firewall_ip_bans before automatic expiration.
• Telemetry Refresh Cadence: Interval (seconds) at which the front-end dashboard polls background metrics.

---

5. Architectural Flow & Security Governance

  ┌──────────────┐         1. Inbound Requests            ┌────────────────────────┐
  │  Perimeter   ├───────────────────────────────────────►│  NGINX / Fastify API   │
  │   Traffic    │                                        └───────────┬────────────┘
  └──────────────┘                                                    │
                                                         2. Asynchronous Telemetry
                                                            Push via Redis Pub/Sub
                                                                      ▼
  ┌──────────────┐         4. Synchronize Blacklist       ┌────────────────────────┐
  │ Linux Kernel ◄────────────────────────────────────────┤  AI Perimeter Guard    │
  │   nftables   │                                        │  Background Evaluator  │
  └──────────────┘                                        └───────────┬────────────┘
                                                                      │
                                                         3. Write Event & Ban
                                                                      ▼
                                                          ┌────────────────────────┐
                                                          │   ss_billing Database  │
                                                          │  (ai_security_events,  │
                                                          │   firewall_ip_bans)    │
                                                          └────────────────────────┘

1. Ingestion: API authentication calls and web portal traffic pass through the perimeter web server.
2. Telemetry Dispatch: Request metadata (IP, headers, ASN, path, response status) is pushed to the evaluator daemon.
3. Inference & Auditing: The engine evaluates anomaly scores. If confidence exceeds the threshold, an event is logged in public.ai_security_events and an immutable record is inserted into public.firewall_ip_bans.
4. Kernel Drop Execution: The ban executor executes an atomic rule addition to the Linux kernel firewall (nftables set ring2all_bans), instantly discarding subsequent TCP/UDP packets from the offender.

---

6. Common Scenarios & Operational Playbooks

Playbook 1: Investigating a “Critical” Toll Fraud Alert

1. Open ADMIN > Firewall > AI Perimeter Guard.
2. Review the Attack Vectors (7 Days) breakdown.
3. Switch to the Security Incidents tab to inspect the source IP, destination numbers attempted, and confidence rating.
4. Verify whether the offending IP is already quarantined in Active Kernel Bans.
5. If the IP attempted high-cost international destinations (e.g., +232, +252), navigate to BILLING > Customer Accounts > Customers to ensure the compromised customer account is temporarily suspended.

Playbook 2: Whitelisting a False-Positive Corporate Gateway

1. Navigate to ADMIN > Firewall > Access Control.
2. Click + Add Entry.
3. Enter the customer’s corporate gateway IP/CIDR (e.g., 198.51.100.0/24).
4. Set Action to Allow and toggle Bypass AI Guard.
5. Click Save and close.
6. If the IP was previously quarantined, navigate to ADMIN > Firewall > AI Perimeter Guard > IP Forensic Audit and click Remove Ban.

---

7. Troubleshooting & Diagnostic Commands

Verifying AI Guard Database State

# Check recent AI security alerts
sudo -u postgres psql -d ss_billing -c \
  "SELECT event_type, severity, ip_address, ai_confidence, mitigation_action, created_at \
   FROM ai_security_events ORDER BY id DESC LIMIT 5;"

# Inspect active IP bans enforced by the system
sudo -u postgres psql -d ss_billing -c \
  "SELECT id, ip_address, ban_type, reason, expires_at FROM firewall_ip_bans WHERE status = 'active';"

Inspecting Linux Kernel nftables Sets

# Check if kernel set contains banned IP addresses
nft list set inet filter ring2all_bans

# Manually test dropping an offending IP via nftables
nft add element inet filter ring2all_bans { 198.51.100.44 }

Checking Daemon Service Logs

# Monitor real-time telemetry processing in Fastify API
journalctl -u ring2all-billing-api -f | grep -i "ai-guard"

---

8. Model Context Protocol (MCP) AI Integration

The AI Perimeter Guard module connects directly to the Ring2All BSS MCP Server, providing security copilots and autonomous SOC diagnostic tools with real-time threat intelligence, kernel mitigation statuses, and automated IP ban telemetry.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
get_firewall_ai_perimeter_status	Super Administrator	Retrieves AI Perimeter Guard real-time telemetry, active threat bans, and heuristic anomaly scores.	{}

Sample MCP Tool Execution: get_firewall_ai_perimeter_status

Request Payload

{
  "name": "get_firewall_ai_perimeter_status",
  "arguments": {}
}

Response Payload

{
  "guardEnabled": true,
  "neuralModelActive": true,
  "activeBansCount": 3,
  "eventsLast24Hours": 142,
  "highestAnomalyScore": 0.94,
  "recentBans": [
    {
      "id": 12,
      "ipAddress": "198.51.100.44",
      "reason": "Distributed Credential Stuffing & Rate Flood",
      "aiConfidence": 0.94,
      "expiresAt": "2026-09-10T04:00:00Z"
    }
  ]
}

Conversational AI Prompts for Copilot

• “What is the current status of the AI Perimeter Guard and how many IPs are banned?”
• “Show all high-confidence security events detected in the last 24 hours.”
• “Verify if kernel nftables drop sets are active and synchronized.”

---

9. Glossary

• IRSF (International Revenue Share Fraud): Telecommunications fraud where attackers route calls to high-cost premium numbers through compromised accounts.
• Confidence Score: A mathematical value between 0.00 and 1.00 indicating the statistical likelihood that an observed traffic pattern is malicious.
• Kernel Drop: Dropping network packets directly in Linux kernel netfilter/nftables space before socket allocation, protecting CPU resources.
• Telemetry Vector: Multidimensional data points (rate, path, entropy, geographic origin) evaluated together to detect anomalous activity.
• Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.