Fraud Sentinel 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 Fraud Sentinel module (public.fraud_rules, public.fraud_logs) delivers automated, real-time fraud mitigation and anomaly detection for Ring2All Billing. In high-throughput telecommunications networks, financial loss occurs within minutes during International Revenue Share Fraud (IRSF), PBX credential brute-forcing, or runaway automated dialing attacks. Fraud Sentinel interfaces directly with the Online Charging System (OCS) and CDR mediation pipeline to evaluate active traffic against granular velocity limits and security guardrails.

When an anomaly threshold is breached, Sentinel executes immediate policy-driven mitigation—such as shedding rogue call legs with SIP response codes (486 Busy Here), freezing international destination routing for compromised accounts, or fully suspending customer SIP trunks—while recording comprehensive incident traces for audit and review.

Data Model & Architecture Diagram

 ┌────────────────────────────────────────────────────────────────────────┐
 │                   Fraud Guardrails (public.fraud_rules)                │
 │  • id: bigint (Primary Key)                                            │
 │  • tenant_id: bigint / domain_id: bigint                               │
 │  • name: VARCHAR(255) (e.g., 'Hourly Spend Velocity Guard')            │
 │  • rule_type: 'spend_velocity' | 'max_concurrent_calls' | 'daily_spend'│
 │  • threshold_value: numeric(12,2) (e.g., 50.00)                        │
 │  • action: 'terminate_calls' | 'freeze_route' | 'suspend_account'      │
 │  • is_active: boolean                                                  │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │ Evaluates Real-Time Traffic
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │                    Incident Stream (public.fraud_logs)                 │
 │  • id: bigint (Primary Key)                                            │
 │  • customer_id: bigint (FK to public.customers)                        │
 │  • rule_name: VARCHAR(255)                                             │
 │  • severity: 'low' | 'medium' | 'high' | 'critical'                    │
 │  • anomaly_score: integer (0 - 100)                                    │
 │  • details: jsonb (Trigger reasons, spend velocity, destination hops)  │
 │  • action_taken: VARCHAR(100) (Automated mitigation applied)           │
 │  • resolved: boolean (Operator review status)                          │
 │  • created_at: timestamptz                                             │
 └────────────────────────────────────────────────────────────────────────┘

PostgreSQL Schema Architecture

• public.fraud_rules:

  • id: Numeric primary key (bigserial).
  • name: Descriptive identifier for the protection rule.
  • rule_type: Metric being monitored (spend_velocity, max_concurrent_calls, daily_spend).
  • threshold_value: Quantitative ceiling triggering mitigation (e.g., $50.00/hr or 10 Max Channels).
  • action: Enforcement directive executed upon breach (terminate_calls, freeze_international_routing, suspend_customer_account).
  • is_active: Operational toggle enabling or pausing the rule.

• public.fraud_logs:

  • id: Numeric primary key (bigserial).
  • customer_id: References the evaluated customer entity.
  • rule_name: The specific guardrail triggered.
  • severity: Threat severity categorization (low, medium, high, critical).
  • anomaly_score: Normalized risk index between 1 and 100 calculated by the Sentinel engine.
  • details: JSONB payload containing contextual parameters (e.g., hourly spend rate, country codes, call bursts).
  • action_taken: Explicit defense action executed by the platform.
  • resolved: Boolean indicating whether a security engineer has acknowledged and reviewed the event.

---

2. Module Overview (Commercial & Business Value)

• Elimination of IRSF Liability: International Revenue Share Fraud (IRSF) attacks often exploit compromised SIP credentials overnight, generating thousands of dollars in toll charges to premium-rate destinations in under an hour. Sentinel’s velocity limits halt unauthorized spend instantly.
• Preservation of Upstream Carrier Credit: Wholesale carriers enforce strict daily credit lines and fraud indemnification clauses. Unchecked fraudulent bursts can lead to sudden trunk suspension across an entire enterprise.
• Automated 24/7 Threat Neutralization: By operating autonomously at the database and rating engine layer, Fraud Sentinel provides unyielding perimeter defense without requiring manual NOC intervention outside business hours.
• Customer Trust & Dispute Reduction: Transparent incident logs with precise anomaly scoring allow billing teams to demonstrate exactly when an account was compromised and confirm that containment was immediate, eliminating contentious billing disputes.

