# 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):**
```bash
brew install openjdk@21
# or for Java 25+:
brew install openjdk
```

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install openjdk-21-jdk
```

**Verify:**
```bash
java --version
# Should show 21+ 
```

## Step 2: Install signal-cli

**Option A: Download release (recommended)**

```bash
# 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**
```bash
brew install signal-cli
```

**Option C: Build from source**
```bash
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:**
```bash
# 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:
```bash
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):**
```bash
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.

```bash
# 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:

```bash
# 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:

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

Or list all groups:
```bash
signal-cli -a +1234567890 listGroups --output=json | jq '.[] | {name, id}'
```

## Step 6: Install Python Dependencies

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

## Step 7: Configure

Edit `config.json`:

```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):**
```bash
python spam_remover.py
```

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

**Manual ban:**
```bash
python spam_remover.py --ban +1987654321
```

**Dry run (preview):**
```bash
python spam_remover.py --dry-run
```

**List banned:**
```bash
python spam_remover.py --list-banned
```

**Single check:**
```bash
python spam_remover.py --once
```

## Running as a Service

Create a systemd service for the spam remover:

```bash
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:**
```bash
# 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