signal_honey_pot/README.md

Signal Spammer Auto-Removal

Automatically removes spammers from your Signal group chats when they message in a designated honeypot group.

How It Works

1. You have a "honeypot" group that's clearly not for humans (e.g., "AI Bot Testing" or "System Messages")
2. Spammers join all your groups and message in every chat
3. When a spammer messages in the honeypot group, this script detects them
4. The script removes them from all groups you admin (except the honeypot)
5. You get a notification about the removal

The spammer never realizes they've been caught - they still see the honeypot group and think everything is working.

Prerequisites

• Java 25+ (required by signal-cli 0.14.x)
• signal-cli 0.14.2+ (has the group member removal fix)
• Python 3.9+
• A Signal account registered with signal-cli

Step 1: Install Java

signal-cli requires Java 25 or newer. Install OpenJDK:

macOS (Homebrew):

brew install openjdk@21
# or for Java 25+:
brew install openjdk

Ubuntu/Debian:

sudo apt update
sudo apt install openjdk-21-jdk

Verify:

java --version
# Should show 21+ 

Step 2: Install signal-cli

Option A: Download release (recommended)

# Download latest release (check https://github.com/AsamK/signal-cli/releases for current version)
cd /tmp
wget https://github.com/AsamK/signal-cli/releases/download/v0.14.5/signal-cli-0.14.5-Linux.tar.gz

# Extract
tar xf signal-cli-0.14.5-Linux.tar.gz

# Move to /opt
sudo mv signal-cli-0.14.5 /opt/signal-cli

# Add to PATH
echo 'export PATH="/opt/signal-cli:$PATH"' >> ~/.bashrc
source ~/.bashrc

Option B: macOS with Homebrew

brew install signal-cli

Option C: Build from source

git clone https://github.com/AsamK/signal-cli.git
cd signal-cli
./gradlew installDist
# Binary will be in build/install/signal-cli/bin/signal-cli

Step 3: Register signal-cli with Your Signal Account

Important: You need a phone number that can receive SMS or calls. This can be:

• Your main number (if you want to use your existing account)
• A secondary number (dedicated for this bot)

Register:

# Using your phone number
signal-cli -a +1234567890 register

# You'll receive an SMS with a verification code
signal-cli -a +1234567890 verify CODE_FROM_SMS

Alternative - Link as secondary device: If you want to use your existing Signal account as a linked device:

signal-cli link
# Shows a URI - scan this QR code with your phone's Signal app
# Go to Signal Settings > Linked Devices > Link New Device

Set a PIN (recommended):

signal-cli -a +1234567890 setPin YOUR_PIN

Step 4: Start signal-cli Daemon

The script communicates with signal-cli via its JSON-RPC HTTP interface.

# Start daemon on localhost:8080
signal-cli -a +1234567890 daemon --http=localhost:8080

Keep this running. You may want to run it as a systemd service:

# Create systemd service
sudo tee /etc/systemd/system/signal-cli.service << 'EOF'
[Unit]
Description=Signal CLI Daemon
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/opt/signal-cli/bin/signal-cli -a +1234567890 daemon --http=localhost:8080
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable signal-cli
sudo systemctl start signal-cli

# Check status
sudo systemctl status signal-cli

Step 5: Get Your Honeypot Group ID

1. Create the honeypot group in Signal (app or signal-cli)
2. Get the group's base64 ID:

signal-cli -a +1234567890 listGroups --output=json | jq '.[] | select(.name=="YOUR_HONEYPOT_GROUP_NAME") | .id'

Or list all groups:

signal-cli -a +1234567890 listGroups --output=json | jq '.[] | {name, id}'

Step 6: Install Python Dependencies

cd /path/to/this/project
pip install -r requirements.txt

Step 7: Configure

Edit config.json:

{
  "signal_cli_endpoint": "http://localhost:8080",
  "account": "+1234567890",
  "honeypot_group_id": "BASE64_GROUP_ID_FROM_STEP_5",
  "notify_self_number": "+1234567890",
  "excluded_groups": [],
  "banned_list_path": "banned.json",
  "log_file": "spam_remover.log"
}

Configuration options:

Field	Description
signal_cli_endpoint	URL where signal-cli daemon is running
account	Your signal-cli registered phone number
honeypot_group_id	Base64 ID of the honeypot group
notify_self_number	Phone number to receive removal notifications
excluded_groups	List of group IDs to never remove from (besides honeypot)
banned_list_path	Path to store banned spammers list
log_file	Path to log file

Step 8: Run

Daemon mode (recommended):

python spam_remover.py

This runs continuously, listening for messages in the honeypot group.

Manual ban:

python spam_remover.py --ban +1987654321

Dry run (preview):

python spam_remover.py --dry-run

List banned:

python spam_remover.py --list-banned

Single check:

python spam_remover.py --once

Running as a Service

Create a systemd service for the spam remover:

sudo tee /etc/systemd/system/spam-remover.service << 'EOF'
[Unit]
Description=Signal Spammer Auto-Remover
After=network.target signal-cli.service
Requires=signal-cli.service

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/path/to/this/project
ExecStart=/usr/bin/python3 spam_remover.py
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable spam-remover
sudo systemctl start spam-remover

Files Created

File	Description
spam_remover.py	Main script
config.json	Configuration
requirements.txt	Python dependencies
banned.json	Auto-created, stores banned spammers
spam_remover.log	Auto-created, application logs

Troubleshooting

signal-cli not connecting:

# Check if daemon is running
curl http://localhost:8080/api/v1/check

# Check signal-cli status
systemctl status signal-cli

Permission errors:

• Ensure your account is admin of the groups you want to manage
• signal-cli can only remove members from groups where you have admin privileges

Rate limiting:

• Signal may rate-limit if you remove too many people too fast
• The script handles this automatically with retries

Groups not showing:

• Run signal-cli -a +1234567890 listGroups to verify groups are synced
• You may need to link your device first to sync existing groups

Security Notes

• The honeypot group should look legitimate enough that spammers join but obvious enough that real users don't
• The banned.json file contains phone numbers - protect this file
• signal-cli registration requires a real phone number for SMS verification
• Running as a linked device means your primary device must stay online