Alert Configuration Guide

Alert Configuration Guide

ScarpShield supports alerting across five channels. This guide walks you through configuring each one.

---

Console (Default, Always On)

The console channel requires no setup. All alerts are printed directly to the terminal where ScarpShield is running.

[ALERT] Transfer | USDC Treasury | Ethereum
  From: 0x1234...abcd
  To:   0x5678...ef01
  Value: 1,250.00 USDC

Console alerts cannot be disabled. They serve as a reliable fallback when other channels fail.

---

Email (SMTP)

Prerequisites

• Access to an SMTP server (Gmail, Outlook, or a custom server)
• For Gmail: a Google account with 2-Factor Authentication enabled

Gmail Setup

1. Enable 2-Factor Authentication on your Google account: https://myaccount.google.com/security
2. Go to App passwords: https://myaccount.google.com/apppasswords
3. Generate a new app password for "Mail"
4. Copy the 16-character password (e.g., abcd efgh ijkl mnop)

Important: Use the app password, NOT your regular Google password.

Step-by-Step Configuration

Run the setup wizard:

python main.py setup-email

The CLI will prompt you for the following values:

Prompt	Example Value
SMTP Host	smtp.gmail.com
SMTP Port	587 (TLS) or 465 (SSL)
Username	your.email@gmail.com
Password	abcd efgh ijkl mnop (app password)
From Address	your.email@gmail.com
To Address	alerts@yourdomain.com

Environment Variable Alternative

Instead of using the wizard, you can set these in your .env file:

SCARPSHIELD_SMTP_HOST=smtp.gmail.com
SCARPSHIELD_SMTP_PORT=587
SCARPSHIELD_SMTP_USER=your.email@gmail.com
SCARPSHIELD_SMTP_PASSWORD=your_app_password
SCARPSHIELD_SMTP_FROM=your.email@gmail.com
SCARPSHIELD_SMTP_TO=alerts@yourdomain.com

Environment variables override values stored in config.json at runtime.

Testing

After configuration, verify email delivery:

python main.py test-alerts

You should receive a test alert email within a few seconds.

Troubleshooting

Error	Cause	Fix
Authentication failed	Wrong password or app password not used	Generate a fresh app password
Connection refused	Wrong host or port	Double-check smtp.gmail.com:587
STARTTLS extension not supported	Port mismatch	Use 587 for TLS, 465 for SSL
Emails in spam folder	Sender reputation	Add sender to contacts or whitelist

---

Discord

Prerequisites

• A Discord server where you have Manage Webhooks permission

Step 1: Create a Webhook

1. Open your Discord server
2. Go to Server Settings → Integrations → Webhooks
3. Click New Webhook
4. Choose the channel where alerts should be posted
5. Give it a name like "ScarpShield Alerts"

Step 2: Copy the Webhook URL

1. Click Copy Webhook URL
2. The URL looks like:

   https://discord.com/api/webhooks/1234567890123456789/abcdefghijklmnopqrstuvwxyz
   

Step 3: Configure ScarpShield

Run the setup wizard:

python main.py setup-discord

Paste the webhook URL when prompted.

Environment Variable Alternative

SCARPSHIELD_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/1234567890123456789/abcdefghijklmnopqrstuvwxyz

Message Limits

Discord messages auto-truncate at 2000 characters. If an alert exceeds this limit, ScarpShield splits it into multiple messages or sends a summarized version with a link to the full details.

Testing

python main.py test-alerts

A test message should appear in your Discord channel immediately.

---

Slack

Prerequisites

• Admin access to a Slack workspace

Step 1: Create a Slack App

1. Go to https://api.slack.com/apps
2. Click Create New App → From scratch
3. Name it "ScarpShield" and select your workspace

Step 2: Enable Incoming Webhooks

1. In the left sidebar, go to Incoming Webhooks
2. Toggle Activate Incoming Webhooks to On
3. Click Add New Webhook to Workspace
4. Choose the channel where alerts should be posted
5. Click Allow

Step 3: Copy the Webhook URL

1. The webhook URL will be displayed:

   https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
   

2. Copy this URL

Step 4: Configure ScarpShield

Run the setup wizard:

python main.py setup-slack

Paste the webhook URL when prompted.

Environment Variable Alternative

SCARPSHIELD_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Testing

python main.py test-alerts

A test message should appear in your Slack channel.

---

Telegram

Prerequisites

• A Telegram account

Step 1: Create a Bot

1. Open Telegram and message @BotFather
2. Send /newbot
3. Follow the prompts to name your bot (e.g., "ScarpShieldBot")
4. Copy the bot token provided:

   123456789:ABCdefGHIjklMNOpqrSTUvwxyz
   

Step 2: Add the Bot to a Chat

1. Create a group or channel (or use an existing one)
2. Add your new bot to the group/channel
3. Send at least one message in the chat so the bot can see it

Step 3: Get the Chat ID

Use the Telegram API to find your chat ID. Replace <TOKEN> with your bot token:

curl https://api.telegram.org/bot<TOKEN>/getUpdates

Look for the chat object in the response:

{
  "message": {
    "chat": {
      "id": -123456789,
      "title": "ScarpShield Alerts"
    }
  }
}

The id field is your chat ID. For groups, it is typically negative.

Step 4: Configure ScarpShield

Run the setup wizard:

python main.py setup-telegram

Enter the bot token and chat ID when prompted.

Environment Variable Alternative

SCARPSHIELD_TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxyz
SCARPSHIELD_TELEGRAM_CHAT_ID=-123456789

Testing

python main.py test-alerts

A test message should appear in your Telegram chat.

---

Security Best Practice

Always use environment variables (.env file) for credentials instead of storing them in config.json.

The .env file is listed in .gitignore by default, so your secrets will never be committed to version control. Credentials stored in config.json may accidentally be checked into your repository.

Recommended .env Pattern

# SMTP
SCARPSHIELD_SMTP_USER=your.email@gmail.com
SCARPSHIELD_SMTP_PASSWORD=your_app_password

# Discord
SCARPSHIELD_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Slack
SCARPSHIELD_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# Telegram
SCARPSHIELD_TELEGRAM_BOT_TOKEN=123456789:...
SCARPSHIELD_TELEGRAM_CHAT_ID=-123456789

Load the .env file before starting ScarpShield:

# On Windows (PowerShell)
$env:SCARPSHIELD_SMTP_USER = "your.email@gmail.com"

# Or use python-dotenv (installed automatically)
python main.py start

File Permissions

On Unix systems, restrict .env file access:

chmod 600 .env

On Windows, the file is not executable by default. Keep it in a secure location and avoid sharing it.