Special thanks to Deutsche Telekom Security GmbH for sponsoring us! Very kind!
Why not give us a star and follow us on Twitter!
- Introduction
- Overview
- Features
- Talks
- Adoption
- Design
- Docker
- Installation
- Running SentryPeer
- WebHook
- RESTful API
- Syslog and Fail2ban
- JSON Log Format
- Command Line Options
- IPv6 Multicast Address
- License
- Contributing
- Project Website
- Trademark
- Questions, Bug reports, Feature Requests
- Special Thanks
- Sponsorship
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.
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@
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@
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
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
- All code Free/Libre and Open Source Software
- FAST
- User owns their data
- User can submit their own data if they want to (you need to enable p2p mode -
-p) - User gets other users' data ONLY IF they opt in to submit their data to the pool
- Embedded Distributed Hash Table (DHT) node using OpenDHT (
-pcli option) - Peer to Peer sharing of collected bad_actors using OpenDHT (default off)
- Peer to Peer data replication to receive collected bad_actors using OpenDHT (default off)
- Set your own DHT bootstrap node (
-bcli option) - Multithreaded
- UDP transport
- TCP transport
- TLS transport
- JSON logging to a file
- SIP mode can be disabled. This allows you to run SentryPeer in API mode or DHT mode only etc. i.e. not as a honeypot, but as a node in the SentryPeer community or to just serve replicated data
- SIP responsive mode can be enabled to collect data - cli / env flag
- Local data copy for fast access - cli / env db location flag
- Local API for fast access - cli / env flag
- WebHook for POSTing bad actor json to a central location - cli / env flag
- Integration with SentryPeerHQ via OAuth2 bearer token
- Query API for IP addresses of bad actors
- Query API for IPSET of bad actors
- Query API for a particular IP address of a bad actor
- Query API for attempted phone numbers called by bad actors
- Query API for an attempted phone number called by a bad actor
- Fail2Ban support via
syslogas per feature request - Local sqlite database - feature / cli flag
- Analytics - opt in
- SDKs/libs for external access - CGRateS to start with or our own firewall with nftables
- Small binary size for IoT usage
- Cross-platform
- Firewall options to use distributed data in real time
- Container on Docker Hub for latest build
- BGP agent to peer with for blackholing collected IP addresses (similar to Team Cymru Bogon Router Server Project)
- SIP agent to return 404 or default destination for SIP redirects
- ClueCon Weekly 2023 - https://www.youtube.com/watch?v=iuN_MtVfT6g
- UKNOF49 2022 (presentation slides) - https://indico.uknof.org.uk/event/59/contributions/801/
- ClueCon Weekly 2022 - https://youtu.be/DFxGHJI_0Wg
- CommCon 2021 - https://2021.commcon.xyz/talks/sentrypeer-a-distributed-peer-to-peer-list-of-bad-ip-addresses-and-phone-numbers-collected-via-a-sip-honeypot
- TADSummit 2021 - https://blog.tadsummit.com/2021/11/17/sentrypeer/
- Kali Linux
- Deutsche Telekom T-Pot - The All In One Honeypot Platform v22 onwards
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
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.
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.
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 certifcate for localhost will be automatically
generated in the directory that sentrypeer is run from creating a cert.pem and
a key.pem file.
Debian or Fedora packages are always available from the release page for the current version of SentryPeer:
https://github.com/SentryPeer/SentryPeer/releases
< F438 div class="markdown-heading" dir="auto">