VoiceBridge Security Model: ARI, RTP, Firewall Isolation (Production-Grade)

VoiceBridge is not just another web service. It sits directly in the live media path of phone calls. It controls Asterisk through ARI (control plane) and transports live voice using RTP over UDP (media plane).

That makes it extremely powerful — and extremely sensitive.

This document defines the intended, production-ready security model for VoiceBridge deployments:

• How ARI must be isolated
• How RTP ports must be controlled
• How firewall rules should be written
• How DB-stored credentials must be handled
• How to structure network zones correctly

All references map to actual project files in:
https://github.com/mylinehub/omnichannel-crm/tree/main/mylinehub-voicebridge

Understand the Two Critical Planes

1. Control Plane — ARI (HTTP / WebSocket)

ARI allows VoiceBridge to:

• Create mixing bridges
• Create ExternalMedia channels
• Snoop channels
• Track Stasis lifecycle events

ARI access is authenticated using Basic Auth.

Implementation reference:

• src/main/java/com/mylinehub/voicebridge/ari/AriWsClient.java

This file constructs WebSocket connections and sets:

Authorization: Basic <base64(username:password)>
  

If ARI is exposed publicly, anyone who obtains credentials can manipulate calls.

2. Media Plane — RTP (UDP)

RTP is high-rate UDP traffic. It carries live audio between:

• Asterisk → VoiceBridge (caller audio)
• VoiceBridge → Asterisk (AI speech)

RTP handling is implemented in:

• rtp/RtpPacketizer.java
• rtp/RtpSymmetricEndpoint.java
• rtp/RtpPortAllocator.java

RTP must never be open to arbitrary internet hosts.

ARI Security Model (Intended Production Setup)

ARI Must Be Private

• Bind ARI to private interface only.
• Use HTTPS (WSS) not plain HTTP.
• Firewall ARI port (typically 8089) to VoiceBridge IP only.

Never Expose ARI to Public Internet

ARI is equivalent to remote call control. Public exposure = remote PBX takeover risk.

Do Not Reuse Admin ARI Credentials

Create a dedicated ARI user for VoiceBridge.

Configuration guidance:

• docs/enable_ari.md
• docs/mylinehub-freepbx-config.md

Database-Stored Credentials (Critical Consideration)

VoiceBridge stores runtime configuration in the database:

• models/StasisAppConfig.java
• repository/StasisAppConfigRepository.java
• service/StasisAppConfigService.java

Fields include:

• ari_ws_url
• ari_rest_base_url
• ari_username
• ari_password

Security implication: The database now contains PBX control credentials.

Required DB Protections

• DB must not be public.
• Restrict DB access to VoiceBridge only.
• Encrypt backups.
• Never share production DB dumps casually.

RTP Security Model

Deterministic Port Allocation

RTP ports are allocated via:

• rtp/RtpPortAllocator.java

This allows strict firewall rules.

Symmetric RTP Protection

NAT-safe endpoint learning is handled in:

• rtp/RtpSymmetricEndpoint.java

This prevents one-way audio caused by mismatched source ports.

Never Open Large UDP Ranges

Production rule:

• Allow RTP only between PBX IP and VoiceBridge IP.
• Restrict to known port range.

Firewall Rule Blueprint

Allow

• VoiceBridge → Asterisk ARI (TCP 8089)
• Asterisk → VoiceBridge RTP UDP range
• VoiceBridge → Database (DB port only)
• VoiceBridge → AI provider (outbound only)

Deny

• Public → ARI
• Public → RTP UDP range
• Public → Database

Docker Exposure Considerations

In:

• docker-compose.yml

Ports are mapped for convenience:

• Application port
• RTP UDP port

In production:

• Bind to private network only.
• Use host firewall restrictions.
• Never expose RTP UDP ports globally.

Network Zone Architecture (Recommended)

• PBX Zone — Asterisk / FreePBX
• Media Application Zone — VoiceBridge
• Data Zone — PostgreSQL
• AI Egress Zone — outbound internet access

Each zone communicates only with explicitly required neighbors.

Secrets Handling Best Practices

Environment variables shown in:

• .env.example

Includes:

• AI_API_KEY
• DB credentials
• RTP bind port

Production rule:

• Never commit real secrets.
• Use secure secret storage (vault / env injection).
• Restrict file permissions on .env files.

Operational Security Checklist

• ARI accessible only from VoiceBridge.
• RTP UDP allowed only from PBX IP.
• Database not public.
• HTTPS/WSS enabled for ARI.
• Dedicated ARI user for VoiceBridge.
• Secrets rotated periodically.

Final Security Principle

VoiceBridge must never be treated like a public web app.

It is a real-time telecom control system.

The correct production posture is:

• Minimal exposure
• Explicit firewall rules
• Strict separation of control and media planes
• Credential discipline

If ARI is private and RTP is tightly scoped, your duplex voice system remains both stable and secure.