94 lines
2.1 KiB
Markdown
94 lines
2.1 KiB
Markdown
# 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:
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. Configure environment:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your SMTP2GO API key and sender settings
|
|
```
|
|
|
|
## Usage
|
|
|
|
### List available templates
|
|
```bash
|
|
python -m src.main list-templates
|
|
```
|
|
|
|
### Preview a template
|
|
```bash
|
|
python -m src.main preview --template password-reset --name "John Doe" --email "john@example.com"
|
|
```
|
|
|
|
### Send to a single recipient
|
|
```bash
|
|
python -m src.main send --template password-reset --to user@example.com --name "Test User"
|
|
```
|
|
|
|
### Send to multiple recipients from CSV
|
|
```bash
|
|
python -m src.main send --template password-reset --csv recipients.csv
|
|
```
|
|
|
|
### Dry run (preview without sending)
|
|
```bash
|
|
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
|
|
```json
|
|
{
|
|
"subject": "Password Reset Required",
|
|
"sender_name": "IT Security Team"
|
|
}
|
|
```
|
|
|
|
## CSV Format
|
|
|
|
Recipients CSV must have an `email` column. The `name` column is optional.
|
|
|
|
```csv
|
|
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 |
|