Docs Feed fail2ban from sipnab

Feed fail2ban from sipnab

Run sipnab's scanner and registration-flood detectors as a service and have fail2ban ban what they find, with the filter and jail that ship with sipnab.

On this page

fail2ban bans the addresses that a log names. sipnab can write that log.

  • sipnab has a scanner detector and a registration-flood detector.
    • Each finds attackers in the SIP traffic sipnab captures.
  • With --fail2ban, sipnab writes one line for each detection.
  • The filter and jail in sipnab’s contrib/fail2ban turn those lines into bans.
  • sipnab writes the lines. fail2ban decides and bans.

sipnab’s lines come from the traffic it captures, not from your SIP server’s log.

This guide starts where Ban SIP scanners with fail2ban ends, before its uninstall. OpenSIPS, fail2ban and the two test addresses are in place.

What sipnab writes

Two kinds of line, one per detection:

2026-10-01 03:49:45 sipnab[17157]: scanner_detected src=198.51.100.60 ua="friendly-scanner" method="OPTIONS"
2026-10-01 03:51:13 sipnab[17540]: reg_flood src=198.51.100.60 count=51
  • scanner_detected comes from the scanner detector, --kill-scanner.
    • sipnab quotes ua and method.
  • reg_flood comes from the registration-flood detector, --reg-flood.
    • count is how many REGISTERs with credentials the registrar refused from that address within one second.
    • Out of the box the threshold is 50.
    • sipnab writes a line for each refusal past it.
    • So 80 refusals in a burst write 30 lines, count=51 to count=80.

--fail2ban itself detects nothing. It only chooses the format. Without a detector beside it, sipnab warns when it starts that no detector is running, so this run will emit nothing.

Know what --kill-scanner sends.

  • On a live capture, the scanner detector also answers the scanner requests it detects.
    • It answers from a separate process.
  • The answer is a 200 OK.
    • It carries your SIP server’s address and port as its source.
  • Watching the scanner’s side, the request OpenSIPS ignored on purpose got an answer within milliseconds:
03:50:04.370537 IP 198.51.100.60.54184 > 192.0.2.10.5060: SIP: OPTIONS sip:192.0.2.10 SIP/2.0
03:50:04.383978 IP 192.0.2.10.5060 > 198.51.100.60.54184: SIP: SIP/2.0 200 OK

So with sipnab running this way, a scanner learns that something answers on your SIP port. That is true even when your SIP server answers nothing.

To ban scanners without answering them, use --kill-scanner-detect-only in place of --kill-scanner. It runs the same scanner detector and writes the same scanner_detected lines, and sipnab sends nothing to the scanner. This option is newer than the tests below. See Detect scanners without answering them.

Before you start

  • The machine as Ban SIP scanners with fail2ban leaves it before its uninstall: OpenSIPS, fail2ban, nftables and the two test addresses.
  • root on that machine. The steps use sudo.
  • No other system changes. The ban is in this machine’s own firewall.
  • What a scanner sees does change with --kill-scanner: sipnab answers its requests with a 200 OK that carries your SIP server’s address. With --kill-scanner-detect-only sipnab sends nothing.

Tested on

Every block on this page ran as written, in order, on 2026-10-01. So did every command in the table in “Operate it”.

  • They ran with sipnab 0.5.199 from its release package.
  • They ran with the contrib/fail2ban files as this version of the page describes them.
  • They ran on the machines the fail2ban guide ran on:
    • clean x86_64 virtual machines with 2 cores and 3 GB of memory,
    • Debian 13 (kernel 6.12.111) and Ubuntu 24.04 (kernel 6.8.0).
  • They ran right after that guide’s section “Watch a password guesser get banned, and the ban run out”.
  • The section “Ban with iptables instead of nftables” ran on both.
    • Debian 13’s iptables package is 1.8.11 and reports (nf_tables).
  • A capture on both showed the answer --kill-scanner sends.

On 2026-11-03 the filter and the jail ran again against sipnab 0.5.232, built from source, without the rest of the page:

After four scanner_detected src=203.0.113.42 lines the jail counted Total failed: 4 and banned nobody. The fifth banned 203.0.113.42, and nftables held the set addr-set-sipnab. No SIP server, phone or network namespace took part.

Install sipnab

