SentryPeer

Overview

SentryPeer is a lightweight, cross-platform SIP (Session Initiation Protocol) honeypot designed to detect and log VoIP fraud, unauthorized access attempts, and attack patterns. It operates by simulating a real VoIP endpoint, collecting data on reconnaissance and exploitation attempts, and sharing threat intelligence with the broader security community.

Key Features

• SIP Honeypot: Attracts and logs VoIP reconnaissance and attack attempts
• Real-time Detection: Identifies fraud patterns and malicious SIP traffic
• Threat Intelligence: Community-driven database of known attackers and patterns
• Cross-platform: Runs on Linux, macOS, Windows, and Docker
• Low Resource Usage: Minimal CPU and memory footprint
• JSON Logging: Structured output for SIEM integration

Installation

Linux (Debian/Ubuntu)

curl https://install.sentrypeer.org | sh
# or via package manager (if available in your distro)
apt-get update
apt-get install sentrypeer

macOS

brew install sentrypeer
# or from source
curl -O https://raw.githubusercontent.com/SentryPeer/SentryPeer/main/install.sh
chmod +x install.sh
./install.sh

Windows

# Via Chocolatey
choco install sentrypeer

# Or download binary from GitHub releases
# https://github.com/SentryPeer/SentryPeer/releases

Docker

docker pull sentrypeer/sentrypeer:latest
docker run -d --name sentrypeer \
  -p 5060:5060/udp \
  -v /var/log/sentrypeer:/var/log/sentrypeer \
  sentrypeer/sentrypeer:latest

From Source

git clone https://github.com/SentryPeer/SentryPeer.git
cd SentryPeer
./configure
make
sudo make install

Basic Configuration

Configuration File

SentryPeer uses /etc/sentrypeer/sentrypeer.conf or a custom config file:

# View default config
sentrypeer --show-config

# Use custom config
sentrypeer -c /path/to/config.conf

Configuration Options

Setting	Description	Default
listen_port	SIP port to listen on	5060
listen_address	IP address to bind to	0.0.0.0
log_file	Path to log file	/var/log/sentrypeer/sentrypeer.log
json_log_file	JSON structured logs	/var/log/sentrypeer/sentrypeer.json
database_file	SQLite database path	/var/lib/sentrypeer/sentrypeer.db
sip_domain	SIP domain to advertise	sentrypeer.org
max_calls	Maximum concurrent calls	0 (unlimited)
enable_api	Enable HTTP API	true

Example Configuration

cat > /etc/sentrypeer/sentrypeer.conf << 'EOF'
listen_port = 5060
listen_address = 0.0.0.0
log_file = /var/log/sentrypeer/sentrypeer.log
json_log_file = /var/log/sentrypeer/sentrypeer.json
sip_domain = company.com
enable_api = true
api_port = 8080
EOF

Basic Usage

Start SentryPeer

# Basic startup
sentrypeer

# Verbose output
sentrypeer -v

# Very verbose (debug)
sentrypeer -vv

# Daemon mode (background)
sentrypeer -d

# With custom config
sentrypeer -c /path/to/config.conf

Monitor Logs

# Follow log file in real-time
tail -f /var/log/sentrypeer/sentrypeer.log

# Follow JSON logs
tail -f /var/log/sentrypeer/sentrypeer.json | jq

# Filter for specific attack types
grep -i "register" /var/log/sentrypeer/sentrypeer.log
grep -i "invite" /var/log/sentrypeer/sentrypeer.log

Advanced Features

Threat Intelligence Sharing

SentryPeer can automatically report attacks to the community database:

# Enable reporting in config
sed -i 's/enable_stats = false/enable_stats = true/g' /etc/sentrypeer/sentrypeer.conf

# View shared threat data
curl https://api.sentrypeer.org/v1/phonenumbers/\
  -H "Content-Type: application/json"

Query Known Bad Numbers

# Check if number is known attacker
sentrypeer --query-phonenumber +1234567890

# Check multiple numbers
while read number; do
  sentrypeer --query-phonenumber "$number"
done < numbers.txt

API Usage

# Get honeypot stats (if API enabled)
curl http://localhost:8080/api/v1/stats

# Query threat intelligence
curl http://localhost:8080/api/v1/threats

# Get recent attacks
curl http://localhost:8080/api/v1/events?limit=100

Detection Patterns

Common VoIP Attacks Detected

Attack Type	Indicator	Example
SIP Scanning	Multiple REGISTER requests from same IP	Attacker probing for valid extensions
Extension Brute Force	Repeated REGISTER with different usernames	Testing extensions 100-999
Credential Attacks	INVITE/REGISTER with bad auth	Bad username/password combinations
SPAM/SPIT	Unsolicited INVITE messages	Robocalls, spam calls
Reconnaissance	OPTIONS requests to discover capabilities	Attacker fingerprinting system
Call Injection	Malformed SIP packets	Attempting protocol exploits

Attack Detection Examples

