syed-sameer-ul-hassan/MailSpoof

<div align="center">

| ✅ Issue Resolved | | :--- | | Thank you for your patience! The installation issues have been resolved. All fixes are live and the tool is fully operational. |

</div>

<p align="center"> <img src="assets/logo.svg" alt="MailSpoof Logo" width="500"> </p>

<div align="center">

MailSpoof — Email Spoofing & Phishing Simulation Tool

    ![Status]() ![Platform]() 

</div>

---

MailSpoof is a professional, open-source email spoofing and phishing simulation framework for authorized penetration testing, red team exercises, and security awareness training. Built in Python with a built-in SMTP testing server, pre-built attack scenarios, custom template creation, audit logging, and report generation.

---

Table of Contents

• Features
• Technology Stack
• How It Works
• Quick Start
• Installation
• Usage
• Interactive Session Workflow
• Template Lifecycle
• SMTP Profile Workflow
• Report Generation Flow
• Email Spoofing Scenarios
• Custom Templates
• SMTP Relay & Delivery
• Audit Logs & Reports
• Project Structure
• Troubleshooting
• License
• Legal Notice

---

Features

• Built-in SMTP Server — Multi-threaded raw-socket SMTP server with optional MX relay for local testing
• HTTP Tracking Server — Embedded HTTP server on port 8080 for open/pixel tracking of sent emails
• 62 Phishing Templates — 62 pre-built HTML email templates across social media, SaaS, financial, logistics, developer platforms, and BEC
• Custom Template Engine — Create, edit, preview, filter, and remove your own phishing email templates interactively
• External SMTP Relay — Send via Gmail, Outlook, SendGrid, or any authenticated SMTP server with TLS/SSL support
• SMTP Profile Management — Save and reuse named SMTP relay configurations
• Bulk Target Lists — Send to hundreds of targets via --target-list targets.csv in a single command
• Attachment Payloads — Attach files (PDFs, DOCX, etc.) to emails via --attach to test gateway filtering
• Advanced Headers — Inject custom --reply-to and --x-mailer headers for advanced bypass testing
• Audit Logging — Every test is logged with timestamps, success/failure, error details, and server details
• JSON & CSV Reports — Generate assessment reports with success rates, per-test errors, and security recommendations
• Template Preview — Preview HTML/text content before sending
• Template Filtering — Filter templates by name, category, tags, or content
• Docker Support — Deploy instantly on any VPS using docker-compose up
• Desktop Launcher — .desktop entry with icon for Linux application menus (auto-installed)
• Cross-Platform — Works on Linux, macOS, and Termux (Android)
• Apache-2.0 Licensed — Free for commercial and personal use

Architecture Overview

flowchart TD
    A[User] -->|CLI| B[mailspoof]
    B --> C[lib/cli.py]
    C --> D{Command?}
    D -->|start / server| E[lib/server.py<br/>SMTP Server]
    D -->|test / custom| F[lib/engine.py<br/>Email Builder]
    D -->|list / create / preview / edit / remove| G[lib/core.py<br/>Templates]
    D -->|logs / report| H[lib/audit.py<br/>Audit & Reports]
    D -->|profile| I[lib/core.py<br/>Config & Profiles]
    E -->|MX Relay| M[Recipient Mail Server]
    F -->|Send| J[External SMTP Relay]
    F -->|Send| E
    J --> M
    H --> K[audit.log / reports/]

---

Technology Stack

MailSpoof is built entirely in Python 3.8+ with zero external runtime dependencies for core functionality. Below is the complete technology breakdown:

Core Language & Standard Library

| Technology | Purpose | |------------|---------| | Python 3.8+ | Core programming language with type hints (\|, list[T]) | | argparse | CLI argument parsing and subcommand routing (start, test, custom, list, create, preview, edit-template, remove-template, profile, logs, report) | | smtplib | SMTP client for external relay sending (AUTH, STARTTLS, SSL) | | socket | Raw TCP socket handling for built-in SMTP server | | threading | Multi-threaded built-in SMTP server (concurrent client sessions) | | json | Config file (config.json) and audit log (audit.log) serialization | | logging | Structured audit logging to file and stdout |

Email & MIME Construction

| Technology | Purpose | |------------|---------| | email.mime.multipart | multipart/alternative MIME messages (HTML + plain text) | | email.mime.text | MIME text parts for email body | | email.header | UTF-8 encoded email subject headers | | email.utils | Message-ID generation and RFC-compliant date formatting | | html | HTML-to-text conversion for plain-text fallback |

Data & Configuration

| Technology | Purpose | |------------|---------| | dataclasses | Scenario, TestResult typed data structures | | pathlib | Cross-platform path handling (~/.mailspoof/, templates) | | re | Regex for HTML stripping, template parsing, SMTP response parsing |

Optional Dependencies

| Technology | Purpose | |------------|---------| | dnspython | DNS MX record lookups for direct MX delivery (pip install dnspython) | | setuptools | Package building and console script entry points | | wheel | Python wheel distribution format |

Reporting & Output

| Technology | Purpose | |------------|---------| | JSON | Default report format (report_YYYYMMDD_HHMMSS.json) | | CSV | Tabular report export (report_YYYYMMDD_HHMMSS.csv) | | ANSI Color Codes | Terminal color output (red/yellow/green/cyan for severity) |

