Docs Let sipnab see and control TFPS

Let sipnab see and control TFPS

Have sipnab report what TFPS blocks and ban or unban on request, over REST and MCP, with TFPS on the same machine or reached over SSH.

On this page

TFPS blocks attacking SIP sources in the kernel.

  • sipnab can ask it what it is blocking and why. It does this through its REST API and its MCP tools.
  • It can also block or unblock an address on your behalf, once you turn that on. Out of the box, sipnab changes nothing outside itself.
  • sipnab never blocks anything on its own.
    • Every ban through sipnab is one you ask for.
    • sipnab records it, so you can see it and undo it later.

This guide starts where Add TFPS to your voice stack ends, with TFPS installed and enforcing.

  • It covers sipnab on the same machine as TFPS.
  • It covers sipnab on a different machine.
  • Neither TFPS nor sipnab needs anything from the SIP server. So every step is the same beside OpenSIPS or Kamailio.

What sipnab asks TFPS

sipnab runs tfps_ctl, TFPS’s own command, and reads its answers:

sipnab routeMCP toolRunsNeeds
GET /v1/tfps/statustfps_statustfps_ctl statusthe block map, to report enforcement
GET /v1/tfps/bannedtfps_bannedtfps_ctl bannedthe block map
GET /v1/tfps/labelstfps_labelstfps_ctl logthe database
POST /v1/tfps/bantfps_bantfps_ctl banthe block map and /etc/tfps/config.json, once --allow-action turns it on
POST /v1/tfps/unbantfps_unbantfps_ctl unbanthe block map, once --allow-action turns it on
POST /v1/actions/revertactions_reverttfps_ctl unbanthe block map, once --allow-action turns it on
GET /v1/tfps/droppedtfps_droppednothing yeta TFPS release that reports its kernel drops; none does yet, so this answers 502

The REST API reference gives every request and response.

Before you start

  • TFPS installed and enforcing, as Add TFPS to your voice stack leaves it, from a build at 984577dc or later. Earlier builds do not answer --json in the form sipnab reads.
  • root on the machine that runs sipnab. The steps use sudo.
  • On the other system, TFPS:
    • sipnab on the same machine changes nothing in TFPS until you turn on --allow-action. Then a ban or an unban you ask for changes TFPS’s block map.
    • sipnab on a different machine needs a dedicated account on the TFPS machine, whose SSH key can run tfps_ctl and nothing else.
  • On the SIP server, the phones and the carriers, nothing changes.

Tested on

Every block on this page ran as written, in order, on 2026-09-28. The exception is the blocks in sipnab on the same machine as TFPS.

  • sipnab was 0.5.194, from its release package.
  • The machines were clean x86_64 virtual machines with 2 cores and 3 GB of memory:
    • Debian 13 (kernel 6.12.63),
    • Ubuntu 24.04.5 (kernel 6.8.0).
  • sipnab ran beside TFPS, and on a second machine reaching it over SSH.
  • TFPS came from a build of master.
  • On Debian 13, causing each fault under When something does not work produced what it describes.

Check that TFPS answers in JSON

sipnab reads tfps_ctl’s answers as JSON. It asks with --json.

  • TFPS gained that option on its master branch, merged 2026-09-18 as 984577dc.
  • TFPS v0.3.0 is the first release that has it. v0.2.1 and earlier answer unknown option: --json.
  • sipnab needs a TFPS built at or after the JSON contract, which landed on 2026-09-16 (e7ee57a). A tfps_ctl that predates the JSON contract can answer --json and still not in that form: a build installed on 2026-09-03 answered status, but its ban gave expires as a date string, which sipnab cannot read. Build 984577dc or later.
  • Add TFPS to your voice stack builds that commit.
  • If your TFPS is v0.2.1 or earlier, run its Install TFPS step.
    • The installer builds from the checkout and upgrades the release in place.
    • It keeps /etc/tfps/config.json and what TFPS has learned.

Then check:

sudo tfps_ctl status --json

It prints one line of JSON. Its first member is "enforcement":"active", and the members after it are mode, interface, map, blocked_now, pairs, peers, last_checkpoint, db and version. This build still calls itself 0.2.1 in that line. That is because master has not changed its version number since the release.

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 runs sipnab as the sipnab user, capturing on every interface.

sipnab on the same machine as TFPS

