Security

The design in one sentence: only the edge faces the internet, and only on two ports. Everything else stays home.

#Network design

Only the edge server faces the internet — TLS port 5061 plus the audio ports. The PBX has no ports forwarded to it at all. Router forwards go to the edge, never the PBX.

#Edge server

• TLS only — no plaintext SIP from the internet.
• Known scanners dropped on sight.
• Flood limit: more than ~30 requests in 2 seconds from one IP is dropped on the spot, and a second fail2ban jail (kamailio-edge-flood) bans that IP for 24 hours.
• fail2ban: 8 failed sign-ins or junk requests in 10 minutes → banned 1 hour. A failed sign-in only counts when a phone actually sent a password and was refused — the normal first 401 challenge isn't counted, and stale nonces are ignored. Your LAN is never banned.
• Every ban shows on the dashboard and is emailed. Lift one on the edge with fail2ban-client unban <ip>.

#Panel

• Passwords and sessions: bcrypt passwords. Sessions expire after 3 hours idle or 12 hours total, and end immediately when a user is disabled, demoted or changes password.
• Sign-in lockouts: 10 failures per address, or 20 per username, in 15 minutes locks that address or username for 15 minutes.
• Admin pages: home network only.
• Single sign-on (optional): OpenID Connect authorization code flow with PKCE, a state bound to the browser and a nonce; the ID token's issuer, audience, expiry and nonce are checked. Same lockouts and sign-in log as passwords (entries say “single sign-on”). Never creates accounts; admins can be kept to passwords. See Sign-on.
• Page protection: CSRF tokens on every form, security headers against framing and clickjacking, 25 MB upload limit.

#Server hardening

• Code, Python environments and helper scripts are root-owned; the service account can't change them.
• The database is readable by the PBX services only (mode 600).
• Asterisk's own API (ARI) listens on the PBX itself only (127.0.0.1), behind a long random password — it's never exposed to the network.
• The kill switch and safety lock can also be driven over the API, and the kill switch bypasses the safety lock — an emergency stop always works.

#Emergency tools

• Kill switch — hangs up every call and disconnects every phone at once (toll-fraud response).
• Safety lock — freezes admin changes only, or everything including My Phone.
• Per-user block lists and reports — users block numbers themselves; reports land with the admin.

#Staying safe over time

• Run scripts/security-check.sh on both servers regularly — it reports pending security updates, open ports, SSH settings, permissions and vulnerable Python packages.
• Keep Debian, Asterisk (latest 22.x) and Kamailio updated: apt-get update && apt-get upgrade.
• Scan your public IP from outside (e.g. an online port scanner on mobile data). Only TCP 5061 should be open.
• Turn off SSH root password logins once setup is done.