{"id":135,"date":"2026-04-24T19:54:50","date_gmt":"2026-04-24T19:54:50","guid":{"rendered":"https:\/\/phonesstillexist.com\/?p=135"},"modified":"2026-05-12T16:13:21","modified_gmt":"2026-05-12T16:13:21","slug":"hardening-freeswitch-a-production-baseline-for-day-one","status":"publish","type":"post","link":"https:\/\/phonesstillexist.com\/index.php\/2026\/04\/24\/hardening-freeswitch-a-production-baseline-for-day-one\/","title":{"rendered":"Hardening FreeSWITCH: A Production Baseline for Day One"},"content":{"rendered":"\n
\"Hardening<\/figure>\n\n\n\n

Updated April 2026: substantial rewrite. The hardening script and this post now reflect what we actually see hitting public-IP FreeSWITCH boxes \u2014 two distinct attack patterns (credential brute-force and unauthenticated INVITE floods), and three failure modes that make a default fail2ban setup look like it’s working when it isn’t. New Section 1 explains the attack landscape; Section 7 describes the consolidated single-jail design that catches both patterns; new Section 9 covers ban enforcement (which on Debian 12 minimal images requires explicitly installing iptables \u2014 a step the script now handles automatically).<\/em> <\/p>\n\n\n\n

If you don’t feel like reading, the script can be found here: https:\/\/github.com\/thevoiceguy\/freeswitch_tools\/blob\/main\/harden-freeswitch.sh<\/a><\/p>\n\n\n\n

A default FreeSWITCH installation is powerful, flexible, and easy to get running \u2014 which is exactly why it shouldn’t stay in its default state for long. Fresh installs ship with well-known default passwords, an admin socket that trusts the entire local network, and authentication-failure logging turned off. Automated SIP scanners sweep the public internet around the clock, looking for precisely this configuration, and when they find it, the result is almost always toll fraud: attackers register to your server, route international calls through it, and leave you with the bill. A single compromised FreeSWITCH instance can generate tens of thousands of dollars in fraudulent charges over a single weekend.<\/p>\n\n\n\n

To make the cleanup pass less tedious, I put together a script that automates the whole process. You can grab it from my GitHub: harden-freeswitch.sh<\/a>. It’s a practical post-install hardening pass for FreeSWITCH on Debian or Ubuntu \u2014 it doesn’t try to solve every security concern, but it closes the biggest, most commonly exploited holes immediately after installation while keeping FreeSWITCH fully usable.<\/p>\n\n\n\n

Why FreeSWITCH Hardening Matters<\/h3>\n\n\n\n

FreeSWITCH often sits at the edge of real-time communications infrastructure. It may accept SIP registrations, process inbound calls, route outbound calls, expose management access through Event Socket, and handle RTP media streams. That combination \u2014 network-exposed, powerful, and directly connected to paid services \u2014 makes it a high-value target.<\/p>\n\n\n\n

Leaving defaults in place creates avoidable risk. Default passwords, exposed management services, missing firewall rules, and incomplete logging make it trivial for attackers to probe the system without being blocked or even noticed. The goal of this script is simple: reduce the obvious attack surface immediately after installation while keeping FreeSWITCH usable.<\/p>\n\n\n\n

This is a baseline, not a finish line. Production deployments should go further with per-extension passwords, SIP-TLS, dialplan restrictions, and proper monitoring. But none of that matters if the basics aren’t covered first.<\/p>\n\n\n\n

How SIP Boxes Actually Get Attacked<\/h3>\n\n\n\n

Before walking through what the script does, it’s worth understanding what<\/em> it’s defending against. There are two distinct attack patterns that will hit your box within minutes of it touching the public internet, and each one looks different in the logs. A defense that only catches one of them will leave you mostly exposed.<\/p>\n\n\n\n

Pattern 1: Credential brute-force.<\/strong> A scanner tries to authenticate against your server with guessed or stolen credentials. Each attempt produces a SIP auth failure<\/code> line in the FreeSWITCH log, with the source IP, when log-auth-failures<\/code> is enabled. This is the classic attack pattern that most fail2ban-FreeSWITCH guides describe.<\/p>\n\n\n\n

Pattern 2: Unauthenticated INVITE floods.<\/strong> A scanner sends INVITE after INVITE \u2014 typically targeting expensive international destinations \u2014 without ever attempting to authenticate. FreeSWITCH responds to each INVITE with a 401 challenge asking for credentials. The scanner ignores the challenge, abandons the call, and immediately fires the next INVITE from a different source port. This pattern produces no SIP auth failure<\/code> lines at all.<\/strong> It generates only SIP auth challenge<\/code> events, which a typical fail2ban filter doesn’t match.<\/p>\n\n\n\n

This second pattern is now the dominant one in the wild. On a real public-IP FreeSWITCH box, it accounts for the overwhelming majority of attack traffic \u2014 often hundreds of probes per minute from a single attacker rotating through source ports. The scanner is testing whether your dialplan will route calls without authentication. Most boxes won’t, which is why these probes look like waste \u2014 but the cost to the attacker is so low (a single UDP packet per probe) that they keep doing it forever, hoping to find the one misconfigured server that does.<\/p>\n\n\n\n

A defense that only watches for SIP auth failure<\/code> would have caught a tiny fraction of this traffic. The script’s filter watches for both<\/em> SIP auth failure<\/code> and SIP auth challenge<\/code> events, with thresholds set so that legitimate users (who generate a few challenges per registration cycle) never trigger it, but a scanner generating 20 events in 5 minutes does. More on that in Section 7.<\/p>\n\n\n\n

There is also a third pattern worth knowing about, even though we don’t directly defend against it at this layer: credential stuffing using harvested credentials<\/strong>. If an attacker already has valid SIP credentials (from a leaked database, a compromised softphone, or a misconfigured PBX they took over previously), they will skip both of the above patterns entirely and just place calls. The defense against this is per-extension passwords, dialplan restrictions, and outbound call monitoring \u2014 covered briefly in “What This Script Does Not Cover.”<\/p>\n\n\n\n

1. Back Up the FreeSWITCH Configuration<\/h3>\n\n\n\n

Before changing anything, the script creates a timestamped tarball of the entire FreeSWITCH configuration directory and saves it under \/root<\/code>.<\/p>\n\n\n\n

This matters because hardening touches critical files, including vars.xml<\/code>, event_socket.conf.xml<\/code>, and both SIP profile configurations. If something breaks, you need a clean way to roll back. The script also leaves a .bak<\/code> copy of each file it modifies, giving you two levels of recovery: per-file rollback for small mistakes, and full restore from the tarball for anything bigger.<\/p>\n\n\n\n

2. Replace the Default SIP Password<\/h3>\n\n\n\n

FreeSWITCH’s default dialplan references a shared variable called default_password<\/code> in vars.xml<\/code>, set out of the box to the string 1234<\/code>. Every example extension in the default directory inherits this value. If it is left alone, anyone who knows FreeSWITCH (which is to say, every attacker on the internet) has a working password for every default user.<\/p>\n\n\n\n

The script generates a strong 28-character random password using openssl rand<\/code> and replaces the default in vars.xml<\/code>. The original file is preserved as vars.xml.bak<\/code>.<\/p>\n\n\n\n

One caveat worth knowing: this only rotates the shared default. If you have already provisioned extensions with their own passwords in directory\/default\/*.xml<\/code>, those are not touched, and in production, you should be using per-extension passwords anyway.<\/p>\n\n\n\n

3. Replace the Event Socket Password<\/h3>\n\n\n\n

The Event Socket (ESL) is FreeSWITCH’s admin control interface. It can run any FreeSWITCH command, originate calls, inspect live state, and script complex call flows. By default, it accepts the password ClueCon<\/code> \u2014 a value that is not a secret to anyone who has ever touched FreeSWITCH.<\/p>\n\n\n\n

The script generates a second random password and rotates the ESL credential. Unauthorized ESL access is not a minor issue \u2014 it is full control of the FreeSWITCH instance, including the ability to place calls through any configured gateway.<\/p>\n\n\n\n

4. Bind Event Socket to Loopback<\/h3>\n\n\n\n

In addition to rotating the Event Socket password, the script changes the listen-ip<\/code> parameter to 127.0.0.1<\/code>. The management interface is now reachable only from the server itself, not from the wider network.<\/p>\n\n\n\n

This is one of the highest-value changes in the entire script. Even with a strong password, management interfaces should not be exposed to networks that do not need access to them. If you need remote ESL access, tunnel it over SSH \u2014 do not expose it directly.<\/p>\n\n\n\n

5. Enable SIP Authentication Failure Logging<\/h3>\n\n\n\n

This is the single most important and most overlooked hardening step, and it deserves its own explanation.<\/p>\n\n\n\n

By default, FreeSWITCH does not write the WARNING line that Fail2Ban needs to match. The auth failures still happen \u2014 the call is rejected \u2014 but the log line that contains the source IP never appears. Fail2Ban can’t ban an IP it never sees. This is why so many administrators install Fail2Ban with the FreeSWITCH jail enabled, watch it sit there with zero hits for weeks, and conclude that “Fail2Ban doesn’t work with FreeSWITCH.” Fail2Ban is fine. There is simply nothing in the log for it to match.<\/p>\n\n\n\n

The script flips log-auth-failures<\/code> to true<\/code> on both SIP profiles:<\/p>\n\n\n\n

sip_profiles\/internal.xml\nsip_profiles\/external.xml<\/code><\/pre>\n\n\n\n
If the parameter is already present and set to false<\/code>, the script updates it. If it is missing entirely, the script injects it before the closing <\/settings><\/code> tag. The result either way is that failed SIP authentication events now produce log lines that Fail2Ban can actually act on.<\/p>\n\n\n\n
6. Store the Generated Credentials Securely<\/h3>\n\n\n\n
New passwords are only useful if you can find them again. The script writes both the new SIP password and the new Event Socket password to:<\/p>\n\n\n\n
\/root\/freeswitch-credentials.txt<\/code><\/pre>\n\n\n\n
The file is created with umask 077<\/code> and chmod 600<\/code> so only root can read it. You’ll need these values later to reconfigure SIP clients and any scripts that talk to the Event Socket, and this is a safer place for them than shell history or a scratchpad. Ultimately, you should move these credentials into a proper password vault (1Password, Bitwarden, HashiCorp Vault, etc.) and delete the file from the server entirely. A plaintext credentials file on disk is a convenience, not a long-term storage plan.<\/p>\n\n\n\n
7. Install and Configure Fail2Ban<\/h3>\n\n\n\n
The script installs Fail2Ban and configures a single FreeSWITCH jail tuned to catch both attack patterns described in the opening section. The jail thresholds are:<\/p>\n\n\n\n
maxretry  = 20\nfindtime  = 300\nbantime   = 86400\nbanaction = iptables-allports<\/code><\/pre>\n\n\n\n
Twenty SIP authentication events from the same IP within five minutes earns a 24-hour ban across all ports.<\/p>\n\n\n\n
Why these numbers? Two reasons.<\/p>\n\n\n\n
The threshold of 20 in 5 minutes is permissive on purpose.<\/strong> The filter matches both SIP auth failure<\/code> (Pattern 1) and SIP auth challenge<\/code> (Pattern 2). Including challenge events is essential for catching the unauthenticated-INVITE-flood pattern, but it would false-positive on legitimate users at low thresholds \u2014 every real INVITE generates a challenge as the normal first step of authentication. A real softphone produces only a handful of challenges per registration cycle, with cycles an hour or more apart. A scanner produces 20 challenges in seconds. The threshold sits in that gap.<\/p>\n\n\n\n
The bantime of 24 hours, with iptables-allports<\/code>, makes a single ban materially expensive for the attacker.<\/strong> A scanner that gets banned has to burn a fresh IP per probe \u2014 they can’t just wait out a one-hour ban and resume. Combined with the recidive jail in Section 8, a sustained attacker quickly runs out of usable IPs.<\/p>\n\n\n\n
There is one detail that catches many fail2ban-on-FreeSWITCH setups by surprise. The Fail2Ban package ships a \/etc\/fail2ban\/filter.d\/freeswitch.conf<\/code> by default, but its regex does not match FreeSWITCH 1.10.x log output, which now includes a CPU-usage percentage between the timestamp and the [WARNING]<\/code> tag. The script overwrites this file with a working regex that matches the current format. It specifically avoids using a .local<\/code> override with before = freeswitch.conf<\/code>, which creates a recursive include loop and crashes Fail2Ban with “maximum recursion depth exceeded.”<\/p>\n\n\n\n
A note on the banaction. Fail2Ban’s default is iptables-multiport<\/code>, which only blocks TCP. SIP scanner traffic on 5060\/UDP would walk right through TCP-only ban rules. The script sets banaction = iptables-allports<\/code> explicitly so bans cover all ports and protocols. This sounds like a small detail; on a SIP server it is the difference between actually blocking attackers and just logging them.<\/p>\n\n\n\n
8. Catch Repeat Offenders With a Recidive Jail<\/h3>\n\n\n\n
A 24-hour ban is much better than a one-hour ban, but persistent scanners simply wait it out. Fail2Ban’s recidive<\/code> jail solves this by watching Fail2Ban’s own log and escalating any IP that gets banned multiple times.<\/p>\n\n\n\n
The script enables recidive with these parameters:<\/p>\n\n\n\n
bantime   = 604800   (7 days)\nfindtime  = 86400    (24 hours)\nmaxretry  = 3\nbanaction = banaction_allports<\/code><\/pre>\n\n\n\n
Translation: any IP that gets banned three times across any jail within 24 hours gets banned for a week, across all ports. A persistent scanner that probes both SIP and SSH gets locked out of both at once.<\/p>\n\n\n\n
There is no false-positive risk. Recidive only escalates IPs that Fail2Ban has already<\/em> banned multiple times. A legitimate user would have to get banned by the freeswitch jail three separate times within 24 hours to trigger recidive \u2014 extraordinarily unlikely for anyone who is not an attacker.<\/p>\n\n\n\n
In testing on a real public-IP box, recidive immediately picked up persistent scanner IPs the moment it started watching the historical log \u2014 IPs the freeswitch jail had banned and unbanned multiple times over previous days. Recidive identified them as repeat offenders and escalated them to week-long all-port bans within seconds. That is what “the same handful of attackers keep coming back” looks like in concrete numbers.<\/p>\n\n\n\n
9. Make Sure Bans Are Actually Enforced<\/h3>\n\n\n\n
Fail2Ban can run, log bans, and appear<\/em> fully functional while enforcing absolutely nothing. The daemon will say Currently banned: 9<\/code> in its status output, the filter will match millions of log lines, and not a single attacker IP will be dropped at the kernel level. There are at least three ways this happens:<\/p>\n\n\n\n
The kernel firewall framework is missing the userspace tool.<\/strong> Debian 12 minimal cloud images use nftables as the kernel firewall framework, but they do not install the iptables<\/code> userspace command by default. Fail2Ban’s default banactions all shell out to iptables<\/code>. Without it, the banaction commands silently fail; the ban gets recorded in Fail2Ban’s database, but no kernel rule is ever created. The script always installs iptables<\/code> (which on Debian 12 is the iptables-nft compatibility shim), regardless of whether the script is also configuring UFW. Without iptables present, the rest of Fail2Ban is decorative.<\/p>\n\n\n\n
The default banaction doesn’t match the protocol of the attack.<\/strong> As noted in Section 7, Fail2Ban’s default iptables-multiport<\/code> banaction creates TCP-only rules. SIP scanner traffic on UDP ports walks right past it. The script sets banaction = iptables-allports<\/code> on the freeswitch jail to drop all traffic from banned IPs, regardless of port or protocol.<\/p>\n\n\n\n
Fail2Ban’s reload doesn’t reliably swap banactions.<\/strong> Editing a jail config and running fail2ban-client reload<\/code> doesn’t always replace the previously-active banaction with the new one. Sometimes both end up active simultaneously and conflict. The script handles this on every run by stopping fail2ban, flushing existing iptables state, and starting fail2ban fresh \u2014 guaranteeing a clean state regardless of what was there before.<\/p>\n\n\n\n
To catch all of these failure modes, the script ends with a runtime verification step. It places a test ban on 192.0.2.99<\/code> (a documentation-reserved IP that no legitimate traffic ever uses), checks that an iptables rule appeared in the kernel, then unbans it. The output is one line:<\/p>\n\n\n\n
>>> Confirmed: bans are enforced at the iptables level.<\/code><\/pre>\n\n\n\n
If you don’t see that line \u2014 if instead you see a warning that “bans are being LOGGED but NOT ENFORCED” \u2014 something is wrong and you need to fix it before walking away. This single check would have surfaced every one of the failure modes above within seconds.<\/p>\n\n\n\n
10. Make Fail2Ban Work on Minimal Debian Systems<\/h3>\n\n\n\n
Fail2Ban’s default SSH jail reads \/var\/log\/auth.log<\/code>, which minimal Debian cloud images often do not create because logging is routed through journald. The script installs rsyslog<\/code> to produce the expected log file, installs python3-systemd<\/code> so Fail2Ban can also read directly from the journal, and pins the SSH jail to the systemd backend as a belt-and-suspenders measure:<\/p>\n\n\n\n
[sshd]\nbackend = systemd<\/code><\/pre>\n\n\n\n
This is not strictly a FreeSWITCH-specific step, but it supports the overall goal: make sure host-level protection starts correctly and is actually watching the right log sources. A Fail2Ban installation that silently fails to start is worse than no Fail2Ban at all, because it creates the illusion of protection.<\/p>\n\n\n\n
11. Configure UFW Firewall Rules<\/h3>\n\n\n\n
The script resets UFW to a clean state and applies a default-deny inbound policy. It then opens only what FreeSWITCH actually needs:<\/p>\n\n\n\n