GoldenEye

Overview

GoldenEye is an open-source HTTP-based DoS (Denial of Service) testing tool written in Python. It is designed for authorized stress testing and capacity planning. GoldenEye generates large amounts of traffic to evaluate how systems handle load, identify bottlenecks, and test failover mechanisms.

IMPORTANT: GoldenEye must only be used on systems you own or have explicit written authorization to test. Unauthorized use is illegal.

Installation

Prerequisites

sudo apt-get update
sudo apt-get install python3 python3-pip git

Clone and Install

git clone https://github.com/jseidl/GoldenEye.git
cd GoldenEye
pip3 install -r requirements.txt

Or via pip (if available)

pip3 install goldeneye

Verify Installation

python3 goldeneye.py --help

Basic Usage

Syntax

python3 goldeneye.py [OPTIONS] <target_url>

Common Command Line Options

Option	Description	Example
-u, --user-agent	Specify custom User-Agent	-u "Mozilla/5.0..."
-w, --workers	Number of workers/threads	-w 50
-r, --requests	Number of requests	-r 1000
-s, --socket-count	Sockets per worker	-s 10
-x, --useproxy	Use HTTP proxy	-x http://proxy:8080
-H, --header	Add custom header	-H "X-Test: value"
-v, --verbose	Verbose output	-v
--method	HTTP method (GET, POST, etc.)	--method POST
--timeout	Connection timeout in seconds	--timeout 10

Quick Start Examples

Basic DoS Test (Authorized Only)

# Simple test with default parameters
python3 goldeneye.py http://test-server.local/

# Test with custom number of threads
python3 goldeneye.py -w 100 http://test-server.local/

# Generate 5000 requests with 50 workers
python3 goldeneye.py -w 50 -r 5000 http://test-server.local/

Detailed Testing Scenario

# Comprehensive stress test
python3 goldeneye.py \
  -w 100 \                    # 100 worker threads
  -r 10000 \                  # 10,000 requests total
  -s 5 \                      # 5 sockets per worker
  --timeout 30 \              # 30 second timeout
  -v \                        # Verbose output
  http://test-server.local/

Custom User-Agent

# Vary user agents to evade simple filters
python3 goldeneye.py \
  -u "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" \
  -w 50 \
  http://test-server.local/

Advanced Usage

Using HTTP Proxy

# Route traffic through proxy (useful for testing behind corporate proxy)
python3 goldeneye.py \
  -x http://192.168.1.100:3128 \
  -w 50 \
  http://test-server.local/

POST-Based Testing

# Send POST requests instead of GET
python3 goldeneye.py \
  --method POST \
  -w 50 \
  -r 1000 \
  http://test-server.local/form-endpoint

Custom Headers

# Add custom headers (e.g., for authorization or API testing)
python3 goldeneye.py \
  -H "Authorization: Bearer token123" \
  -H "X-Custom-Header: test-value" \
  -w 50 \
  http://test-server.local/api/endpoint

Targeting Specific Paths

# Target specific endpoint rather than root
python3 goldeneye.py \
  -w 100 \
  http://test-server.local/api/users/list

# Multiple different paths (sequential)
for path in /api/users /api/posts /api/comments; do
  echo "Testing $path"
  python3 goldeneye.py -w 50 -r 1000 "http://test-server.local$path"
done

Performance Testing Scenarios

Lightweight Load Test

# Suitable for testing small services
python3 goldeneye.py \
  -w 10 \                  # Few workers
  -r 500 \                 # Limited requests
  -s 2 \                   # Few sockets
  http://internal-service.local/

Medium Load Test

# Suitable for mid-tier servers
python3 goldeneye.py \
  -w 50 \
  -r 5000 \
  -s 5 \
  http://test-server.local/

Heavy Load Test

# Significant stress test - use with caution
python3 goldeneye.py \
  -w 200 \
  -r 50000 \
  -s 10 \
  --timeout 5 \
  http://test-server.local/

Monitoring and Analysis

Monitor During Test

# In separate terminal, monitor system resources
watch -n 1 'netstat -an | grep ESTABLISHED | wc -l'

# Monitor CPU and memory
top -p $(pgrep -f goldeneye)

# Monitor network traffic
nethogs

# Check connection states
ss -antp | grep goldeneye

Log Output to File

# Capture verbose output
python3 goldeneye.py -v -w 50 http://test-server.local/ 2>&1 | tee goldeneye_test.log

# Extract statistics from log
grep "requests" goldeneye_test.log
grep "failed" goldeneye_test.log

Rate Limiting Techniques

Slow Ramp-Up

# Start slow to avoid immediate blocking
python3 goldeneye.py -w 5 http://test-server.local/ &
sleep 5
python3 goldeneye.py -w 10 http://test-server.local/ &
sleep 5
python3 goldeneye.py -w 20 http://test-server.local/ &

Distributed Testing

# Distribute load across multiple machines
# Machine 1:
python3 goldeneye.py -w 20 http://test-server.local/

# Machine 2:
python3 goldeneye.py -w 20 http://test-server.local/

# Machine 3:
python3 goldeneye.py -w 20 http://test-server.local/

Request Pacing

