phishtest/README.md

Phishtest

A phishing email testing tool designed to test Proofpoint TAP (Targeted Attack Protection) systems. Sends test phishing emails via SMTP2GO.

Setup

1. Create and activate virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment:

   cp .env.example .env
   # Edit .env with your SMTP2GO API key and sender settings
   

Usage

List available templates

python -m src.main list-templates

Preview a template

python -m src.main preview --template password-reset --name "John Doe" --email "john@example.com"

Send to a single recipient

python -m src.main send --template password-reset --to user@example.com --name "Test User"

Send to multiple recipients from CSV

python -m src.main send --template password-reset --csv recipients.csv

Dry run (preview without sending)

python -m src.main send --template password-reset --csv recipients.csv --dry-run

Creating Templates

Templates are stored in templates/<template-name>/ with three files:

• metadata.json - Subject line and sender name
• template.html - HTML email body
• template.txt - Plain text email body

Available template variables

• {{recipient_name}} - Recipient's name
• {{recipient_email}} - Recipient's email address
• {{company_name}} - Company name from config
• {{date}} - Current date

Example metadata.json

{
  "subject": "Password Reset Required",
  "sender_name": "IT Security Team"
}

CSV Format

Recipients CSV must have an email column. The name column is optional.

email,name
john.doe@example.com,John Doe
jane.smith@example.com,Jane Smith

Configuration

Set these in .env or as environment variables:

Variable	Required	Description
SMTP2GO_API_KEY	Yes	Your SMTP2GO API key
SENDER_EMAIL	Yes	Sender email address (must be verified in SMTP2GO)
SENDER_NAME	No	Default sender display name
COMPANY_NAME	No	Company name for templates