<p align="center"> <img src="static/images/logo_purple.png" alt="PhishHook Logo" width="128"> </p> <h1 align="center">PhishHook</h1> <p align="center"> Enhanced GoPhish fork with evasion capabilities for professional red team operations. </p>

Features

Automatic Let's Encrypt SSL: Use --domain flag for automatic certificate provisioning
Cloudflare Turnstile Integration: Bot protection that blocks automated scanners (Safe Links, security crawlers) while allowing real users through
Behavioral Detection: Filter automated scanners using timing analysis, Microsoft IP blocking, and JS telemetry (mouse movement, scroll events, time-on-page)
Microsoft Tenant Branding Proxy: Automatically fetch target organization's custom Microsoft 365 login branding (background images, logos) via {{.BrandingURL}} template variable
Header Evasion: Strips identifying headers (X-Server: gophish, etc.) that fingerprint the server
Full GoPhish Compatibility: All upstream GoPhish features work as expected

Why PhishHook?

Microsoft Safe Links and similar email security products crawl phishing links before users click them, generating false positive "clicks" in your campaign metrics. PhishHook solves this with multiple layers of defense:

Behavioral Detection: Blocks requests from known Microsoft 365/Safe Links IP ranges, enforces minimum time-on-page, and validates mouse/touch interaction telemetry
Turnstile Challenge: Automated scanners can't solve the Cloudflare challenge, so they never reach the landing page
JS Telemetry: Collects client-side behavioral signals (mouse movement, scroll, clicks) to distinguish humans from bots
Clean Metrics: Your campaign data reflects actual human interactions

Installation

From Source

git clone https://github.com/wcrooker/PhishHook.git
cd PhishHook
go build

Requirements