---

3. 🎯 User Roles & Key Capabilities

Role	Key Capabilities & Permissions in Fraud Sentinel
Security Administrator	Full authority to configure anti-fraud guardrails, set financial thresholds, define automated containment actions (freeze_route, suspend_account), and modify risk formulas.
NOC Engineer	Monitors real-time incident streams, analyzes anomaly scores, reviews SIP trigger reasons, and clears reviewed incidents.
Billing Operator	Inspects customer spend spikes, checks affected rated CDRs, and verifies whether accounts were temporarily restricted due to policy enforcement.
Compliance Officer	Audits historical fraud logs, reviews mitigation timelines, and exports forensic evidence for carrier dispute resolution and regulatory filings.

---

4. Visual Interface & Form Structure

The Fraud Sentinel interface consists of an unified navigation layout with two specialized operating surfaces: Incident Stream (real-time stream and metric telemetry) and Anti-Fraud Guardrails (policy management and rule creation).

4.1 Incident Stream View

The Incident Stream displays high-level operational telemetry alongside a forensic data grid:

• Metric Cards:
  • Sentinel Engine: Real-time operational state (Live Monitoring active).
  • Total Incident Events: Aggregated count of flagged traffic anomalies.
  • High-Risk Threats: Active incidents with anomaly scores equal to or exceeding 70/100.
  • Reviewed & Resolved: Ratio of incidents investigated and resolved by operations staff.
• Forensic Table Fields:
  • Customer Account: Identifies the affected organization, tenant, or SIP trunk.
  • Anomaly Risk Score: Color-coded badge displaying calculated risk (Green: Low, Amber: Medium, Red: Critical).
  • Incident / Trigger Reason: Granular rationale (e.g., “Velocity spend spike ($85 in 15min to Sierra Leone)”).
  • Mitigation Action Taken: Automated action enforced (e.g., “Auto-Frozen International Route”).
  • Time: Timestamp of the detection event.
  • Resolve Action: Quick-action button allowing operators to review and mark incidents as resolved.

4.2 Anti-Fraud Guardrails Management

The Anti-Fraud Guardrails tab provides policy lifecycle administration:

• Guardrail Listing: Presents all active policies, monitored metrics (e.g., Max Concurrent Channels, Hourly Spend Velocity, Max Daily Spend), threshold limits, automated mitigation actions, and activation switches.
• Quick Actions: Edit existing thresholds or delete outdated guardrails with standard confirmation prompts.

4.3 Add Guardrail Modal

Clicking the + Add button opens the Add Guardrail modal:

• Rule Name: Descriptive title (e.g., Hourly Spend Velocity Guard).
• Rule Type: Selects the monitored metric:
  • Spend Velocity ($/hr)
  • Max Concurrent Calls
  • Max Daily Spend ($/day)
• Threshold Limit Value: Numeric trigger limit (e.g., 50.00).
• Mitigation Action: Action executed automatically upon breach:
  • Terminate Calls (486 Busy)
  • Freeze International Routing
  • Suspend Customer Account
• Enabled Switch: Active/inactive status toggle.

---

5. Architectural Flow & Security Governance

 ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
 │ Incoming Call / │       │   OCS Rating    │       │  Sentinel Rule  │
 │  CDR Mediation  │──────▶│   Engine Core   │──────▶│   Evaluation    │
 └─────────────────┘       └─────────────────┘       └────────┬────────┘
                                                              │
                                     ┌────────────────────────┴────────────────────────┐
                                     │ Threshold Exceeded?                             │
                                     ▼                                                 ▼
                              [ NO - Normal ]                                    [ YES - Anomaly ]
                                     │                                                 │
                                     ▼                                                 ▼
                           Proceed to Carrier Trunk                     1. Execute Mitigation Action
                                                                        2. Write public.fraud_logs
                                                                        3. Notify Security Team

1. Ingress Call Valuation: As active SIP channels establish or rated CDRs generate, the OCS continuously computes cumulative spend velocity and active channel volume.
2. Deterministic Guardrail Checking: The Sentinel worker checks current metrics against active rules in public.fraud_rules.
3. Automated Containment: If a threshold is exceeded, the database issues signaling commands to Telephony Server or the SBC perimeter to drop calls or block subsequent INVITE messages.
4. Audit Record Persistence: Details of the breach, including time, affected numbers, and containment codes, are written to public.fraud_logs.