This section ran as written on 2026-09-29. It did not run with the release in Tested on.

  • It ran on the same Debian 13 and Ubuntu 24.04 machines.
  • It used a package built from source that day, before the 0.5.196 release.
  • The test installed that package over the release package that the “Install sipnab” step installs.
  • --allow-action, --journal-show and --revert-actions first shipped in 0.5.196.

Turn on the REST API, and let it ban. The API key reads everything and changes nothing.

  • To ban and unban, sipnab also needs a signing key. From it you make a separate credential that may act.
  • Keep both keys out of the command line, where every user on the machine could read them.
  • Put them in a file only root can read. systemd reads it before it starts sipnab:
# Run all of these, in order.
sudo sh -c 'umask 077; { printf "SIPNAB_API_KEY=%s\n" "$(openssl rand -hex 32)"; printf "SIPNAB_API_SIGNING_KEY=%s\n" "$(openssl rand -hex 32)"; } > /etc/sipnab/api.env'
sudo mkdir -p /etc/systemd/system/sipnab.service.d
sudo tee /etc/systemd/system/sipnab.service.d/tfps.conf >/dev/null <<'EOF'
[Service]
EnvironmentFile=/etc/sipnab/api.env
ExecStart=
ExecStart=/usr/bin/sipnab -N -d any --no-cli-print --syslog --metrics 127.0.0.1:9090 \
  --api 127.0.0.1:8080 --tfps-ctl /usr/local/bin/tfps_ctl --allow-action tfps:rest
EOF

--allow-action tfps:rest is what lets a REST caller ban and unban.

  • Without it, those two routes answer 403 and tfps_ctl never runs.
  • Leave it out if you only want to read what TFPS decided.
  • With it, sipnab records every ban and unban in /var/lib/sipnab/journal. systemd creates that directory for the packaged service.
  • With it, sipnab also limits how often it acts:
    • at most 10 actions a minute,
    • 5 from one caller,
    • one per address a minute.
  • Every ban it asks for expires. That is after an hour, unless you ask for another time.

The API listens on 127.0.0.1 only. Put a TLS proxy in front of it before you open it to the network.

Following Send sipnab’s vCons to a vCon server as well?

  • Both guides replace sipnab’s ExecStart in a drop-in.
  • systemd uses the last ExecStart= it reads, taking drop-ins in file-name order.
  • So one silently replaces the other.
  • Put the flags from both into one drop-in instead.

Give sipnab what tfps_ctl needs. sipnab runs without root. The tfps_ctl it starts inherits sipnab’s privileges. TFPS’s commands need more than a capture does:

  • To read or change blocks, tfps_ctl has to find TFPS’s block map in the kernel by name.
    • That takes CAP_BPF and CAP_SYS_ADMIN.
    • With CAP_BPF alone it fails with no loaded eBPF map called `blocked` .
  • To ban, tfps_ctl reads /etc/tfps/config.json. It does this to refuse addresses you told TFPS to trust. The file is readable by root only.
# Run all of these, in order.
sudo tee /etc/systemd/system/sipnab.service.d/tfps-caps.conf >/dev/null <<'EOF'
[Service]
AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN CAP_BPF CAP_SYS_ADMIN
CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN CAP_BPF CAP_SYS_ADMIN
EOF
sudo chgrp sipnab /etc/tfps/config.json
sudo chmod 640 /etc/tfps/config.json
sudo systemctl daemon-reload
sudo systemctl restart sipnab

Know what you are granting.

  • CAP_SYS_ADMIN is a broad capability, and sipnab parses traffic from the Internet.
  • If you only want to read what TFPS decided, skip the capabilities.
    • labels works without them.
    • status still answers. It reports enforcement as inactive, because it cannot see the map.
  • The different-machine setup below grants sipnab nothing. It works on one machine too.

The installer never rewrites /etc/tfps/config.json. So the group you gave it survives TFPS upgrades. Anything secret in that file, such as an APIBAN key, is now readable by sipnab.

Try it. Make a credential that may act: a token with scope actions, signed with the key sipnab now holds. Then read, ban, look, and unban:

