Security
What the product does to protect calls, accounts and data, stated precisely and where it is enforced, and what a bank, hospital or university still has to add around it.
- Runs on
- Your server, your data
- Passwords
- scrypt, salted
- Secrets at rest
- AES-256-GCM
- Sign-in
- TOTP two-factor, lockout
Layers of protection
Nothing reaches the phone system or the database without passing several independent checks. The firewall decides which ports exist at all. Kamailio screens every SIP request before Asterisk spends any effort on it. nginx terminates HTTPS and adds browser security headers. The dashboard checks the session, the role and the organization on every request. Secrets that must be readable later are encrypted in the database; passwords and one-time links are only stored as hashes.
Control map
Every control below is part of the installed product. The right-hand column says where to look if you want to verify it.
| Control | Enforced in | Where to check |
|---|---|---|
| Closed ports, rate-limited SSH | ufw | scripts/70-firewall.sh |
| Ban of flooding, scanning and password-guessing addresses on all ports | fail2ban, fed by Kamailio's log | fail2ban-kamailio.jail |
| SIP flood detection and per-address ban | Kamailio (pike, ipban table) | kamailio.cfg |
| Wrong-SIP-password ban | Kamailio (authfail table) | kamailio.cfg |
| Scanner tool block | Kamailio (User-Agent match) | kamailio.cfg |
| Premium / satellite number block | Kamailio, PSTN_BLOCK_REGEX | config.env |
| Outside calls per minute, per extension and per trunk | Kamailio, OUTBOUND_MAX_PER_MIN | config.env |
| SIP password check | Asterisk (digest, HA1 only) | pjsip realtime |
| Outgoing / incoming call and transcription switches | Asterisk dialplan (ODBC_PERMS) and the worker | Team → Permissions |
| Which calls are recorded | Asterisk dialplan (ODBC_RECPOLICY) | Organization settings |
| HTTPS only, TLS 1.2+, HSTS, security headers | nginx | webphone.conf |
| Browser phone only for signed-in users | nginx auth_request → dashboard | /sip-ws |
| Internal API unreachable from outside | nginx (404) + shared token | /api/internal/ |
| Sessions, roles, organization scope | Dashboard, on every request | lib/session.ts |
| Sign-in lockout and two-factor | Dashboard | Sign-in page |
| Outbound request address check (SSRF) | Dashboard | Webhooks, channels, IVR API blocks |
| Secrets encrypted at rest | Dashboard (AES-256-GCM) | lib/crypto.ts |
| Audit trail | Dashboard | Organization settings → Audit trail |
| Data retention | Dashboard worker, nightly | Platform settings → Data retention |
| Backups | systemd timer, 02:30 | voip-backup |
Separation between organizations
One installation can serve several organizations (a bank and its subsidiary, several faculties). Each one is a separate world: its own extensions, numbers, menus, queues, recordings, users and history.
- Every organization has its own id. Phone accounts are
<organization>-<extension>, so two organizations can both have extension 1001 without any overlap. - Every call carries its organization (the phone account's, or the dialled number's owner). Dialling, voicemail, queues, IVRs, conference rooms and caller ID are resolved only inside that organization; a user cannot reach another organization's extensions.
- Every dashboard query is limited to the signed-in user's organization; actions on an item first check it belongs to that organization (users, numbers, trunks, IVRs, queues, webhooks, jobs, live calls, conversations, tickets).
- Call detail records, recordings, transcripts and insights are tagged with the organization and only shown inside it.
- Message media is stored in a folder per organization and served only to signed-in people of that organization.
Roles
Every person has exactly one role in one organization. Menus, pages and server actions use the same rule, so hiding a menu entry is never the only protection.
| Role | Can | Cannot |
|---|---|---|
| Admin | Everything in the organization: people, numbers, trunks, IVRs, queues, AI, integrations, settings, the audit trail. | See other organizations or platform settings. There is exactly one Admin per organization; the role is handed over on the server with scripts/add-login.sh, never from the dashboard. |
| Supervisor | Live (listen, whisper, join, hang up), Analytics, everyone's calls, the team list (read-only), plus everything a user can do. | Change routing, people or settings. |
| User | Their own calls, voicemail, transcripts, contacts and phone; Conversations and Tickets of the organization. | See colleagues' calls or recordings, or any administration page. |
| Platform operator | Manage the installation: organizations, platform carrier and numbers, platform settings (sign-in rules, email, retention). | This is a flag on one login (also the Admin of the first organization), not a role in other organizations. |
The Admin makes people supervisors or users on the Team page; nobody can change their own role, and the Admin role cannot be given from there. Each change is audited (user.role).
Accounts and sign-in
| Control | How it works |
|---|---|
| Password storage | scrypt (N=16384, r=8, p=1) with a random 16-byte salt per password. Passwords are never stored or logged in clear. |
| Password rules | At least 10 characters by default (Platform settings → Access, 8 to 64), at most 128. |
| Timing | A sign-in with an unknown email spends the same scrypt time as a real one, and the reply is the same "Wrong email or password", so the form does not reveal which emails have accounts. |
| Brute-force protection | 5 failed sign-ins per account, or 20 per network address, within 15 minutes lock sign-in for 15 minutes. Wrong two-factor codes count too. |
| Two-factor sign-in | TOTP (RFC 6238: HMAC-SHA1, 30-second steps, 6 digits) with any authenticator app; the current code and one step either side are accepted. Each user can turn it on; an Admin can require it for the organization, and the platform operator for every organization. Once required, nobody reaches any page until they have set it up. Admins can reset it for a user who lost their phone. |
| Second-step ticket | After a correct password the browser holds a 5-minute signed ticket (httpOnly, SameSite=Strict) that only the code step accepts; it is never accepted as a session. |
| Sessions | A signed cookie (HS256 with the server's session secret), httpOnly, Secure in production, SameSite=Lax, valid for 12 hours by default (Platform settings → Access, 1 hour to 30 days). On every request the account is re-read from the database, so a deleted login or a removed role takes effect immediately. |
| Password change | Changing or resetting a password signs out every session issued before the change. |
| After sign-in | Only paths on the same site are accepted as the page to return to, so a crafted link cannot send people elsewhere. |
| Sign-up abuse | At most 3 new organizations per network address per hour. Sign-up can be closed in Platform settings or with SIGNUP_ENABLED=no. |
Invitations and password resets
Both are one-time links sent by email. The link carries a random 32-byte token; only its SHA-256 hash is stored, so a copy of the database alone never reveals a working link.
| Link | Valid for | Rules |
|---|---|---|
| Password reset | 1 hour | Works once. At most 5 requests per hour per email or network address. The reply is the same whether or not the email has an account. |
| Invitation | 7 days | Works once. A new link replaces any older unused one. The Admin can resend or withdraw it from the Team page. |
Audit trail
An append-only record per organization, with the person, the action, the target and the network address. Admins read the latest 300 entries under Organization settings → Audit trail. Writing the audit line never blocks the action itself; if the database refuses the line, the error goes to the server log.
| Area | Recorded |
|---|---|
| Sign-in | Sign-in, sign-out, failed sign-ins, wrong two-factor codes, two-factor on / off / reset, two-factor requirement, password changed, reset requested and done, invitation accepted. |
| People | Users created and deleted, invitations sent, resent and withdrawn, logins removed, roles, call permissions, password and SIP password resets. |
| Calls | Every listen, whisper, join and hang-up on a live call; recording paused and resumed; recording policy changes. |
| Routing | Number routing and assignment, SIP trunks, IVR publish and delete, queues, ring groups. |
| Integrations | Webhooks (including secret rotation), API keys created and revoked, message channels (including revealing a bridge secret), files sent in conversations, Self-service API, AI and speech settings, call analysis settings. |
| Tickets | Tickets created, changed and linked; teams created. |
| Platform | Platform settings (access rules, email, retention) and every nightly retention run with what it removed. |
Calls: permissions and recording
Call permissions
The organization switches outgoing calls, incoming calls and transcription & call analysis on or off for everyone (Organization settings). Each person can be set to inherit, on or off (Team → Permissions). Asterisk reads the same values on every call, so a change applies to the next call without a reload.
| Switched off | Effect |
|---|---|
| Outgoing calls | Calls to outside numbers are refused: callers hear "not in service". Extension-to-extension calls still work. |
| Incoming calls | Calls from outside go straight to voicemail for a person; for the whole organization they hear "not in service". |
| Transcription | Recordings are kept, but no transcripts, summaries or topics are produced. |
Recording policy and pause
- Recording is switched on for the installation with
RECORD_CALLS. Each organization then chooses Every call, Calls from outside only, Calls your people make only or No recording (Organization settings → Call recording). - A recorded call produces three files: the caller's side, the other side and both mixed, so a transcript knows who said what.
- An agent can pause the recording of their own call, for example while a customer reads out a card number, and resume it. Every pause and resume is audited with the call id.
- Recordings are files on the server (
/var/spool/voip-recordings), written by Asterisk and readable by the dashboard group only.
Encryption
| Path | Protection |
|---|---|
| Dashboard and API | HTTPS only (HTTP redirects), TLS 1.2 or 1.3, HSTS (1 year, subdomains), no TLS session tickets. |
| Browser phone | Signalling over secure WebSocket (WSS through nginx on 443, or Kamailio on 4443); audio DTLS-SRTP. |
| Desk phones / softphones | SIP over TLS (port 5061, TLS 1.2+, ECDHE with AES-GCM or ChaCha20) is available; SIP over UDP/TCP 5060 is also open for compatibility. Audio to desk phones is plain RTP. |
| Carrier (PSTN) leg | Plain SIP and RTP to the carrier, as with most carriers. Kamailio can reach the platform carrier over TLS and checks its certificate. Use a carrier with private interconnect or TLS/SRTP if you require it. |
| Secrets at rest | AES-256-GCM: carrier passwords, the platform carrier API key, webhook signing secrets, message channel tokens and secrets, AI and speech keys, Self-service API secret, IVR API header secrets, SMTP password and two-factor secrets. |
| Hashes only | Dashboard passwords (scrypt), API keys, invitation and reset links (SHA-256), SIP passwords (the digest hash HA1 that SIP authentication needs). |
| Recordings and database | Stored on the server's disk in clear; use encrypted disks (see below). |
TLS certificates
The same certificate serves nginx, SIP-TLS and WSS. Choose it at install time:
1# public name pointing at the server, port 80 free: a real certificate, renewed automatically2TLS_MODE="letsencrypt"3LETSENCRYPT_EMAIL="it@example.com"4 5# or, for testing: a private CA + server certificate6# import /etc/voip-stack/tls/ca.crt into every client, otherwise browsers reject WSS7TLS_MODE="selfsigned"The encryption key for secrets is derived from the server's SESSION_SECRET (at least 32 characters), which also signs sessions and media links. Keep it out of version control; changing it signs everyone out and makes stored secrets unreadable until they are entered again.
Network edge
Firewall
The installer sets ufw to deny everything incoming except SSH (rate limited), SIP (5060 UDP/TCP, 5061 TLS), WSS (4443), the media range (30000–40000 UDP), and HTTP/HTTPS. Asterisk, the database, the AI agent, the dashboard process and the Asterisk manager interface listen on the server itself only. On a cloud server, open the same ports in the provider's security group; ufw alone is not enough there.
Kamailio
| Protection | Rule | What the attacker sees |
|---|---|---|
| Flood ban | More than 40 requests in 2 seconds from one address bans it for 15 minutes. | Silence: banned addresses are dropped without a reply. |
| Password-guessing ban | More than 8 wrong SIP passwords from one address within 10 minutes bans it for 15 minutes. | Silence. |
| Scanner block | Known attack tools (friendly-scanner, sipvicious, sipcli, sipsak and others) by User-Agent. | Silence. |
| Fraud block list | Numbers matching PSTN_BLOCK_REGEX (premium and satellite ranges by default) are refused before any call is placed. | 403 Destination Blocked |
| Per-extension rate | OUTBOUND_MAX_PER_MIN outside calls per minute per extension and source address (20 by default). | 503 Too Many Calls |
| Per-trunk rate | A cap for the whole platform carrier (10 × the per-extension limit unless set with TRUNK_MAX_PER_MIN). | 503 Too Many Calls |
PSTN_BLOCK_REGEX="^\+(1900|1976|882|883|979|87[0-9])" # numbers matching this are rejected (403)OUTBOUND_MAX_PER_MIN=20 # INVITEs per minute per extensionENABLE_FAIL2BAN="yes"fail2ban watches Kamailio's log for those bans and scanner hits: 5 in 10 minutes block the address on every port for an hour, including the dashboard. Single typos do not count, so a person who mistypes a SIP password once is never locked out of the web. Browser phones are exempt from the Kamailio per-address ban because they all arrive through nginx from the server's own address, and nginx only lets signed-in dashboard users through.
sudo kamcmd htable.dump ipban # addresses Kamailio has bannedsudo fail2ban-client status kamailio # addresses blocked on every portgrep -E "PIKE_BAN|AUTH_BAN|SCANNER|PSTN_BLOCKED|RATE_LIMIT" /var/log/kamailio/kamailio.logToll fraud
- Caller ID for outside calls is set by the system from the organization's configuration, not by the phone.
- Carrier addresses entered for IP-authenticated trunks must be public IPv4, a /24 or narrower, and never the server itself.
- Outgoing calls can be switched off per organization or per person (see Call permissions).
Web server
- Headers on every response:
Strict-Transport-Security,X-Frame-Options: DENY,Content-Security-Policy: frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none',Permissions-Policy(microphone only for the product's own pages; no camera, location or payment),X-Content-Type-Options: nosniff,Referrer-Policy: strict-origin-when-cross-origin, and no server version. - Request bodies are limited to 2 MB, except uploads of sounds and message files (12 MB).
- The internal API used by the AI agent and Asterisk needs a secret token of at least 16 characters, compared in constant time, and nginx answers
404for it from outside.
Outbound requests and integrations
The dashboard makes requests to addresses that admins type in: webhooks, message channel bridges, IVR API blocks, the Self-service API, custom speech and AI servers. Each address is checked before use, to stop the server being used to reach things that are not on the internet (server-side request forgery).
- https only, and no user name or password inside the URL.
- The host name is resolved and refused if any address is private, loopback, link-local (including the cloud metadata address
169.254.169.254), carrier-grade NAT (100.64.0.0/10), multicast or reserved, or an IPv6 local, link-local or mapped address. - Media downloads and webhook deliveries do not follow redirects, so a public URL cannot bounce the request to an internal one.
- On-premises installations that must post to internal systems can set
WEBHOOK_ALLOW_PRIVATE=yes; this lifts the address check (and allows plainhttp) for every outbound integration on that installation.
| Integration | How the receiver can trust it |
|---|---|
| Webhooks | X-Voip9-Signature: v1= HMAC-SHA256 over the timestamp and the raw body, with X-Voip9-Timestamp. Secrets can be rotated. |
| Message bridges | Signed the same way with the channel's own secret. |
| WhatsApp inbound | Meta's X-Hub-Signature-256 is checked against the App secret when one is saved; the URL also carries a random channel token. |
| REST API | Keys (v9k_…) are stored as SHA-256 hashes, carry scopes (read, write, calls:place) and can be revoked. |
| Signed media links | Files sent to a bridge are reachable without a login for one hour through a link signed with HMAC-SHA256; only outgoing files are ever served, and a changed or expired link answers 404. |
Data retention
The platform operator sets how long data is kept under Platform settings → Data retention. 0 days means keep forever, which is the default. The worker applies the rules once a night after 03:00 and writes what it removed to the audit trail.
| Data | Kept | What is removed |
|---|---|---|
| Call recordings | Recordings days (0–3650) | The audio files. The call stays in the history without its recording. |
| Transcripts and AI insights | Transcripts days | Transcripts, summaries, topics and sentiment. |
| Call history | Call history days | Call detail records and the queue log. |
| Voicemail | Voicemail days | Messages older than the limit. |
| Recordings (installer) | RECORDING_DAYS, 30 by default | A daily cron job also deletes recording files older than this. |
| Webhook delivery history | 30 days | Finished deliveries. |
| Background job history | 14 days | Finished and failed jobs. |
| Kamailio and AI agent logs | 14 days | Rotated daily and compressed. |
| Audit trail | Until you delete it | Nothing; set your own policy. |
# in /etc/voip-stack/dashboard.env, then restart the dashboardRETENTION_DRY_RUN=1Backups
voip-backup.timer runs a full backup every night at 02:30 into /var/backups/voip-stack/<date>/ and keeps 14 days (set BACKUP_DIR and KEEP_DAYS in /etc/voip-stack/backup.env). The System health page shows the last result.
| File | Contains |
|---|---|
asterisk.sql.gz | Users, settings, call history, voicemail, conversations, tickets, audit trail. |
kamailio.sql.gz | Trunks and registrations. |
recordings.tgz | Call recordings. |
sounds.tgz | Sounds, IVR prompts and message media. |
config.tgz | /etc/voip-stack (including secrets), Asterisk, Kamailio, nginx and rtpengine configuration, TLS certificates. |
Run a backup by hand
Shell sudo voip-backupCheck the result
Shell cat /var/backups/voip-stack/latest.jsonCopy it off the server
Use your own tooling (for example an encrypted object store or backup agent). The product does not ship backups anywhere by itself.
What we do not claim, and what you should add
The product is not certified against PCI DSS, ISO 27001, SOC 2 or HIPAA out of the box. Certification covers your whole operation (people, processes, hosting), so it is achieved by the deploying organization. The table maps typical expectations of a bank, hospital or university to what is built in and what your team adds.
| Area | Built in | You add |
|---|---|---|
| Access control | Roles, one Admin per organization, two-factor (enforceable), lockout | Joiner / leaver process, periodic access review |
| Logging & monitoring | Audit trail, delivery and job history, Kamailio security log | Ship logs and the audit table to your SIEM; alert on failed sign-ins and listen-in events |
| Encryption | TLS everywhere on the web, DTLS-SRTP for browsers, AES-256-GCM for secrets | Encrypted disks (e.g. EBS encryption), TLS/SRTP phones, encrypted carrier link |
| Data protection | Organization isolation, recording policy and pause, retention rules | Customer consent notices for recording, a retention policy that fits your regulator |
| Availability | Several Asterisk instances with automatic failover, nightly backups | Off-server backup copies and tested restores, a second server or region |
| Network | Minimal open ports, loopback-only internals, flood and fraud controls | Database on a private network, management access via VPN |
| Assurance | Security-focused defaults | Independent penetration test before production, regular patching |