---

6. Common Scenarios & Operational Playbooks

Playbook A: Mitigating an Overnight International Toll Fraud Burst

1. Detection: Sentinel flags a customer account with an anomaly score of 98/100 due to a sudden $85 spend in 15 minutes directed towards high-cost African destinations.
2. Autonomous Action: Sentinel invokes Freeze International Routing. Domestic and inbound calls continue uninterrupted, while high-risk outbound international calls are blocked.
3. NOC Verification: In the Incident Stream, the NOC engineer inspects the trigger reason and verifies with the customer whether this was legitimate traffic.
4. Resolution: If the customer confirms unauthorized usage, the customer credentials are reset, and the NOC engineer marks the incident as Reviewed & Cleared.

Playbook B: Adding a Global Channel Ceiling for New Accounts

1. Navigate to Security > Fraud Sentinel > Anti-Fraud Guardrails.
2. Click + Add.
3. Set Rule Name to Max Concurrent Channels Baseline.
4. Set Rule Type to Max Concurrent Calls.
5. Enter Threshold Limit Value as 10.00.
6. Select Mitigation Action as Terminate Calls (486 Busy).
7. Click Save. Any call attempts beyond 10 concurrent channels are immediately released with 486 Busy.

---

7. Troubleshooting & Diagnostic Commands

Inspecting Recent Fraud Incidents via SQL

SELECT
    l.id,
    c.name AS customer_name,
    l.rule_name,
    l.severity,
    l.anomaly_score,
    l.action_taken,
    l.resolved,
    l.created_at
FROM public.fraud_logs l
LEFT JOIN public.customers c ON c.id = l.customer_id
ORDER BY l.created_at DESC
LIMIT 10;

Checking Active Fraud Guardrails

SELECT
    id,
    name,
    rule_type,
    threshold_value,
    action,
    is_active
FROM public.fraud_rules
ORDER BY id ASC;

Manually Resolving an Incident via Terminal

curl -k -X POST https://192.168.10.29/api/fraud/logs/3/resolve \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json"

---

8. Model Context Protocol (MCP) AI Integration

The Fraud Sentinel module connects directly to the Ring2All BSS MCP Server, providing anti-fraud analysts and automated AI copilots with tools to query active alerts, evaluate risk velocity, and mark resolved incidents.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
list_fraud_alerts	Super Administrator / NOC	Lists real-time fraud alerts and velocity violations detected by the Fraud Sentinel engine.	{"resolved": false, "limit": 10}
resolve_fraud_alert	Super Administrator	Marks an active fraud incident alert as resolved with remediation notes.	{"alertId": 3, "resolutionNotes": "Verified customer campaign; raised limit."}

Sample MCP Tool Execution: list_fraud_alerts

Request Payload

{
  "name": "list_fraud_alerts",
  "arguments": {
    "resolved": false,
    "limit": 5
  }
}

Response Payload

[
  {
    "id": 3,
    "ruleName": "Rapid International Velocity Guard",
    "ruleType": "hourly_cost_limit",
    "severity": "CRITICAL",
    "anomalyScore": 92,
    "actionTaken": "SUSPEND_ACCOUNT",
    "resolved": false,
    "customer": {
      "id": 1,
      "name": "Rodrigo Cuadra",
      "company": "Cuadra Telecom Corp"
    },
    "createdAt": "2026-09-09T04:22:15Z"
  }
]

Conversational AI Prompts for Copilot

• “List all unresolved critical fraud alerts detected by Fraud Sentinel.”
• “Show detailed telemetry for fraud alert ID 3.”
• “Resolve fraud alert 3 with notes ‘False positive confirmed by customer’.”

---

9. Glossary

• IRSF (International Revenue Share Fraud): An organized telecommunications fraud scheme where attackers artificially inflate traffic volumes to premium-rate international telephone numbers.
• Spend Velocity: The rate of monetary consumption over a designated period (e.g., dollars consumed per 60-minute rolling window).
• Mitigation Action: The automated defensive command executed upon policy violation, including call termination, route freezing, or complete trunk suspension.
• Anomaly Score: An algorithmic confidence index (1–100) indicating the statistical deviation of an observed calling pattern from normal operational baselines.
• Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.