# Run all of these, in order.
KEY=$(sudo sed -n 's/^SIPNAB_API_KEY=//p' /etc/sipnab/api.env)
ACT=$(sudo sh -c 'set -a; . /etc/sipnab/api.env; sipnab --mint-token --token-scope actions --token-id ops-console')
curl -s -w '\n' -H "Authorization: Bearer $KEY" 127.0.0.1:8080/v1/tfps/status
curl -s -w '\n' -X POST -H "Authorization: Bearer $ACT" -H 'Content-Type: application/json' \
  -d '{"ip":"198.51.100.20","ttl_secs":600}' 127.0.0.1:8080/v1/tfps/ban
curl -s -w '\n' -H "Authorization: Bearer $KEY" 127.0.0.1:8080/v1/tfps/banned
sudo sipnab --journal-show
sleep 60
curl -s -w '\n' -X POST -H "Authorization: Bearer $ACT" -H 'Content-Type: application/json' \
  -d '{"ip":"198.51.100.20"}' 127.0.0.1:8080/v1/tfps/unban

What you see:

  • The status reports "enforcement":"active".
  • The ban answers "applied":true with the id sipnab recorded it under.
  • banned lists 198.51.100.20 with its expiry.
  • sipnab --journal-show lists the same ban, its id, and token:ops-console as the caller.
  • The sleep is there because sipnab rests an address for a minute between actions.
  • After it, the unban answers "applied":true.
  • TFPS refuses to ban its own machine. The answer is "applied":false with "refused":"local".

The API key alone cannot ban. Try the ban with $KEY and it answers 401.

A ban belongs to the token that placed it. Since sipnab 0.5.231, another actions token cannot lift it. Mint each operator their own token, so the journal and the refusals name a person:

# Run all of these, in order.
OPS=$(sudo sh -c 'set -a; . /etc/sipnab/api.env; sipnab --mint-token --token-scope actions --token-id ops-console')
NIGHT=$(sudo sh -c 'set -a; . /etc/sipnab/api.env; sipnab --mint-token --token-scope actions --token-id night-shift')
LEAD=$(sudo sh -c 'set -a; . /etc/sipnab/api.env; sipnab --mint-token --token-scope admin --token-id ops-lead')
sleep 60
curl -s -w '\n' -X POST -H "Authorization: Bearer $OPS" -H 'Content-Type: application/json' \
  -d '{"ip":"198.51.100.20","ttl_secs":600}' 127.0.0.1:8080/v1/tfps/ban
curl -s -w '\n' -X POST -H "Authorization: Bearer $NIGHT" -H 'Content-Type: application/json' \
  -d '{"ip":"198.51.100.20"}' 127.0.0.1:8080/v1/tfps/unban

The second token’s unban answers 403:

{"detail":"this ban was placed by token:ops-console; only that caller, or a token with the admin scope, may lift it","status":403,"title":"Forbidden","type":"https://sipnab.com/problems/forbidden"}
  • The token that placed the ban can lift it.
  • A token minted with --token-scope admin, here $LEAD, can lift any ban sipnab placed. It reaches everything an actions token does.
  • POST /v1/actions/revert with "all" lifts only the caller’s own bans, unless the caller holds admin.
  • sipnab --revert-actions all at the command line lifts every ban sipnab placed, whoever placed it.
  • sipnab --journal-show counts the refusal, for example 1 token:night-shift ownership.

From an agent over MCP. The MCP tools tfps_ban, tfps_unban and actions_revert act only when the server enables them for MCP, with --allow-action tfps:mcp (or tfps = ["mcp"] under [actions]). Both surfaces at once take --allow-action tfps:rest,mcp.

  • Over MCP stdio, the enabling is the only lock, because the agent is a local process you started.

  • Over MCP HTTP, the token must also have the actions scope, minted with --mcp-signing-key. sipnab refuses a full token, or a static --mcp-token:

    tool tfps_ban changes a system outside sipnab and this token's scope is "full" — calling it requires an "actions"-scope token, and the server must enable the action
    
  • Without --allow-action tfps:mcp, the tool answers reason not_enabled:

    tfps actions are not enabled for mcp: sipnab changes no external system unless the operator enables it. Start sipnab with --allow-action tfps:mcp, or add tfps = ["mcp"] under [actions] in the config file.
    
  • The ownership rule is the same as over REST. A refused unban carries refusal not_yours, and the message names the owner.

