Protect your SIP Servers from bad actors
Special thanks to Deutsche Telekom Security GmbH for sponsoring us in 2024.
Why not give us a star and follow us on Twitter!
Table of Contents
Introduction
SentryPeer® is a fraud detection tool. It lets bad actors try to make phone calls and saves the IP address they came from and
number they tried to call. Those details can then be used to raise notifications at the service providers network and the next
time a user/customer tries to call a collected number, you can act anyway you see fit.
For example:
Let's say you are running your own VoIP PBX on site. What SentryPeer will allow you to do in this context,
is dip into the list of phone numbers (using the RESTful API) when your users are making outbound calls. If you get a hit,
you'll get a heads-up that potentially a device within your network is trying to call known probing phone numbers that
have either been:
- Numbers collected by SentryPeer nodes you are running yourself
- Numbers seen by other SentryPeer nodes which have been replicated to your node via the peer to peer network
This would allow you to generate a notification from your monitoring systems before you rack
up any expensive calls or something worse happens.
What would lead to this scenario?
- Potential voicemail fraud. This can happen if you allow calling an
inbound number (your DID/DDI) to get to your voicemail system, then
prompt for a PIN. This PIN is weak and the voicemail system allows you
to press '*' to call back the Caller ID that left a voicemail. The
attacker has left a voicemail, and they then guess your PIN and call it
back. The CLI is a known number that SentryPeer has seen. You can alert on it.
- A device has been hijacked and/or a softphone or similar is using
the credentials they stole off the phone's GUI and is trying to
register to your system and make calls to a number seen by SentryPeer.
- An innocent user is calling a phishing number or known expensive
number etc. that SentryPeer has seen before.
Traditionally, this data is shipped to a central place, so you don't own the data you've collected. This project is all about Peer to Peer sharing of that data. The user owning the data and various Service Provider / Network Provider related feeds of the data is the key bit for me. I'm sick of all the services out there that keep it and sell it. If you've collected it, you should have the choice to keep it and/or opt in to share it with other SentryPeer community members via p2p methods.
Overview
SentryPeer Node
Here we are using Mermaid Sequence diagrams to show the flow of data from a SentryPeer node to SentryPeerHQ.
sequenceDiagram
actor A as Attacker
participant S as SentryPeer Node
participant DS as Data Store
participant W as WebHook <br/>Endpoint
Note over DS: sqlite/json log/syslog <br/>(if enabled)
Note over W: if enabled
A->>S: SIP probe OPTIONS/REGISTER/etc
S->>DS: Save event
S->>W: Send event
W->>S: 200 OK
S->>A: 200 OK
A->>S: INVITE sip:00046500729221@
SentryPeer Node to SentryPeerHQ
sequenceDiagram
actor A as Attacker
participant S as SentryPeer Node
participant DS as Data Store
participant HQ as SentryPeerHQ
Note over DS: sqlite/json log/syslog (if enabled)
Note over HQ: OAuth2 creds required.<br/> if using https://sentrypeer.com
A->>S: SIP probe OPTIONS/REGISTER/etc
S->>DS: Save event
S->>HQ: Send event
HQ->>S: 201 Created
S->>A: 200 OK
A->>S: INVITE sip:00046500729221@
Using the SentryPeer Node and SentryPeerHQ API
sequenceDiagram
Actor U as User
participant S as SentryPeer Node/HQ API
Note over S: if enabled
U->>S: GET /numbers
S->>U: 200 OK Return all Phone numbers seen in database
Integrating with your own systems
sequenceDiagram
participant D as Device
participant P as PBX/ITSP/Carrier
participant HQ as SentryPeer Node/HQ API
participant N as NOC
Note over P: Integration with <br/>SentryPeer needed
Note over N: Consumes alerts
Note over HQ: OAuth2 creds required<br/> if using SentryPeerHQ
Note over P,HQ: API rate limiting if using SentryPeerHQ
D->>P: SIP INVITE
P->>HQ: Have you seen attackers call this number?
HQ->>P: Yes, this has been seen on SentryPeer Nodes
HQ->>N: WebHook/Email/Slack
Note over HQ,N: Only if using SentryPeerHQ
P->>D: I'm blocking this call. Sorry
:construction: Features
Talks
Adoption
Design
I started this because I wanted to do C network programming as all the projects I use daily are in C like PostgreSQL, OpenLDAP, FreeSWITCH, OpenSIPS,
Asterisk etc. See
Episode 414: Jens Gustedt on Modern C for why C is a good choice. For those interested, see my full podcast show list (https://www.se-radio.net/team/gavin-henry/) for Software Engineering Radio
Docker
You can run the latest version of SentryPeer with Docker. The latest version is available from Docker Hub.
Or build yourself:
sudo docker build --no-cache -t sentrypeer .
sudo docker run -d -p 5060:5060/tcp -p 5061:5061/tcp -p 5060:5060/udp -p 8082:8082 -p 4222:4222/udp sentrypeer:latest
Then you can check at http://localhost:8082/ip-addresses and http://localhost:8082/health-check to see if it's running.
Environment Variables
ENV SENTRYPEER_CONFIG_FILE=/my/location/sentrypeer.toml
ENV SENTRYPEER_DB_FILE=/my/location/sentrypeer.db
ENV SENTRYPEER_API=1
ENV SENTRYPEER_WEBHOOK=1
ENV SENTRYPEER_WEBHOOK_URL=https://my.webhook.url/events
ENV SENTRYPEER_OAUTH2_CLIENT_ID=1234567890
ENV SENTRYPEER_OAUTH2_CLIENT_SECRET=1234567890
ENV SENTRYPEER_SIP_RESPONSIVE=1
ENV SENTRYPEER_SIP_DISABLE=1
ENV SENTRYPEER_SYSLOG=1
ENV SENTRYPEER_PEER_TO_PEER=1
ENV SENTRYPEER_BOOTSTRAP_NODE=mybootstrapnode.com
ENV SENTRYPEER_JSON_LOG=1
ENV SENTRYPEER_JSON_LOG_FILE=/my/location/sentrypeer_json.log
ENV SENTRYPEER_VERBOSE=1
ENV SENTRYPEER_DEBUG=1
ENV SENTRYPEER_CERT=/my/location/sentrypeer-crt.pem
ENV SENTRYPEER_KEY=/my/location/sentrypeer-key.pem
ENV SENTRYPEER_TLS_LISTEN_ADDRESS=0.0.0.0:5061
Either set these in the Dockerfile or in your Dockerfile.env file or docker run command.
Settings any of these to 0 will also enable the feature. We don't care what you set it to, just that it's set.
Configuration File
You can also use a configuration file to set certain things. Mainly the TLS configuration
below. The default location is ~/.config/sentrypeer/default-config.toml, but can
change this with the SENTRYPEER_CONFIG_FILE environment variable or -g cli option.
TLS Configuration
To use your own certs, you can either set the appropriate ENV vars, cli arguments
or use the configuration file. For example:
cat ~/.config/sentrypeer/default-config.toml
cert = "tests/unit_tests/127.0.0.1.pem"
key = "tests/unit_tests/127.0.0.1-key.pem"
tls_listen_address = "0.0.0.0:5061"
If you don't set these, a certificate for localhost will be automatically
generated in the directory that sentrypeer is run from creating a cert.pem and
a key.pem file.
Installation
Debian or Fedora packages are always available from the release page for the current version of SentryPeer:
https://github.com/SentryPeer/SentryPeer/releases
Homebrew (macOS or Linux):
We have a Homebrew Tap for this project (until we get more popular):
brew tap sentrypeer/sentrypeer
brew install sentrypeer
Alpine Linux:
SentryPeer is in testing on Alpine Linux, so you can install it with the following command:
apk -U add --no-cache -X https://dl-cdn.alpinelinux.org/alpine/edge/testing sentrypeer
Ubuntu Package
You can install SentryPeer from our Ubuntu PPD which
is currently for Ubuntu 20 LTS (Focal Fossa):
sudo apt install software-properties-common
sudo add-apt-repository ppa:gavinhenry/sentrypeer
sudo apt-get update
This PPA can be added to your system manually by copying the lines below and adding them to your system's software
sources:
deb https://ppa.launchpadcontent.net/gavinhenry/sentrypeer/ubuntu focal main
deb-src https://ppa.launchpadcontent.net/gavinhenry/sentrypeer/ubuntu focal main
Then you can install SentryPeer:
sudo apt-get install sentrypeer
Building from source
You have two options for installation from source. CMake or autotools. Autotools is recommended at the moment. A release is an autotools build.
If you are a Fedora user, you can install this via Fedora copr:
https://copr.fedorainfracloud.org/coprs/ghenry/SentryPeer/
If you are going to build from this repository, you will need to have the following installed:
git, autoconf, automake and autoconf-archive (Debian/Ubuntu)libtool, rustc and cargo (Fedora)libosip2-dev (Debian/Ubuntu) or libosip2-devel (Fedora)libsqlite3-dev (Debian/Ubuntu) or sqlite-devel (Fedora)uuid-dev (Debian/Ubuntu) or libuuid-devel (Fedora)libmicrohttpd-dev (Debian/Ubuntu) or libmicrohttpd-devel (Fedora)libjansson-dev (Debian/Ubuntu) or jansson-devel (Fedora)libpcre2-dev (Debian/Ubuntu) or pcre2-devel (Fedora)libcurl-dev (Debian/Ubuntu) or libcurl-devel (Fedora)libcmocka-dev (Debian/Ubuntu) or libcmocka-devel (Fedora) - for unit tests
Debian/Ubuntu:
sudo apt-get install git build-essential clang autoconf-archive autoconf \
automake libtool cmake libosip2-dev libsqlite3-dev libcmocka-dev uuid-dev \
libcurl4-openssl-dev libpcre2-dev libjansson-dev libmicrohttpd-dev libclang-dev
Fedora:
sudo dnf install git clang pkg-config autoconf automake autoconf-archive \
libtool libosip2-devel libsqlite3-devel libcmocka-devel libuuid-devel \
libmicrohttpd-devel jansson-devel libcurl-devel pcre2-devel cmake \
clang-libs clang
macOS:
brew install git libtool autoconf automake autoconf-archive libosip cmocka \
libmicrohttpd jansson curl pcre2 pkg-config opendht ossp-uuid cmake
Rust:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
then (make check is highly recommended):
./bootstrap.sh
./configure
make
make check
make install
CMake:
cmake -S . -B build -DUNIT_TESTING=ON
cmake --build build
ctest --test-dir build
cmake --install build
Running SentryPeer
Once built, you can run like so to start in debug mode, respond to SIP probes, enable the RESTful API,
enable WebHooks and enable syslog logging (use a package if you want systemd):
./sentrypeer -draps
SentryPeer node id: e5ac3a88-3d52-4e84-b70c-b2ce83992d02
Starting sentrypeer...
API mode enabled, starting http daemon...
SIP mode enabled...
Peer to Peer DHT mode enabled...
Starting peer to peer DHT mode using OpenDHT-C lib version '2.4.0'...
Configuring local address...
Creating sockets...
Binding sockets to local address...
Listening for incoming UDP connections...
SIP responsive mode enabled. Will reply to SIP probes...
Listening for incoming TCP connections...
Peer to peer DHT mode started.
DHT InfoHash for key 'bad_actors' is: 14d30143330e2e0e922ed4028a60ff96a59800ad
Bootstrapping the DHT
Waiting 5 seconds for bootstrapping to bootstrap.sentrypeer.org...
Listening for changes to the bad_actors DHT key
when you get a probe request, you can see something like the following in the terminal:
Received (411 bytes): OPTIONS sip:[email protected] SIP/2.0
Via: SIP/2.0/UDP 91.223.3.152:5173;branch=z9hG4bK-515761064;rport
Content-Length: 0
From: "sipvicious"<sip:[email protected]>;tag=6434396633623535313363340131363131333837383137
Accept: application/sdp
User-Agent: friendly-scanner
To: "sipvicious"<sip:[email protected]>
Contact: sip:[email protected]:5173
CSeq: 1 OPTIONS
Call-ID: 679894155883566215079442
Max-Forwards: 70
read_packet_buf size is: 1024:
read_packet_buf length is: 468:
bytes_received size is: 411:
Bad Actor is:
Event Timestamp: 2021-11-23 20:13:36.427515810
Event UUID: fac3fa20-8c2c-445b-8661-50a70fa9e873
SIP Message: OPTIONS sip:[email protected] SIP/2.0
Via: SIP/2.0/UDP 91.223.3.152:5173;branch=z9hG4bK-515761064;rport
From: "sipvicious" <sip:[email protected]>;tag=6434396633623535313363340131363131333837383137
To: "sipvicious" <sip:[email protected]>
Call-ID: 679894155883566215079442
CSeq: 1 OPTIONS
Contact: <sip:[email protected]:5173>
Accept: application/sdp
User-agent: friendly-scanner
Max-forwards: 70
Content-Length: 0
Source IP: 193.107.216.27
Called Number: 100
SIP Method: OPTIONS
Transport Type: UDP
User Agent: friendly-scanner
Collected Method: responsive
Created by Node Id: fac3fa20-8c2c-445b-8661-50a70fa9e873
SentryPeer db file location is: sentrypeer.db
Destination IP address of UDP packet is: xx.xx.xx.xx
You can see the data in the sqlite3 database called sentrypeer.db using sqlitebrowser or sqlite3 command line tool.
Here's a screenshot of the database opened using sqlitebrowser (it's big, so I'll just link to the image):
sqlitebrowser exploring the sentrypeer.db
WebHook
There is a WebHook to POST a JSON Log Format payload to SentryPeerHQ or
your own WebHook endpoint. The WebHook is not enabled by default. You can configure the WebHook URL via -w or set
the SENTRYPEER_WEBHOOK_URL env variable.
If using SentryPeer SaaS you need to get your client id and client secret from the
Dashboard and set the SENTRYPEER_OAUTH2_CLIENT_ID and SENTRYPEER_OAUTH2_CLIENT_SECRET env variables or use the -i and -c flags.
RESTful API
The RESTful API is complete for the current use cases. Please click the Watch button to be notified when more things come out :-)
Endpoint /health-check
Query the API to see if it's alive:
curl -v -H "Content-Type: application/json" http://localhost:8082/health-check
* Connected to localhost (127.0.0.1) port 8082 (#0)
> GET /health-check HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/7.79.1
> Accept: */*
> Content-Type: application/json
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Mon, 24 Apr 2022 11:16:25 GMT
< Content-Type: application/json
< Access-Control-Allow-Origin: *
< X-Powered-By: SentryPeer
< X-SentryPeer-Version: 1.4.0
< Content-Length: 81
<
{
"status": "OK",
"message": "Hello from SentryPeer!",
"version": "1.0.0"
}
Endpoint /ip-addresses
List all the IP addresses that have been seen by SentryPeer:
curl -v -H "Content-Type: application/json" http://localhost:8082/ip-addresses
* Connected to localhost (127.0.0.1) port 8082 (#0)
> GET /ip-addresses HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/7.79.1
> Accept: */*
> Content-Type: application/json
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Mon, 24 Jan 2022 11:17:05 GMT
< Content-Type: application/json
< Access-Control-Allow-Origin: *
< X-Powered-By: SentryPeer
< X-SentryPeer-Version: 1.0.0
< Content-Length: 50175
<
{
"ip_addresses_total": 396,
"ip_addresses": [
{
"ip_address": "193.107.216.27",
"seen_last": "2022-01-11 13:30:48.703603359",
"seen_count": "1263"
},
{
"ip_address": "193.46.255.152"
"seen_last": "2022-01-11 13:28:27.348926406",
"seen_count": "3220"
}
...
]
}
Endpoint /ip-addresses/{ip-address}
Query a single IP address:
curl -v -H "Content-Type: application/json" http://localhost:8082/ip-addresses/8.8.8.8
* Connected to localhost (127.0.0.1) port 8082 (#0)
> GET /ip-addresses/8.8.8.8 HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/7.79.1
> Accept: */*
> Content-Type: application/json
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 404 Not Found
< Date: Mon, 24 Jan 2022 11:17:57 GMT
< Content-Type: application/json
< Access-Control-Allow-Origin: *
< X-Powered-By: SentryPeer
< X-SentryPeer-Version: 1.0.0
< Content-Length: 33
<
* Connection #0 to host localhost left intact
{
"message": "No bad actor found"
}
Endpoint /numbers
List all the called numbers that have been seen by SentryPeer:
curl -v -H "Content-Type: application/json" http://localhost:8082/numbers
* Connected to localhost (127.0.0.1) port 8082 (#0)
> GET /numbers HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/8.0.1
> Accept: */*
> Content-Type: application/json
< Date: Thu, 27 Jul 2023 11:10:35 GMT
< Content-Type: application/json
< Access-Control-Allow-Origin: *
< X-Powered-By: SentryPeer
< X-SentryPeer-Version: 4.0.0
< Content-Length: 31746258
{
"called_numbers_total": 244850,
"called_numbers": [
{
"called_number": "981046500729221",
"seen_last": "2023-07-27 12:06:59.388055505",
"seen_count": "451"
},
{
"called_number": "81046500729221",
"seen_last": "2023-07-27 12:05:19.206442003",
"seen_count": "453"
},
{
"called_number": "100",
"seen_last": "2023-07-27 11:59:57.679798597",
"seen_count": "17335"
},
....
Endpoint /numbers/{phone-number}
Query a phone number a bad actor tried to call with optional + prefix:
curl -v -H "Content-Type: application/json" http://localhost:8082/numbers/8784946812410967
* Connected to localhost (127.0.0.1) port 8082 (#0)
> GET /numbers/8784946812410967 HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/7.79.1
> Accept: */*
> Content-Type: application/json
>
< HTTP/1.1 200 OK
< Date: Mon, 24 Jan 2022 11:19:53 GMT
< Content-Type: application/json
< Access-Control-Allow-Origin: *
< X-Powered-By: SentryPeer
< X-SentryPeer-Version: 1.0.0
< Content-Length: 46
<
{
"phone_number_found": "8784946812410967"
}
Syslog and Fail2ban
With sentrypeer -s, you parse syslog and use Fail2Ban to block the IP address of the bad actor:
Nov 30 21:32:16 localhost.localdomain sentrypeer[303741]: Source IP: 144.21.55.36, Method: OPTIONS, Agent: sipsak 0.9.7
JSON Log Format
With sentrypeer -j, you can produce a JSON log file of the bad actor's IP address and the phone number they tried to call
plus other metadata (set a custom log file location with -l):
{
"app_name":"sentrypeer",
"app_version":"v1.4.0",
"event_timestamp":"2022-02-22 11:19:15.848934346",
"event_uuid":"4503cc92-26cb-4b3e-bb33-69a83fa09321",
"created_by_node_id":"4503cc92-26cb-4b3e-bb33-69a83fa09321",
"collected_method":"responsive",
"transport_type":"UDP",
"source_ip":"45.134.144.128",
"destination_ip":"XX.XX.XX.XX",
"called_number":"0046812118532",
"sip_method":"OPTIONS",
"sip_user_agent":"friendly-scanner",
"sip_message":"full SIP message"
}
Command Line Options
./sentrypeer -h
Protect your SIP Servers from bad actors at https://sentrypeer.com
Usage: sentrypeer [OPTIONS]
Options:
-f <DB_FILE> Set 'sentrypeer.db' location or use SENTRYPEER_DB_FILE env
-j Enable json logging or use SENTRYPEER_JSON_LOG env
-p Enable Peer to Peer mode or use SENTRYPEER_PEER_TO_PEER env
-b <BOOTSTRAP_NODE> Set Peer to Peer bootstrap node or use SENTRYPEER_BOOTSTRAP_NODE env
-i <CLIENT_ID> Set OAuth 2 client ID or use SENTRYPEER_OAUTH2_CLIENT_ID env to get a Bearer token for WebHook
-c <CLIENT_SECRET> Set OAuth 2 client secret or use SENTRYPEER_OAUTH2_CLIENT_SECRET env to get a Bearer token for WebHook
-a Enable RESTful API mode or use SENTRYPEER_API env
-w <WEBHOOK_URL> Set WebHook URL for bad actor json POSTs or use SENTRYPEER_WEBHOOK_URL env
-r Enable SIP responsive mode or use SENTRYPEER_SIP_RESPONSIVE env
-R Disable SIP mode completely or use SENTRYPEER_SIP_DISABLE env
-l <JSON_LOG_FILE> Set JSON logfile (default './sentrypeer_json.log') location or use SENTRYPEER_JSON_LOG_FILE env
-N Disable Rust powered TCP, UDP and TLS or use SENTRYPEER_TLS_DISABLE env
-t <TLS_CERT_FILE> Set TLS cert location (default './cert.pem') or use SENTRYPEER_CERT env
-k <TLS_KEY_FILE> Set TLS key location (default './key.pem') or use SENTRYPEER_KEY env
-z <TLS_LISTEN_ADDRESS> Set TLS listen address (default '0.0.0.0:5061') or use SENTRYPEER_TLS_LISTEN_ADDRESS env
-g <CONFIG_FILE> Set config file location or use SENTRYPEER_CONFIG_FILE env
-s Enable syslog logging or use SENTRYPEER_SYSLOG env
-v Enable verbose logging or use SENTRYPEER_VERBOSE env
-d Enable debug mode or use SENTRYPEER_DEBUG env
-h, --help Print help
-V, --version Print version
IPv6 Multicast Address
The project has an IANA IPv6 multicast address for the purpose of sending messages between SentryPeer peers.
Addresses: FF0X:0:0:0:0:0:0:172
Description: SentryPeer
Contact: Gavin Henry <ghenry at sentrypeer.org>
Registration Date: 2022-01-26
Please see http://www.iana.org/assignments/ipv6-multicast-addresses
The assigned variable-scope address -- which can also be listed as "FF0X::172" for short -- the "X" denotes any possible scope.
License
Great reading - How to choose a license for your own work
This work is dual-licensed under GPL 2.0 and GPL 3.0.
SPDX-License-Identifier: GPL-2.0-only OR GPL-3.0-only
Contributing
See CONTRIBUTING
Project Website
https://sentrypeer.org
Trademark
SENTRYPEER is a registered trademark of Gavin Henry
Questions, Bug reports, Feature Requests
New issues can be raised at:
https://github.com/SentryPeer/SentryPeer/issues
It's okay to raise an issue to ask a question.
Special Thanks
Special thanks to:
Sponsorship
Special thanks to Deutsche Telekom Security GmbH for sponsoring us! Very kind!