# Run all of these, in order.
V=$(curl -fsSL https://api.github.com/repos/NormB/sipnab/releases/latest \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["tag_name"].lstrip("v"))')
A=$(dpkg --print-architecture)
curl -fsSLO https://github.com/NormB/sipnab/releases/download/v$V/sipnab_${V}_${A}.deb
curl -fsSL https://github.com/NormB/sipnab/releases/download/v$V/SHA256SUMS.txt \
  | grep " sipnab_${V}_${A}.deb$" | sha256sum -c -
sudo apt-get install -y ./sipnab_${V}_${A}.deb

The package installs a service that runs sipnab as the sipnab user. The service captures on every interface. The package does not start it.

Run sipnab with its detectors, writing the log

A drop-in does two things:

  • It adds the two detectors and --fail2ban to the packaged command.
  • It sends sipnab’s standard output, where the lines go, to /var/log/sipnab.log.
    • That is the file the contrib jail reads.

sipnab’s own messages, on standard error, stay in the journal:

# Run all of these, in order.
sudo mkdir -p /etc/systemd/system/sipnab.service.d
sudo tee /etc/systemd/system/sipnab.service.d/fail2ban.conf >/dev/null <<'EOF'
[Service]
ExecStart=
ExecStart=/usr/bin/sipnab -N -d any --no-cli-print --syslog --metrics 127.0.0.1:9090 \
  --kill-scanner --reg-flood --fail2ban
StandardOutput=append:/var/log/sipnab.log
StandardError=journal
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now sipnab
sleep 3
systemctl is-active sipnab
sudo ls -l /var/log/sipnab.log
  • --no-cli-print keeps every SIP message out of the log.
    • It does not hold back the detection lines.
  • systemd creates the log file when the service starts.
  • Start sipnab before the jail.
    • fail2ban refuses to start a jail whose log file does not exist.
    • It stops every other jail with it.

Install sipnab’s filter and jail

Fetch both files at the tag of the sipnab you installed:

# Run all of these, in order.
V=$(sipnab --version | awk 'NR==1 {print $2}')
sudo curl -fsSL "https://raw.githubusercontent.com/NormB/sipnab/v$V/contrib/fail2ban/sipnab-scanner.conf" \
  -o /etc/fail2ban/filter.d/sipnab-scanner.conf
sudo curl -fsSL "https://raw.githubusercontent.com/NormB/sipnab/v$V/contrib/fail2ban/sipnab-jail.conf" \
  -o /etc/fail2ban/jail.d/sipnab.conf
cat /etc/fail2ban/jail.d/sipnab.conf

The jail is sipnab-scanner.

  • It reads /var/log/sipnab.log.
  • It bans an address after 5 lines within 60 seconds.
    • The ban lasts for an hour.
    • It covers every port, UDP and TCP.
    • It uses nftables.
  • backend = auto makes it read that file even where the distribution’s default is the systemd journal, as on Ubuntu 24.04.

Load it:

# Run all of these, in order.
sudo systemctl restart fail2ban
sleep 3
sudo fail2ban-client status sipnab-scanner

The status shows File list: /var/log/sipnab.log.

Before you leave this running on real traffic, measure who the detectors would name on a capture of your own. Detect SIP scanners and auto-block via fail2ban shows how.

  • Change the jail in a sipnab.local beside it.
  • Never change it in sipnab.conf. The next download replaces that file.

For example, never ban the phone’s network, and wait for 10 detections rather than 5:

# Run all of these, in order.
sudo tee /etc/fail2ban/jail.d/sipnab.local >/dev/null <<'EOF'
[sipnab-scanner]
ignoreip = 127.0.0.1/8 ::1 203.0.113.0/24
maxretry = 10
EOF
sudo systemctl restart fail2ban
sleep 3
sudo fail2ban-client get sipnab-scanner ignoreip
sudo fail2ban-client get sipnab-scanner maxretry

The jail now prints the three ignored ranges and 10. Take the example out again before “Watch sipnab’s lines become a ban”. That section counts to 5:

# Run all of these, in order.
sudo rm /etc/fail2ban/jail.d/sipnab.local
sudo systemctl restart fail2ban
sleep 3
sudo fail2ban-client get sipnab-scanner maxretry

It prints 5.

Watch sipnab’s lines become a ban

  • Start with the scanner unbanned in every jail.
    • The fail2ban guide’s tests may have left a ban behind.
  • The OpenSIPS jail would also ban this scanner, after its third request.
    • So have that jail ignore it while you watch sipnab’s.
    • Keep that until the end of “Watch a registration flood become a ban”.
  • Then the scanner sends four OPTIONS as friendly-scanner:
# Run all of these, in order.
sudo fail2ban-client unban 198.51.100.60
sudo fail2ban-client set opensips addignoreip 198.51.100.60
sudo ip netns exec scanner python3 ~/f2b-test/sipreq.py 192.0.2.10 OPTIONS 4 friendly-scanner
sleep 3
sudo grep -c 'scanner_detected src=198.51.100.60 ' /var/log/sipnab.log
sudo fail2ban-client status sipnab-scanner
  • The first three print SIP/2.0 200 OK.
    • That is sipnab’s answer, not OpenSIPS’s.
  • The fourth prints no answer.
    • sipnab answers one source at most three times a minute.
  • sipnab wrote a scanner_detected src=198.51.100.60 line for each of the four.
  • The jail counts them, Total failed: 4.
    • But it has banned nobody: Banned IP list: is empty.

The fifth inside 60 seconds earns the ban:

# Run all of these, in order.
sudo ip netns exec scanner python3 ~/f2b-test/sipreq.py 192.0.2.10 OPTIONS 1 friendly-scanner
sleep 3
sudo fail2ban-client status sipnab-scanner
sudo nft list set inet f2b-table addr-set-sipnab
sudo ip netns exec scanner python3 ~/f2b-test/sipreq.py 192.0.2.10 OPTIONS 1
  • The jail lists 198.51.100.60.
  • nftables holds it in addr-set-sipnab.
  • The next OPTIONS prints refused.

The phone is not affected, and sipnab wrote nothing about it:

# Run all of these, in order.
sudo ip netns exec phone python3 ~/f2b-test/sipreq.py 192.0.2.10 REGISTER 1 MicroSIP 1001 correct-horse-1001
sudo grep -c 203.0.113.70 /var/log/sipnab.log || true

It prints REGISTER 1001: SIP/2.0 200 OK, then 0.

Watch a registration flood become a ban

  • Lift the scanner’s ban first.
  • The OpenSIPS jail still ignores the address, so only sipnab’s jail acts.
  • Afterwards, the OpenSIPS jail stops ignoring it:
# Run all of these, in order.
sudo fail2ban-client set sipnab-scanner unbanip 198.51.100.60
sudo ip netns exec scanner python3 ~/f2b-test/sipreq.py 192.0.2.10 REGISTER 80 MicroSIP 1001 wrong-password | sort | uniq -c
sleep 3
sudo grep -c 'reg_flood src=198.51.100.60' /var/log/sipnab.log
sudo fail2ban-client status sipnab-scanner
sudo fail2ban-client set opensips delignoreip 198.51.100.60
  • All 80 guesses print REGISTER 1001: SIP/2.0 401 Unauthorized.
  • sipnab wrote 30 reg_flood lines for them.
  • The jail lists 198.51.100.60.

Ban with iptables instead of nftables

The shipped jail bans with nftables. That worked on both systems this guide ran on.

  • You may manage the firewall with the iptables command on a host.
  • There, give the jail fail2ban’s iptables action.
    • The shipped file shows it in a comment.

This block does three things:

  • It installs iptables.
  • It switches the jail to it in a sipnab.local.
  • It bans the scanner again with five OPTIONS:
# Run all of these, in order.
sudo apt-get install -y iptables
sudo iptables -V
sudo tee /etc/fail2ban/jail.d/sipnab.local >/dev/null <<'EOF'
[sipnab-scanner]
action = iptables-allports[name=sipnab, protocol=all]
EOF
sudo systemctl restart fail2ban
sleep 3
sudo fail2ban-client unban 198.51.100.60
sudo ip netns exec scanner python3 ~/f2b-test/sipreq.py 192.0.2.10 OPTIONS 5 friendly-scanner
sleep 3
sudo fail2ban-client status sipnab-scanner
sudo iptables -S f2b-sipnab
sudo ip netns exec scanner python3 ~/f2b-test/sipreq.py 192.0.2.10 OPTIONS 1
  • iptables -V names its backend in brackets.
    • (nf_tables) is the iptables command writing nftables rules for you.
    • (legacy) is the old kernel tables.
  • The jail lists 198.51.100.60.
  • The f2b-sipnab chain holds a rule rejecting it.
  • The next OPTIONS prints refused.

To go back to nftables, remove the override:

# Run all of these, in order.
sudo rm /etc/fail2ban/jail.d/sipnab.local
sudo systemctl restart fail2ban
sleep 3
sudo fail2ban-client status sipnab-scanner

Operate it

CommandWhat it does
sudo fail2ban-client status sipnab-scannerthe jail’s failures and its banned addresses
sudo fail2ban-client set sipnab-scanner unbanip 198.51.100.60lift a ban
sudo fail2ban-regex /var/log/sipnab.log sipnab-scannercount the lines of sipnab’s log the filter matches, without banning anything
sudo journalctl -u sipnab -n 20sipnab’s own messages, including an [ALERT] line for each detection

Uninstall. Remove the jail and the drop-in, and put the packaged service back:

# Run all of these, in order.
sudo rm -f /etc/fail2ban/jail.d/sipnab.conf /etc/fail2ban/jail.d/sipnab.local /etc/fail2ban/filter.d/sipnab-scanner.conf
sudo systemctl restart fail2ban
sudo rm /etc/systemd/system/sipnab.service.d/fail2ban.conf
sudo systemctl daemon-reload
sudo systemctl disable --now sipnab
sudo rm -f /var/log/sipnab.log

To remove sipnab too:

sudo apt-get purge -y sipnab

Check that it worked

After the scanner’s requests of Watch sipnab’s lines become a ban:

# Run all of these, in order.
sudo grep -c 'scanner_detected src=198.51.100.60 ' /var/log/sipnab.log
sudo fail2ban-client status sipnab-scanner
  • The first line counts sipnab’s lines for the scanner. It is 5 after the five requests of that step.
  • The jail’s Banned IP list: names 198.51.100.60.
  • A count of 0 means that sipnab wrote nothing. See the second item below.

When something does not work

  • fail2ban does not start, and journalctl -u fail2ban says Have not found any log file for sipnab-scanner jail.
    • /var/log/sipnab.log does not exist yet.
    • Start sipnab as in “Run sipnab with its detectors, writing the log”.
    • Then restart fail2ban.
  • The log stays empty.
    • Run sudo journalctl -u sipnab -n 20.
    • sipnab warns there when --fail2ban has no detector beside it.