The ownership, admin and MCP behavior above ran on 2026-11-03 with sipnab 0.5.232 built from source, against a stand-in tfps_ctl that answered ban, unban and banned in TFPS’s JSON form, as sipnab’s own tests do. The refusals come from sipnab and do not depend on TFPS. The same day, the 0.5.232 release package ran against a real TFPS on a Debian 13 host, but that host’s tfps_ctl predates the JSON contract: its status worked and its ban answered expires as a date string, so sipnab answered 502 and the ownership steps could not run there. The TFPS side of this page was last run end to end with sipnab 0.5.194, as Tested on says.

Undo everything sipnab did. Someone may misuse a credential that may act. Then:

  • take the permission away first,
  • then lift every ban sipnab placed.

sipnab only lifts its own bans, never one TFPS placed:

# Run all of these, in order.
sudo sed -i 's/ --allow-action tfps:rest//' /etc/systemd/system/sipnab.service.d/tfps.conf
sudo systemctl daemon-reload
sudo systemctl stop sipnab
sudo sipnab --revert-actions all --tfps-ctl /usr/local/bin/tfps_ctl
sudo systemctl start sipnab

sipnab on a different machine

sipnab starts tfps_ctl as a local program. It does not care whether that program is TFPS’s or a script.

  • On the sipnab machine, a two-line script takes its place. The script runs tfps_ctl on the TFPS machine over SSH.
  • On the TFPS machine, a dedicated account’s key can run tfps_ctl and nothing else.

This way sipnab needs no extra privileges at all. The one privileged thing, a sudo rule for tfps_ctl, stays on the TFPS machine.

On the sipnab machine, make a key for the connection:

# Run all of these, in order.
sudo install -d -o sipnab -g sipnab -m 0700 /etc/sipnab/tfps
sudo -u sipnab ssh-keygen -q -t ed25519 -N '' -C sipnab-tfps -f /etc/sipnab/tfps/key
sudo cat /etc/sipnab/tfps/key.pub

On the TFPS machine, create these:

  • the account,
  • a forced command that passes the arguments to tfps_ctl and nothing else,
  • a sudo rule for tfps_ctl alone.

Paste the public key from the last step where it says PUBLIC-KEY:

# Run all of these, in order.
sudo useradd --system --create-home --home-dir /var/lib/sipnabctl --shell /bin/sh sipnabctl
sudo install -d -m 0755 /usr/local/lib/tfps-remote
sudo tee /usr/local/lib/tfps-remote/serve >/dev/null <<'EOF'
#!/bin/sh
# Forced command for sipnab's key: run tfps_ctl with the arguments sipnab
# sent, and nothing else. set -f stops the shell expanding * or ? in them;
# the arguments are split on spaces and never evaluated.
set -f
exec sudo -n /usr/local/bin/tfps_ctl $SSH_ORIGINAL_COMMAND
EOF
sudo chmod 0755 /usr/local/lib/tfps-remote/serve
echo 'sipnabctl ALL=(root) NOPASSWD: /usr/local/bin/tfps_ctl' | sudo tee /etc/sudoers.d/sipnabctl >/dev/null
sudo chmod 0440 /etc/sudoers.d/sipnabctl
sudo visudo -cf /etc/sudoers.d/sipnabctl
sudo install -d -o sipnabctl -g sipnabctl -m 0700 /var/lib/sipnabctl/.ssh
echo 'restrict,command="/usr/local/lib/tfps-remote/serve" PUBLIC-KEY' \
  | sudo tee /var/lib/sipnabctl/.ssh/authorized_keys >/dev/null
sudo chown sipnabctl: /var/lib/sipnabctl/.ssh/authorized_keys
sudo chmod 0600 /var/lib/sipnabctl/.ssh/authorized_keys
  • restrict turns off port forwarding, agent forwarding and terminals for the key.
  • command= means the key runs serve whatever the other side asks for.
  • An attempt to slip in a second command, such as status;id, reaches tfps_ctl as one unknown argument. tfps_ctl refuses it.

Back on the sipnab machine, do these things:

  • write the script that stands in for tfps_ctl,
  • record the TFPS machine’s host key,
  • try it.

Replace 192.0.2.20 with the TFPS machine’s address:

# Run all of these, in order.
sudo tee /etc/sipnab/tfps/tfps_ctl >/dev/null <<'EOF'
#!/bin/sh
exec ssh -o BatchMode=yes -o UserKnownHostsFile=/etc/sipnab/tfps/known_hosts \
  -i /etc/sipnab/tfps/key sipnabctl@192.0.2.20 -- "$@"