Packaging & Distribution

| Technology | Purpose | |------------|---------| | setuptools + setup.py | PyPI-compatible package with console script entry point | | pyproject.toml | Modern Python packaging (PEP 517/518) | | .deb / dpkg | Debian/Ubuntu system package | | .rpm / rpmbuild | Fedora/RHEL/CentOS system package | | PKGBUILD | Arch Linux AUR package | | Makefile | Generic install/uninstall |

Desktop Integration

| Technology | Purpose | |------------|---------| | .desktop entry | Linux application menu launcher | | SVG icon | Scalable vector icon for all display resolutions | | XDG directories | Standard icon/application paths (~/.local/share/, /usr/share/) |

---

How It Works

MailSpoof operates through a simple 3-stage pipeline: Select a template, Configure the target and SMTP relay, then Send and log the result.

flowchart LR
    A[Select Template] --> B[Configure Target & SMTP]
    B --> C[Build HTML Email]
    C --> D[Send via Relay or MX]
    D --> E{Success?}
    E -->|Yes| F[Log Success + Report]
    E -->|No| G[Log Error + Tips]
    F --> H[Audit.log]
    G --> H

Key paths:

• Built-in templates → 45+ ready-to-use scenarios
• Custom templates → Create your own with mailspoof create
• SMTP relay → Use Gmail, Outlook, SendGrid, or saved profiles
• Direct MX → Deliver straight to recipient server (often blocked by ISPs)

---

Quick Start

git clone https://github.com/syed-sameer-ul-hassan/MailSpoof.git
cd MailSpoof
pip install -r requirements.txt
chmod +x mailspoof
./mailspoof --version

Or install via Debian package:

sudo dpkg -i mailspoof-v1.2.0.deb
mailspoof --version

---

Installation

Option 1: Universal Installer (Any Distro)

Auto-detects your platform and installs dependencies:

bash install.sh

Supported: Debian/Ubuntu, Fedora/RHEL/CentOS, Arch/Manjaro, macOS, Termux, and others.

Option 2: Debian / Ubuntu (.deb)

sudo dpkg -i mailspoof-v1.2.0.deb
sudo apt-get install -f

Or build from source:

bash scripts/build-deb.sh

Option 3: Fedora / RHEL / CentOS (.rpm)

sudo dnf install rpm-build
rpmbuild -ba mailspoof.spec
sudo rpm -i ~/rpmbuild/RPMS/noarch/mailspoof-*.rpm

Option 4: Arch Linux (AUR / PKGBUILD)

makepkg -si

Or install manually:

cd /tmp
git clone https://aur.archlinux.org/mailspoof.git
cd mailspoof
makepkg -si

Option 5: Generic Makefile

make install
sudo make install PREFIX=/usr

Option 6: Manual / Development

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
./mailspoof list

Requirements: Python 3.8+, python3-venv (or python3-virtualenv on RPM distros)

---

Usage

Interactive Session Workflow

flowchart TD
    A[mailspoof start] --> B[Start SMTP Server<br/>port 2525]
    B --> C[Select Template ID]
    C --> D[Enter Target Email]
    D --> E[Enter Spoofed From<br/>ceo@company.com]
    E --> F[Enter Subject]
    F --> G{Use External Relay?}
    G -->|Yes| H[Enter SMTP Host<br/>User / Pass / TLS]
    G -->|No| I[Direct MX Delivery]
    H --> J[Confirm & Send]
    I --> J
    J --> K{Delivery Result}
    K -->|Success| L[Log to audit.log]
    K -->|Failed| M[Show Error + Tips]
    M --> N[Retry with Relay]

Interactive Email Spoofing Session

Launch the built-in SMTP server and send a spoofed email interactively:

mailspoof start --port 2525

You will be prompted for:

• Target email address
• Spoofed sender email & display name
• Subject line
• External SMTP relay settings (optional, recommended)
• Template ID

Run a Built-in Phishing Scenario

mailspoof test 1 victim@company.com

Start SMTP Server Only

mailspoof server --host 0.0.0.0 --port 2525

List All Templates

mailspoof list                              # All templates
mailspoof list --filter linkedin            # Filter by name/tag/content
mailspoof list --filter "social media"      # Filter by category

Create Custom Phishing Template

mailspoof create
# or
mailspoof -t

Custom templates are auto-assigned the next available ID.

Preview Template

mailspoof preview 1                         # Text preview (strips HTML)
mailspoof preview 1 --raw                   # Show raw HTML

Edit Template

mailspoof edit-template 1                   # Edit in $EDITOR (default nano)

Works for both built-in and custom templates.

Remove Template

mailspoof remove-template 46                # Only custom templates

Template Lifecycle

Manage templates from creation to deletion:

flowchart TD
    A[mailspoof create] --> B[Auto-assign ID]
    B --> C[Save to ~/.mailspoof/templates/custom/]
    C --> D[mailspoof list]
    D --> E{Need changes?}
    E -->|Yes| F[mailspoof edit-template <id>]
    F --> G[Edit in $EDITOR]
    G --> D
    E -->|No| H[mailspoof preview <id>]
    H --> I[mailspoof test <id> target@email.com]
    I --> J{Done with template?}
    J -->|Yes| K[mailspoof remove-template <id>]
    J