Security Architecture & Threat Model

AiPBX turns standard Linux servers into high-concurrency telecommunications appliances. Real-time telephony traffic demands specialized security considerations: SIP signaling and RTP audio streams must maintain predictable low latency while defending against global automated scanner traffic, credential brute-force attacks, toll fraud, eavesdropping, and data leakage.

This document details AiPBX's defense-in-depth threat model, trust boundaries, credential handling, data retention lifecycle, and AI permissions guardrails.

1. Trust Boundaries & Architecture Map

AiPBX separates untrusted public networks from internal telephony cores via strict architectural layers:

[ UNTRUSTED INTERNET / CARRIERS / CLIENTS ]
     │
     ├─► [ Port 443 Ingress (Nginx TCP Stream with ALPN) ] ──(Loopback / TLS)──► Apache 2.4 / Web Portal & WebRTC WSS
     ├─► [ Public SIP 5060/5061 (Restricted via Rich Rules) ] ───────────────► Asterisk 22 Core (PJSIP)
     ├─► [ Media RTP 10000-20000 / UDPTL 4100-4999 (SRTP / DTLS) ] ─────────► Asterisk Media Engine
     └─► [ TURN / STUN Relay 5349 ] ─────────────────────────────────────────► coturn (Ephemeral Tokens)
                                                                                     │
[ RESTRICTED LOCALHOST / OS BOUNDARY ]                                              │
     ├─► Asterisk AMI (127.0.0.1:5038, strong password, root/asterisk only)          │
     ├─► Asterisk WSS (127.0.0.1:8088/ws, isolated from public binding)              │
     ├─► MariaDB Database (127.0.0.1:3306, strict permissions) ◄────────────────────┘
     ├─► Go Instant Messaging Core (127.0.0.1:8086/ws)
     └─► Local AI Inference Engine (Whisper STT / Piper TTS / Ollama on loopback)

2. Threat Analysis & Mitigations

2.1. SIP Exposure & Scanner Protection

2.2. WebRTC, Media & Session Credentials

2.3. Data Retention Lifecycle & PII Privacy

Telecommunications metadata and call recordings are strictly governed under the built-in Privacy & GDPR Engine:

• Pre-Call Consent & Periodic Beep: Inbound routes support automated pre-call disclosures, explicit DTMF Opt-In (1) / Opt-Out (9), and periodic FCC-compliant beeps (MixMonitor ,B(15)) for two-party consent jurisdictions.
• Automated Nightly Purge (privacy_purge.php): Nightly cron jobs at 03:45 enforce retention limits configured by administrators (e.g., 90 days for GDPR, 180 days for KVKK):
  • Permanently deletes expired audio recordings (/var/spool/asterisk/monitor/) and voicemail audio.
  • Deletes expired AI speech-to-text transcripts, fax spool files, and chat messages.
  • Pseudonymizes / anonymizes expired CDR rows (src = 'REDACTED', dst = 'REDACTED', clid = 'REDACTED'), preserving aggregate analytics without retaining personal phone numbers.
• Subject Access Requests (SAR) & Right to Erasure: Administrators can export a full JSON package of all records associated with a phone number or execute an immutable cryptographic erasure covering CDRs, voicemails, faxes, and recordings.

2.4. Mobile Push Notifications & Token Handling

AiPBX mobile softphones (Android and iOS) utilize push notifications for background battery efficiency:

1. Token Storage: Device push tokens (Apple APNs and Google FCM) are stored in the PBX database linked to the user's extension. Tokens are never exposed in public API responses.
2. Payload Minimization: Push notification payloads are designed with data minimization in mind. Call signaling payloads contain ephemeral correlation UUIDs. In strict privacy modes, personal caller names and numbers are omitted from the push body and fetched securely over TLS upon app activation.
3. Transport Security: Push dispatches connect directly to official Apple/Google gateway endpoints over mutual TLS / HTTP/2 using authenticated administrator-managed APNs tokens and FCM keys.

2.5. AI Assistant Permissions & Least Privilege (AI Guardrails)

Integrating AI assistants into communications systems requires strict boundaries to prevent data leakage and privilege escalation (following the principle of Least Privilege / AI-OS workflow isolation):

• Local-First Execution: AiPBX defaults to entirely on-premise AI models: Whisper for speech recognition, Piper for text-to-speech, and local LLMs (via Ollama) running on loopback. Audio and transcriptions never leave the local PBX host.
• Cross-Border Cloud AI Lock: Checking Lock outbound Cloud AI services in /privacy hard-disables all external Cloud AI providers. Any attempt by dialplan or background workers to query third-party APIs is blocked at the code level.
• Real-Time PII & Payment Card Redaction: Before any transcript is saved to the database or processed by an LLM, PrivacyService::redactTranscriptPii() inspects the text and automatically redacts:
  • Luhn-validated payment card numbers (13–19 digits) → [REDACTED-CARD]
  • CVV / CVC codes → [REDACTED-CVV]
  • 11-digit national identity numbers → [REDACTED-ID]
• Restricted Telephony Execution Sandbox: The AI voice assistant operates within an isolated Asterisk AGI execution boundary. It has no filesystem write permissions, cannot access the MariaDB root credentials, cannot execute shell commands, and is restricted solely to dialplan telephony primitives (queue transfer, extension routing, hangup, audio playback).

2.6. Operating System & Process Privilege Separation

• Unprivileged Web Runtime: The web portal runs under www-data. It cannot modify system services, firewall rules, or Asterisk configuration files directly.
• Audited Privilege Helper (aipbx-priv): Privileged operations (such as reloading Asterisk, restarting services, generating Let's Encrypt certificates, or triggering backups) are mediated via /usr/local/sbin/aipbx-priv, a strictly audited wrapper with sudoers whitelisting and rigid parameter validation.
• Encrypted Database Secrets: Sensitive third-party credentials (SMTP passwords, S3 storage keys, external database passwords) are AES-encrypted in the database using /var/lib/aipbx/settings.key, which is readable only by the root user and the application process.

3. Security Hardening Checklist for Administrators

For production environments, follow these four hardening recommendations:

1. Carrier IP Whitelisting: On the Firewall page, remove open 5060/5061 ports and allow only your SIP trunk provider's IP subnets and internal office networks.
2. SSH Hardening: Disable password authentication in /etc/ssh/sshd_config (PasswordAuthentication no) and use Ed25519 SSH keys.
3. Automated Backups: Verify that aipbx-backup is running daily and configure AIPBX_BACKUP_COPY_TO in /etc/ai-pbx.env for automated off-site replication.
4. Cloud AI Lock: If handling regulated healthcare (HIPAA) or payment (PCI-DSS) calls, enable the Cloud AI Lock and verify automated nightly retention purge on the GDPR & Privacy page.