EOF
sudo chmod 0755 /etc/sipnab/tfps/tfps_ctl
ssh-keyscan -t ed25519 192.0.2.20 | sudo -u sipnab tee /etc/sipnab/tfps/known_hosts >/dev/null
sudo -u sipnab /etc/sipnab/tfps/tfps_ctl status --json

The last line prints TFPS’s status as JSON. Check the host key that ssh-keyscan recorded against the TFPS machine’s own (ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub there). Do this before you rely on it.

Then point sipnab at the script.

# Run all of these, in order.
sudo sh -c 'umask 077; printf "SIPNAB_API_KEY=%s\n" "$(openssl rand -hex 32)" > /etc/sipnab/api.env'
sudo mkdir -p /etc/systemd/system/sipnab.service.d
sudo tee /etc/systemd/system/sipnab.service.d/tfps.conf >/dev/null <<'EOF'
[Service]
EnvironmentFile=/etc/sipnab/api.env
ReadWritePaths=/etc/sipnab/tfps
ExecStart=
ExecStart=/usr/bin/sipnab -N -d any --no-cli-print --syslog --metrics 127.0.0.1:9090 \
  --api 127.0.0.1:8080 --tfps-ctl /etc/sipnab/tfps/tfps_ctl
EOF
sudo systemctl daemon-reload
sudo systemctl restart sipnab

The curl commands from the same-machine section work unchanged.

When something does not work

  • unknown option: --json. The TFPS in use is v0.2.1 or earlier. Build master, as in the “Check that TFPS answers in JSON” step, or install TFPS v0.3.0 or later.
  • no loaded eBPF map called `blocked` — is tfps running, and are you root? Either TFPS is not running, or sipnab lacks CAP_BPF and CAP_SYS_ADMIN.
  • reading /etc/tfps/config.json: Permission denied. Give the file to the sipnab group, as in the same-machine section.
  • A ban answers 502 with TFPS could not be asked: /usr/local/bin/tfps_ctl ban answered something this sipnab cannot read: line 1: invalid type: string "<date>", expected u64 at line 1 column <n>. A tfps_ctl that predates the JSON contract answers expires as a date string. Upgrade it, as Check that TFPS answers in JSON says.
    • TFPS may have applied the ban anyway: sudo tfps_ctl banned --json lists the address.
    • In 0.5.232 sipnab records no such ban, not even as in doubt. So its unban answers 409, sipnab holds no ban on this address, and --revert-actions does not lift it. A fix is in progress.
    • Lift it on the TFPS host: sudo tfps_ctl unban 198.51.100.20 --json.
  • An unban answers 403 with this ban was placed by token:<id>; only that caller, or a token with the admin scope, may lift it. Another token placed the ban. Use that token, or one minted with --token-scope admin. Over MCP the same refusal is refusal not_yours.
  • A ban or unban answers 429 with this address was acted on moments ago; it rests for the cooldown, retry in 59 s. sipnab acts on one address once a minute. Wait the seconds it names.
  • sipnab refuses an MCP tfps_ban call with reason scope_refused. The HTTP token has the full scope. Mint one with --token-scope actions.
  • /v1/tfps/dropped answers 502. Expected: no TFPS build has dropped yet.
  • A ban answers 502 with answered something this sipnab cannot read.
    • sipnab reads the JSON of e7ee57a and later, where every time is epoch seconds. A tfps_ctl built from the draft of that JSON gives expires as an RFC 3339 date string instead, and sipnab cannot read it.
    • TFPS may still have applied the ban, so sipnab holds it in doubt. sipnab --journal-show lists it, and no other action runs until it is settled.
    • Unban the address with the same token, or with a token with scope admin. TFPS’s answer settles it.
    • Then build TFPS from master, as in the “Check that TFPS answers in JSON” step.
  • installed: false, and the reason says tfps_ctl was not found on PATH.
    • The service runs without --tfps-ctl, and its PATH has no tfps_ctl.
    • Name it with --tfps-ctl.
  • 502 with a detail such as cannot run /opt/tfps/bin/tfps_ctl: No such file or directory (os error 2). The path given to --tfps-ctl does not exist. Check it.