# View attacks in JSON for analysis
cat /var/log/sentrypeer/sentrypeer.json | jq '.[] | select(.attack_type=="REGISTER_FRAUD")'

# Count attacks by source IP
cat /var/log/sentrypeer/sentrypeer.json | jq -r '.source_ip' | sort | uniq -c

# Find extension enumeration attempts
cat /var/log/sentrypeer/sentrypeer.json | jq '.[] | select(.method=="REGISTER")'

Integration and Monitoring

SIEM Integration

# Logstash configuration example
output {
  if [source] == "sentrypeer" {
    elasticsearch {
      hosts => ["localhost:9200"]
      index => "sentrypeer-%{+YYYY.MM.dd}"
    }
  }
}

# Send logs to syslog
sentrypeer | logger -t sentrypeer

Alerting

# Alert on attack rate threshold
while true; do
  COUNT=$(tail -1 /var/log/sentrypeer/sentrypeer.json | \
    jq '[.] | length')
  if [ $COUNT -gt 10 ]; then
    echo "ALERT: High attack rate detected" | mail -s "SentryPeer Alert" admin@example.com
  fi
  sleep 300
done

Firewall Integration

# Block attacking IPs automatically
while read ip; do
  ufw insert 1 deny from $ip
done < <(cat /var/log/sentrypeer/sentrypeer.json | \
  jq -r '.source_ip' | sort -u)

Systemd Service

Create Service Unit

cat > /etc/systemd/system/sentrypeer.service << 'EOF'
[Unit]
Description=SentryPeer SIP Honeypot
After=network.target

[Service]
Type=simple
User=sentrypeer
Group=sentrypeer
ExecStart=/usr/local/bin/sentrypeer -c /etc/sentrypeer/sentrypeer.conf
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable sentrypeer
sudo systemctl start sentrypeer

Service Management

# Check status
sudo systemctl status sentrypeer

# View logs
sudo journalctl -u sentrypeer -f

# Restart service
sudo systemctl restart sentrypeer

Performance Tuning

Resource Optimization

# Limit file descriptors (for high volume)
ulimit -n 65536

# Network buffer settings
sysctl -w net.core.rmem_max=134217728
sysctl -w net.core.wmem_max=134217728

# UDP buffer optimization
sysctl -w net.ipv4.udp_mem="102400 204800 307200"

Database Maintenance

# Vacuum database to reclaim space
sqlite3 /var/lib/sentrypeer/sentrypeer.db "VACUUM;"

# Check database integrity
sqlite3 /var/lib/sentrypeer/sentrypeer.db "PRAGMA integrity_check;"

# Archive old logs
find /var/log/sentrypeer -name "*.log" -mtime +30 -exec gzip {} \;

Troubleshooting

Port Already in Use

# Check what's using port 5060
lsof -i :5060
netstat -tlnp | grep 5060

# Change SentryPeer port in config
sed -i 's/listen_port = 5060/listen_port = 5061/g' \
  /etc/sentrypeer/sentrypeer.conf

High CPU Usage

# Monitor SIP traffic
tcpdump -i any -n 'udp port 5060' | head -20

# Reduce logging verbosity
sed -i 's/verbose = true/verbose = false/g' /etc/sentrypeer/sentrypeer.conf

# Restart service
sudo systemctl restart sentrypeer

Missing Logs

# Check permissions
ls -la /var/log/sentrypeer/
ls -la /var/lib/sentrypeer/

# Verify service is running
sudo systemctl status sentrypeer

# Check for errors
sudo journalctl -u sentrypeer -n 50

Security Best Practices

Network Setup

# Run on isolated network segment (honeypot network)
ip link add sentrypeer-net type bridge
ip addr add 192.168.100.1/24 dev sentrypeer-net

# Firewall rules (only SIP in)
ufw allow 5060/udp
ufw deny in from any to any port 5060/tcp

# Limit to specific networks
ufw allow from 10.0.0.0/8 to any port 5060

Data Protection

# Encrypt sensitive logs
gpg -c /var/log/sentrypeer/sentrypeer.json

# Secure database backup
sqlite3 /var/lib/sentrypeer/sentrypeer.db ".backup /backups/sentrypeer.db.backup"

# Set restrictive permissions
chmod 600 /etc/sentrypeer/sentrypeer.conf
chmod 700 /var/lib/sentrypeer/

Useful Commands Reference

Command	Purpose
sentrypeer -h	Show help and options
sentrypeer --version	Display version
sentrypeer --list-phonenumbers	List known bad numbers
sentrypeer --query-phonenumber NUMBER	Check if number is known
sentrypeer -c CONFIG -d	Run with custom config in daemon mode
sentrypeer --stats	Show statistics
systemctl restart sentrypeer	Restart service
journalctl -u sentrypeer	View service logs

Resources

• Official Website: https://sentrypeer.org
• GitHub: https://github.com/SentryPeer/SentryPeer
• Community Database: https://api.sentrypeer.org
• Issue Tracker: https://github.com/SentryPeer/SentryPeer/issues
• Documentation: https://docs.sentrypeer.org