# Slower attack with delays between requests
# Requires modification to source code or use of wrapper script
for i in {1..100}; do
  python3 goldeneye.py -w 1 -r 10 http://test-server.local/
  sleep 2  # 2 second delay between batch submissions
done

Custom Testing Script

Python Wrapper for Fine-Grained Control

#!/usr/bin/env python3
import subprocess
import time
import sys

def run_goldeneye_test(target, workers, requests, interval=0):
    """Run GoldenEye with specified parameters"""
    cmd = [
        'python3', 'goldeneye.py',
        '-w', str(workers),
        '-r', str(requests),
        '-v',
        target
    ]
    
    print(f"[*] Starting test: {' '.join(cmd)}")
    try:
        subprocess.run(cmd)
    except KeyboardInterrupt:
        print("\n[!] Test interrupted by user")
        sys.exit(0)
    
    if interval > 0:
        print(f"[*] Waiting {interval} seconds before next test...")
        time.sleep(interval)

# Ramp-up test
targets = [
    ('http://test-server.local/', 10, 1000),
    ('http://test-server.local/', 20, 2000),
    ('http://test-server.local/', 50, 5000),
]

for target, workers, requests in targets:
    run_goldeneye_test(target, workers, requests, interval=10)
    print("[*] Test phase completed\n")

Testing Behind Firewalls

Through Bastion Host

# Via SSH proxy
ssh -L 8080:test-server.local:80 bastion.host \
  python3 goldeneye.py http://localhost:8080/

# Or configure SSH tunneling
ssh -L 8443:test-server.local:443 bastion.host \
  python3 goldeneye.py https://localhost:8443/

Network Interface Binding

# Run from specific network interface
# Modify goldeneye.py source to bind to specific IP
# Or use iptables to route traffic

# View current route
ip route show

# Route specific traffic through interface
sudo ip route add 192.168.100.0/24 via 192.168.1.1 dev eth0

Interpreting Results

Server Response Codes

Code	Meaning	Interpretation
200-299	Success	Server handling requests normally
300-399	Redirect	Server redirecting requests
400-499	Client Error	Request malformed or unauthorized
500-599	Server Error	Server struggling or overwhelmed
Timeout	Connection timeout	Server not responding within limit
Connection Refused	No response	Server shutdown or filtering

Sample Output Analysis

[*] Setting up workers
[*] Initializing 50 workers with 1000 requests each
[*] Starting attack...
[+] Request #100 (2xx: 98, 3xx: 0, 4xx: 2, 5xx: 0)
[+] Request #200 (2xx: 196, 3xx: 0, 4xx: 4, 5xx: 0)
[+] Request #500 (2xx: 485, 3xx: 0, 4xx: 15, 5xx: 0)
[+] Request #1000 (2xx: 950, 3xx: 0, 4xx: 50, 5xx: 0)
[!] Attack finished in 45 seconds
[!] Success rate: 95%

Best Practices

Pre-Test Checklist

• Obtain written authorization for testing
• Document baseline performance metrics
• Notify system administrators
• Have rollback plan ready
• Monitor system during test
• Test during maintenance window when possible
• Start with light load and ramp up gradually
• Have abort command ready (Ctrl+C)

Safe Testing Practices

# 1. Test in isolated environment first
python3 goldeneye.py http://localhost:8080/

# 2. Start with minimal load
python3 goldeneye.py -w 5 -r 100 http://test-server.local/

# 3. Gradually increase load
# (monitor system health between each test)

# 4. Monitor for adverse effects
# - Check error rates
# - Monitor CPU/memory
# - Watch for dropped connections

Troubleshooting

Common Issues

Problem	Solution
Module not found	Install requirements: pip3 install -r requirements.txt
Connection refused	Verify target is reachable: ping test-server.local
Too many open files	Increase ulimit: ulimit -n 65535
Proxy connection fails	Verify proxy URL format and connectivity
Timeout errors	Increase timeout: --timeout 60

Permission Issues

# Handle "too many open files" error
ulimit -n 65535

# Check current limit
ulimit -n

# Permanent change (add to ~/.bashrc)
echo "ulimit -n 65535" >> ~/.bashrc
source ~/.bashrc

Debugging

# Run with maximum verbosity
python3 goldeneye.py -v -v http://test-server.local/

# Strace to see system calls
strace -f python3 goldeneye.py -w 5 http://test-server.local/

# Monitor with tcpdump
sudo tcpdump -i eth0 'host test-server.local' -w goldeneye.pcap

Legal and Ethical Considerations

CRITICAL:

• Only test systems you own or have explicit written authorization to test
• Unauthorized DoS testing is a federal crime in many jurisdictions
• Document all testing activities and results
• Use minimal force necessary for testing objectives
• Cease testing immediately if system becomes unstable
• Report findings responsibly to system administrators

Alternative Tools

Tool	Purpose
Apache Bench (ab)	Simple HTTP benchmarking
Wrk	Modern HTTP benchmarking
Locust	Distributed load testing
JMeter	Complex load testing scenarios
Siege	Web load testing and benchmarking

Resources

• GitHub Repository: https://github.com/jseidl/GoldenEye
• HTTP DoS Testing: https://owasp.org/www-community/attacks/DoS_attacks
• Load Testing Guide: https://www.owasp.org/index.php/Performance_and_Load_Testing
• Python Requests: https://requests.readthedocs.io/