Magikarp: Phishing Email Analyzer

A Telegram bot that analyzes suspicious emails in real-time. Just forward a .eml file and get an instant threat verdict with detailed IOC breakdown. Perfect for security analysts who need fast, accurate phishing triage.

What It Does

• Parses email structure, headers, bodies, and attachments
• Enriches all artifacts: IP reputation, DNS auth, URL scanning, file hashes
• Scores threats using weighted ML-friendly model
• Reports analyst-friendly verdicts with defanged IOCs
• Integrates with Telegram for mobile-first SOC workflows

Tech Stack

• Language: Python 3.11+ (UTF-8)
• APIs: VirusTotal, AbuseIPDB, URLScan.io, ipinfo.io
• DNS: dnspython (SPF/DKIM/DMARC checks)
• Bot: python-telegram-bot 20.0
• Export: CSV activity logging

Setup: Quick Start

Windows

git clone https://github.com/ryuk27/magikarp.git
cd magikarp
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
# Edit .env with your API keys
python main.py --bot

Linux / Kali

git clone https://github.com/ryuk27/magikarp.git
cd magikarp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your API keys
python3 main.py --bot

Then edit .env with your API keys:

VIRUSTOTAL_API_KEY=your_key_here
ABUSEIPDB_API_KEY=your_key_here
URLSCAN_API_KEY=your_key_here
IPINFO_TOKEN=your_key_here
TELEGRAM_BOT_TOKEN=your_botfather_token
ALLOWED_USER_IDS=your_telegram_numeric_id

Demo: Video Walkthrough

Starting the Bot (Kali Linux)

Bot in Action (Analyzing an Email)

Usage: CLI Mode

Analyze a single email from the command line:

python main.py sample_emails/phishing.eml

Output: Formatted threat report with verdict (MALICIOUS / SUSPICIOUS / CLEAN)

Usage: Telegram Bot

The bot is now running and will display the startup banner:

    ███╗   ███╗ █████╗  ██████╗ ██╗██╗  ██╗ █████╗ ██████╗ ██████╗ 
    ████╗ ████║██╔══██╗██╔════╝ ██║██║ ██╔╝██╔══██╗██╔══██╗██╔══██╗
    ██╔████╔██║███████║██║  ███╗██║█████╔╝ ███████║██████╔╝██████╔╝
    ██║╚██╔╝██║██╔══██║██║   ██║██║██╔═██╗ ██╔══██║██╔══██╗██╔═══╝ 
    ██║ ╚═╝ ██║██║  ██║╚██████╔╝██║██║  ██╗██║  ██║██║  ██║██║     
    ╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     
    
    Powered by Rimuru - Bot Running...
    By: ryuk27

In Telegram (find your bot via BotFather):

• Send /start → intro + features
• Send /help → commands guide
• Send /stats → IOC log summary
• Send any .eml file → instant analysis report with action buttons
  • 🚨 Escalate: Flag for further investigation
  • ✅ Close: Mark resolved
  • 🔁 Re-analyze: Fresh run
  • 📋 IOCs only: Artifact summary

How Scoring Works

5 threat categories, 100 points total:

Category	Points	Source
Sender IP	20	AbuseIPDB (score) + Tor detection
DNS Auth	20	SPF/DKIM/DMARC failures
URLs	25	VirusTotal + URLScan verdicts
Attachments	25	File hash VirusTotal lookup
URLScan	10	Full page scan verdict

Special rules:

• URL flagged by ≥1 engine: minimum +20 points
• Attachment >50% AV consensus: +40 bonus
• Tor exit node: +10 bonus

Final verdict:

• 🔴 MALICIOUS (70+): Immediate action
• 🟡 SUSPICIOUS (40–69): Manual review
• 🟢 CLEAN (<40): Archive only

IOC Safety: Defanging

All artifacts are defanged in reports for safe reading:

IP:      1.2.3.4 → 1[.]2[.]3[.]4
URL:     https://evil.com → hxxps://evil[.]com
Email:   user@evil.com → user[@]evil[.]com
Domain:  evil.com → evil[.]com

Deployment Options

Local (Recommended for Initial Demos)

Run bot on your PC with task scheduler auto-start:

python main.py --bot

Bot will poll Telegram until Ctrl+C.

Cloud (Optional: Railway.app)

Deploy to Railway.app free tier (500 hrs/month):

1. Push repo to GitHub
2. Connect Railway to GitHub
3. Set environment variables in Railway dashboard
4. Railway auto-deploys on push

License & Attribution

Internal SOC tool. Built for security analysts.

Analyst Name: Ram V
Version: 1.0 (Bot-integrated)
Last Updated: April 2026