Go 1.21+
Ports 80 and 443 (for Let's Encrypt)

Quick Start

Development (Self-Signed SSL)

./gophish

Production (Let's Encrypt)

# Allow binding to privileged ports without root
sudo setcap 'cap_net_bind_service=+ep' ./gophish

# Start with automatic SSL
./gophish --domain phish.example.com

This will:

Start HTTP on port 80 for ACME challenges
Obtain a Let's Encrypt certificate automatically
Start HTTPS on port 443 with valid SSL
Cache certificates in certs/ for renewal

Configuration

Edit config.json:

{
  "admin_server": {
    "listen_url": "127.0.0.1:3333",
    "use_tls": true,
    "cert_path": "gophish_admin.crt",
    "key_path": "gophish_admin.key"
  },
  "phish_server": {
    "listen_url": "0.0.0.0:443",
    "use_tls": true,
    "cert_path": "phish.crt",
    "key_path": "phish.key"
  },
  "turnstile": {
    "enabled": true,
    "site_key": "YOUR_CLOUDFLARE_SITE_KEY",
    "secret_key": "YOUR_CLOUDFLARE_SECRET_KEY",
    "cookie_secret": "random-32-char-secret-here"
  },
  "evasion": {
    "enabled": true,
    "strip_server_header": false,
    "custom_server_name": "IGNORE"
  },
  "behavioral": {
    "enabled": true,
    "min_time_on_page_ms": 2000,
    "require_mouse_movement": false,
    "require_interaction": false,
    "block_microsoft_ips": true,
    "custom_blocked_cidrs": [],
    "max_requests_per_minute": 30
  },
  "branding": {
    "enabled": true,
    "allowed_origins": ["*"]
  }
}

Turnstile Setup

Go to Cloudflare Dashboard > Turnstile
Click "Add Widget"
Enter your phishing domain
Choose "Managed" mode (recommended)
Copy Site Key and Secret Key to config.json
Generate a random cookie_secret (32+ characters)

Configuration Options

| Option | Description | |--------|-------------| | turnstile.enabled | Enable Cloudflare Turnstile challenge | | turnstile.site_key | Cloudflare Turnstile site key | | turnstile.secret_key | Cloudflare Turnstile secret key | | turnstile.cookie_secret | Secret for signing session cookies | | evasion.enabled | Enable header stripping | | evasion.strip_server_header | Remove X-Server header entirely | | evasion.custom_server_name | Custom X-Server value (default: "IGNORE") | | behavioral.enabled | Enable behavioral bot detection | | behavioral.min_time_on_page_ms | Minimum milliseconds on page before form submission is valid (default: 2000) | | behavioral.require_mouse_movement | Require mouse/touch movement to validate request | | behavioral.require_interaction | Require scroll, click, or keypress events | | behavioral.block_microsoft_ips | Block known Microsoft 365/Safe Links IP ranges | | behavioral.custom_blocked_cidrs | Additional CIDR ranges to block (e.g., ["10.0.0.0/8"]) | | behavioral.max_requests_per_minute | Rate limit per IP address (default: 30) | | branding.enabled | Enable Microsoft tenant branding proxy | | branding.allowed_origins | CORS allowed origins for branding endpoint (use ["*"] for all) |

CLI Options

| Flag | Description | |------|-------------| | --config | Path to config.json (default: ./config.json) | | --domain | Domain for Let's Encrypt SSL | | --disable-mailer | Disable built-in mailer | | --mode | Run mode: all, admin, or phish |

Endpoints

| Endpoint | Description | |----------|-------------| | https://localhost:3333 | Admin panel | | https://your-domain:443 | Phishing server | | https://your-domain:443/branding?email=user@company.com | Microsoft tenant branding proxy |

API

PhishHook is fully compatible with the GoPhish API.

# Example: List campaigns
curl -k -H "Authorization: Bearer YOUR_API_KEY" https://localhost:3333/api/campaigns/

How It Works

User clicks phishing link
         |
         v
  +-------------------+
  | Behavioral Check  |
  | - IP blocking     |
  | - Rate limiting   |
  +-------------------+
         |
    Blocked? Pass
         |
   +-----+-----+
   |           |
   v           v
 404 Page   +----------------+
            | Turnstile      |
            | Challenge Page |
            | + JS Telemetry |
            +----------------+
                   |
              Bot? |  Human?
                   |
             +-----+-----+
             |           |
             v           v
          Blocked    Solve Challenge
          (no click     |
           recorded)    v
                   +-----------------+
                   | Telemetry Check |
                   | - Time on page  |
                   | - Mouse moves   |
                   | - Interactions  |
                   +-----------------+
                          |
                     Pass | Fail
                          |
                    +-----+-----+
                    |           |
                    v           v
               +----------+  404 Page
               | Landing  |
               | Page     |
               | (click   |
               | recorded)|
               +----------+

Microsoft Tenant Branding

PhishHook can automatically fetch an organization's custom Microsoft 365 login branding, making phishing pages nearly indistinguishable from the real thing.

How it works:

Landing page includes {{.BrandingURL}} template variable
When page loads, JavaScript calls the branding endpoint with the target's email
PhishHook queries Microsoft's GetCredentialType API
Returns the organization's custom background image, logo, and boilerplate text
Landing page applies the branding dynamically

Usage in landing pages:

fetch('{{.BrandingURL}}?email={{.Email}}')
  .then(r => r.json())
  .then(data => {
    if (data.userTenantBranding) {
      document.body.style.backgroundImage = 'url(' + data.backgroundImageUrl + ')';
    }
  });

Response format:

{
  "success": true,
  "backgroundImageUrl": "https://aadcdn.msauthimages.net/...",
  "bannerLogoUrl": "https://aadcdn.msauthimages.net/...",
  "boilerPlateText": "<p>Custom login text...</p>",
  "userTenantBranding": true
}

Behavioral Detection

The behavioral detection layer runs before Turnstile and blocks requests based on:

IP Blocking: Requests from Microsoft 365/Exchange Online Protection IP ranges are blocked immediately. These ranges are sourced from the official Microsoft 365 endpoints API.
Rate Limiting: IPs making more than max_requests_per_minute requests are temporarily blocked.
JS Telemetry: The challenge page collects behavioral signals:
- Time spent on page before submission
- Mouse movement count
- Click and scroll events
- Touch events (mobile)
- Screen dimensions and WebGL support

Safe Links typically hits within seconds of email delivery with no interaction events, making it easy to distinguish from real users.

License

MIT License - Based on GoPhish by Jordan Wright

Disclaimer

This tool is intended for authorized security testing and red team operations only. Unauthorized use against systems you do not own or have explicit permission to test is illegal. Always obtain proper written authorization before conducting phishing assessments.

PhishHook

Install / Use

README