RedHook

Complete setup guide for email-based security testing platform

Get Started

Quick Start (5 steps)

1 git clone && cd redhook
2 ./setup.sh
3 Configure email (AWS SES or Resend) in backend/.env
4 Run ngrok http 8081
5 ./start.sh
Dashboard: http://localhost:8080

Clone & Setup

git clone https://github.com/your-repo/redhook.git
cd redhook
chmod +x setup.sh start.sh
./setup.sh
This creates backend/.env from template

PostgreSQL Setup

Option A: Docker

docker run --name redhook-db \
  -e POSTGRES_PASSWORD=redhook \
  -e POSTGRES_DB=redhook \
  -p 5432:5432 -d postgres:15

Option B: Local Install

sudo apt install postgresql
sudo systemctl start postgresql

Email Configuration (AWS SES or Resend)

Choose one: AWS SES (recommended for production) or Resend (easier setup, domain verification required)

Option A: Resend (Recommended for Testing)

  1. Sign up at resend.com
  2. Get API key from API Keys page
  3. For sending to any email: Verify your domain at resend.com/domains

Resend Configuration (.env)

# Resend Configuration RESEND_ENABLED=true RESEND_API_KEY=re_xxxxxxxxxxxxxxxx RESEND_FROM_EMAIL=Your Name
Resend Limits (Free Tier):
  • Without domain verification: Can only send to your account email
  • After domain verification: Send to any email

Option B: AWS SES (Production)

  1. Create IAM user with AmazonSESFullAccess policy
  2. Create access key (save the Secret!)
  3. Verify sender email in SES console, OR
  4. Request production access to send to any email

AWS SES Configuration (.env)

# AWS SES Configuration AWS_ENABLED=true AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/xxx AWS_SES_FROM_EMAIL=noreply@yourdomain.com

ngrok Setup

Important: Without ngrok, phishing links won't work for external recipients.

Install

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update \
  && sudo apt install ngrok

Start (Port 8081)

ngrok http 8081

Output:

Forwarding → https://abcd-1234.ngrok-free.app → http://localhost:8081

Update .env

PHISHING_URL=https://abcd-1234.ngrok-free.app
Note: ngrok URLs change on restart. Update .env each time.

Run RedHook

./start.sh

Access Dashboard

URL: http://localhost:8080 Email: admin@redhook.local Password: changeme123

Health Check

curl http://localhost:8080/health

Create First Campaign

1. Login

TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@redhook.local","password":"changeme123"}' | jq -r '.token')
echo $TOKEN

2. Add User

curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"email":"target@company.com","name":"Target User","department":"IT","password":"test123"}'

3. Create Campaign

curl -X POST http://localhost:8080/api/campaigns \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"Test Campaign","template_id":1,"landing_page_id":1}'

4. Send

curl -X POST http://localhost:8080/api/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"campaign_id":1,"recipients":[1]}'

5. Results

curl http://localhost:8080/api/campaigns/1/stats -H "Authorization: Bearer $TOKEN"

Environment Variables

VariableRequiredDescription
DB_HOSTYesDatabase host
DB_USERYesDatabase user
DB_PASSWORDYesDatabase password
Email Provider (Choose One)
RESEND_ENABLEDNoEnable Resend (true/false)
RESEND_API_KEYIf ResendResend API key
RESEND_FROM_EMAILIf ResendSender email (use verified domain)
AWS_ENABLEDNoEnable AWS SES (true/false)
AWS_REGIONIf AWSAWS region
AWS_ACCESS_KEY_IDIf AWSAWS access key
AWS_SECRET_ACCESS_KEYIf AWSAWS secret key
AWS_SES_FROM_EMAILIf AWSSES sender email
Other
PHISHING_URLYesPublic phishing URL (ngrok)
JWT_SECRETYesJWT secret key

Troubleshooting

Email Not Sending

Invalid Credentials

Phishing Links Not Working