Getting Started Guide for Bug Hunters

Getting Started Guide for Bug Hunters

A step-by-step setup guide for new users. By the end of this guide, you'll have the repository installed, tools configured, API keys set up, and your first automated reconnaissance workflow running.

---

📋 Prerequisites

Before you begin, ensure you have:

Requirement	Minimum Version	How to Check
Operating System	Linux (recommended) or macOS	uname -a
Git	2.30+	git --version
Python	3.6+	python3 --version
Bash	4.0+	bash --version
pip3	Latest	pip3 --version
curl	Any recent version	curl --version
Disk Space	~500 MB free	df -h

Windows Users: Use Windows Subsystem for Linux (WSL2) for full compatibility. Install WSL2 with Ubuntu, then follow this guide within your WSL terminal.

---

🚀 Step 1: Clone and Explore the Repository

1.1 Clone the Repository

# Navigate to your preferred directory
cd ~/Documents

# Clone the repository
git clone https://github.com/aw-junaid/bug-bounty.git

# Enter the project directory
cd bug-bounty

1.2 Understand the Structure

Take 5 minutes to familiarize yourself with the layout:

# View the top-level structure
ls -la

# You should see:
# course/          - Structured learning curriculum
# methodologies/   - In-depth exploitation guides
# resources/       - Cheatsheets, templates, wordlists
# tools/           - Automation, recon, exploitation scripts
# write-ups/       - Real-world bug bounty reports
# LICENSE          - MIT License
# README.md        - Main repository documentation

Quick Tour:

Directory	Purpose	Example Content
methodologies/web penetration/	How to find and exploit vulnerabilities	SQL Injection.md, XSS.md
methodologies/web technologies/	Platform-specific exploitation	WordPress Penetration Testing.md
resources/cheatsheets/	Quick-reference commands	SQL-Injection.md
resources/templates/	Bug report format	bug-report-template.md
resources/wordlists/	Fuzzing and discovery lists	xss-payloads.txt
tools/automation/	Workflow scripts	bug-bounty-workflow.sh
tools/exploitation/	Vulnerability testers	sqli-tester.py
tools/reconnaissance/	Enumeration scripts	subdomain-enum.py
tools/utilities/	Helper tools	payload-generator.py

Read: Want a deeper dive? See Understanding the Repository Structure.

---

🛠️ Step 2: Install Required Dependencies

2.1 System Dependencies

# Update package lists (Ubuntu/Debian)
sudo apt update

# Install essential system packages
sudo apt install -y \
    git \
    python3 \
    python3-pip \
    curl \
    wget \
    jq \
    dnsutils \
    whois

# For macOS (using Homebrew)
brew install \
    git \
    python3 \
    curl \
    wget \
    jq \
    bind \
    whois

2.2 Install Python Dependencies

The repository's Python tools have minimal dependencies. Install them all at once:

# Enter the bug-bounty directory
cd ~/Documents/bug-bounty

# Install core Python packages used by multiple tools
pip3 install --user \
    requests \
    beautifulsoup4 \
    dnspython \
    colorama \
    argparse

# Verify installation
pip3 list | grep -E "requests|beautifulsoup4|dnspython"

2.3 Install External Recon Tools (Recommended)

The bug-bounty-workflow.sh script integrates with popular open-source tools. Install the ones you want:

# ---- Subdomain Enumeration ----

# Subfinder (ProjectDiscovery)
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest

# Amass (OWASP)
go install -v github.com/owasp-amass/amass/v4/...@master

# ---- HTTP Probing ----

# httpx (ProjectDiscovery)
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest

# ---- Vulnerability Scanning ----

# Nuclei (ProjectDiscovery)
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# ---- Directory Fuzzing ----

# ffuf
go install -v github.com/ffuf/ffuf/v2@latest

# ---- Ensure Go binaries are in PATH ----
export PATH=$PATH:$HOME/go/bin
echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc
source ~/.bashrc

Note: If you don't have Go installed, download it from go.dev/dl or use sudo apt install golang-go (Ubuntu). Minimum Go version: 1.19+.

2.4 (Optional) Install API-Only Tools

Some users prefer these additional tools:

# Shodan CLI for service enumeration
pip3 install --user shodan

# Waybackurls for historical URL discovery
go install -v github.com/tomnomnom/waybackurls@latest

# GF pattern-based URL filtering
go install -v github.com/tomnomnom/gf@latest

---

🔑 Step 3: Configure API Keys for Reconnaissance

Many reconnaissance tools require API keys for services like Shodan, SecurityTrails, and Censys. Here's how to set them up:

3.1 Create the Configuration Directory

# Create config directory for tools
mkdir -p ~/.config/{subfinder,amass,nuclei}

# Create a secure directory for API keys
mkdir -p ~/.bugbounty
chmod 700 ~/.bugbounty

3.2 Obtain Free API Keys

Service	Purpose	Free Tier	Registration Link
SecurityTrails	DNS history, subdomains	50 req/month	securitytrails.com
Shodan	Service discovery	Limited queries	shodan.io
Censys	Certificate transparency	250 req/month	censys.io
GitHub Token	GitHub dorking, code search	5000 req/hr	github.com/settings/tokens
Chaos (ProjectDiscovery)	Subdomain dataset	Free	chaos.projectdiscovery.io

3.3 Configure API Keys

Method 1: Environment Variables (Recommended)

Create a secure credentials file:

# Create credentials file
cat > ~/.bugbounty/credentials.sh << 'EOF'
#!/bin/bash

# SecurityTrails
export SECURITYTRAILS_API_KEY="your-key-here"

# Shodan
export SHODAN_API_KEY="your-key-here"

# Censys
export CENSYS_API_ID="your-id-here"
export CENSYS_API_SECRET="your-secret-here"

# GitHub Token (for dorking, no special scopes needed)
export GITHUB_TOKEN="ghp_yourtokenhere"

# Chaos (ProjectDiscovery)
export CHAOS_KEY="your-chaos-key-here"
EOF

# Set proper permissions
chmod 600 ~/.bugbounty/credentials.sh

# Load credentials for current session
source ~/.bugbounty/credentials.sh

# Auto-load on shell startup
echo 'source ~/.bugbounty/credentials.sh 2>/dev/null' >> ~/.bashrc

Method 2: Tool-Specific Configuration

# Configure Subfinder
cat > ~/.config/subfinder/provider-config.yaml << 'EOF'
securitytrails:
  - your-securitytrails-api-key
censys:
  - your-censys-api-id:your-censys-api-secret
chaos:
  - your-chaos-api-key
github:
  - your-github-token
EOF

chmod 600 ~/.config/subfinder/provider-config.yaml

3.4 Verify Your API Configuration

# Test Subfinder with API keys
subfinder -d example.com -s securitytrails -silent

# Test Shodan CLI
shodan info

# Test your credentials file
source ~/.bugbounty/credentials.sh
echo "SecurityTrails Key: ${SECURITYTRAILS_API_KEY:0:5}..."  # Should show first 5 chars

---

⚡ Step 4: Make the Automation Scripts Executable

# Navigate to the tools directory
cd ~/Documents/bug-bounty/tools

# Make the main workflow script executable
chmod +x automation/bug-bounty-workflow.sh

# Make all script files executable
chmod +x reconnaissance/subdomain-enum.py
chmod +x reconnaissance/url-collector.sh
chmod +x exploitation/sqli-tester.py
chmod +x exploitation/xss-scanner.py
chmod +x utilities/payload-generator.py
chmod +x utilities/wordlist-merger.sh

# Return to repository root
cd ~/Documents/bug-bounty

---

🎯 Step 5: Run Your First Automated Workflow

5.1 Understanding the Workflow

The bug-bounty-workflow.sh script chains together multiple reconnaissance and scanning steps:

┌────────────────────────────────────────────────────────────┐
│              BUG BOUNTY AUTOMATION WORKFLOW                 │
└────────────────────────────────────────────────────────────┘
                            │
                            ▼
                ┌───────────────────────┐
                │  1. Create Output     │
                │     Directory         │
                └───────────────────────┘
                            │
                            ▼
                ┌───────────────────────┐
                │  2. Subdomain         │
                │     Enumeration       │
                └───────────────────────┘
                            │
                            ▼
                ┌───────────────────────┐
                │  3. DNS Resolution    │
                │     & Validation      │
                └───────────────────────┘
                            │
                            ▼
                ┌───────────────────────┐
                │  4. HTTP Probing      │
                │     (httpx)           │
                └───────────────────────┘
                            │
                            ▼
                ┌───────────────────────┐
                │  5. Technology        │
                │     Detection         │
                └───────────────────────┘
                            │
                            ▼
                ┌───────────────────────┐
                │  6. URL Collection    │
                │     (wayback, GAU)    │
                └───────────────────────┘
                            │
                            ▼
                ┌───────────────────────┐
                │  7. Vulnerability     │
                │     Scanning (Nuclei) │
                └───────────────────────┘
                            │
                            ▼
                ┌───────────────────────┐
                │  8. Generate Report   │
                └───────────────────────┘

5.2 Choose Your Test Target

⚠️ IMPORTANT: Only test targets you own or have explicit written permission to test!

Safe Practice Targets	Purpose
testasp.vulnweb.com	Acunetix test PHP site (intentionally vulnerable)
testphp.vulnweb.com	Acunetix test ASP site
Your own VPS/domain	Full control, no legal risk
Local lab (Docker)	docker run -d -p 80:80 vulnerables/web-dvwa

5.3 Run the Workflow

Option A: Basic Run (Minimal Tools)

cd ~/Documents/bug-bounty

# Run against a safe test target
./tools/automation/bug-bounty-workflow.sh testphp.vulnweb.com

# With a custom output directory
./tools/automation/bug-bounty-workflow.sh testphp.vulnweb.com -o ./recon-results/acunetix-php

Option B: Full Run (All Tools Available)

# Source your API credentials first
source ~/.bugbounty/credentials.sh

# Run the full workflow
./tools/automation/bug-bounty-workflow.sh example.com \
    --output ./recon-results/example-com \
    --full-scan \
    --nuclei-templates ~/nuclei-templates

5.4 Understand the Output

After the workflow completes, examine your results:

recon-results/
└── example-com/
    ├── subdomains/
    │   ├── subdomains.txt          # All discovered subdomains
    │   ├── live-subdomains.txt     # HTTP/HTTPS responsive subdomains
    │   └── subdomains-resolved.txt # DNS-resolved subdomains
    ├── urls/
    │   ├── all-urls.txt            # Collected URLs from all sources
    │   ├── wayback-urls.txt        # Wayback Machine URLs
    │   └── js-files.txt            # JavaScript file URLs
    ├── scans/
    │   ├── nuclei-results.txt      # Nuclei vulnerability findings
    │   └── technology-stack.txt    # Detected technologies per host
    ├── endpoints/
    │   └── interesting-paths.txt   # Discovered interesting endpoints
    └── report/
        └── recon-report.txt        # Summary report of findings

5.5 Review Your Findings

# Quick summary of findings
cat recon-results/example-com/report/recon-report.txt

# Check for vulnerabilities
grep -E "critical|high|medium" recon-results/example-com/scans/nuclei-results.txt

# List all live subdomains
cat recon-results/example-com/subdomains/live-subdomains.txt

# Count total discovered assets
echo "Subdomains: $(wc -l < recon-results/example-com/subdomains/subdomains.txt)"
echo "Live hosts: $(wc -l < recon-results/example-com/subdomains/live-subdomains.txt)"
echo "URLs found: $(wc -l < recon-results/example-com/urls/all-urls.txt)"

---

🧪 Step 6: Run Your First Manual Test

Automation is great, but real bug hunting requires manual testing. Here's a quick exercise:

6.1 Run the XSS Scanner on Collected URLs

# Use the XSS scanner against collected URLs
python3 tools/exploitation/xss-scanner.py \
    --input recon-results/example-com/urls/all-urls.txt \
    --output xss-findings.txt

# Review findings
cat xss-findings.txt

6.2 Test a Single Endpoint Manually

# Grab a URL with parameters from your recon
head -5 recon-results/example-com/urls/all-urls.txt

# Example output: https://example.com/search.php?q=test

# Test for XSS manually
curl -s "https://example.com/search.php?q=<script>alert(1)</script>"

# Test for SQL injection
python3 tools/exploitation/sqli-tester.py --url "https://example.com/search.php?q=test"

6.3 Generate Custom Payloads

# Generate context-specific XSS payloads
python3 tools/utilities/payload-generator.py \
    --type xss \
    --context "search box with character limit" \
    --output custom-xss.txt

# Generate SQLi payloads with WAF bypass attempts
python3 tools/utilities/payload-generator.py \
    --type sqli \
    --waf cloudflare \
    --output custom-sqli.txt

---

✅ Step 7: Verify Your Setup

Run this verification checklist to confirm everything works:

#!/bin/bash
# Save as verify-setup.sh and run: bash verify-setup.sh

echo "======================================="
echo "  Bug Bounty Setup Verification Test  "
echo "======================================="
echo ""

# Check 1: Repository structure
echo "[1/7] Checking repository structure..."
[ -f "README.md" ] && echo "  ✓ README.md found" || echo "  ✗ README.md missing"
[ -d "methodologies" ] && echo "  ✓ methodologies/ found" || echo "  ✗ methodologies/ missing"
[ -d "tools" ] && echo "  ✓ tools/ found" || echo "  ✗ tools/ missing"
[ -d "resources" ] && echo "  ✓ resources/ found" || echo "  ✗ resources/ missing"

# Check 2: Python version
echo ""
echo "[2/7] Checking Python..."
python3 --version && echo "  ✓ Python OK" || echo "  ✗ Python not found"

# Check 3: Python dependencies
echo ""
echo "[3/7] Checking Python dependencies..."
python3 -c "import requests" 2>/dev/null && echo "  ✓ requests installed" || echo "  ✗ requests missing"
python3 -c "import bs4" 2>/dev/null && echo "  ✓ beautifulsoup4 installed" || echo "  ✗ beautifulsoup4 missing"
python3 -c "import dns" 2>/dev/null && echo "  ✓ dnspython installed" || echo "  ✗ dnspython missing"

# Check 4: Tool executability
echo ""
echo "[4/7] Checking tool permissions..."
[ -x "tools/automation/bug-bounty-workflow.sh" ] && echo "  ✓ Workflow script executable" || echo "  ✗ Workflow script not executable"
[ -x "tools/exploitation/sqli-tester.py" ] && echo "  ✓ SQLi tester executable" || echo "  ✗ SQLi tester not executable"
[ -x "tools/exploitation/xss-scanner.py" ] && echo "  ✓ XSS scanner executable" || echo "  ✗ XSS scanner not executable"

# Check 5: External tools (optional)
echo ""
echo "[5/7] Checking external tools (optional)..."
command -v subfinder &>/dev/null && echo "  ✓ subfinder installed" || echo "  - subfinder not installed (optional)"
command -v nuclei &>/dev/null && echo "  ✓ nuclei installed" || echo "  - nuclei not installed (optional)"
command -v ffuf &>/dev/null && echo "  ✓ ffuf installed" || echo "  - ffuf not installed (optional)"
command -v httpx &>/dev/null && echo "  ✓ httpx installed" || echo "  - httpx not installed (optional)"

# Check 6: API credentials (optional)
echo ""
echo "[6/7] Checking API credentials (optional)..."
[ -n "$SECURITYTRAILS_API_KEY" ] && echo "  ✓ SecurityTrails API key set" || echo "  - SecurityTrails API key not set (optional)"
[ -n "$SHODAN_API_KEY" ] && echo "  ✓ Shodan API key set" || echo "  - Shodan API key not set (optional)"

# Check 7: Quick tool test
echo ""
echo "[7/7] Running quick functionality test..."
python3 tools/utilities/payload-generator.py --type xss --context test 2>/dev/null | head -3
[ $? -eq 0 ] && echo "  ✓ Payload generator works" || echo "  ✗ Payload generator failed"

echo ""
echo "======================================="
echo "  Setup Verification Complete!        "
echo "======================================="
echo ""
echo "Next Steps:"
echo "  1. Read the FAQ: wiki/FAQ"
echo "  2. Start the course: course/README.md"
echo "  3. Join Discord: https://discord.gg/Neddn8gPqY"

Run the verification:

bash verify-setup.sh

---

🔧 Troubleshooting Common Issues

Problem	Likely Cause	Solution
python3: command not found	Python 3 not installed	sudo apt install python3
ModuleNotFoundError: No module named 'requests'	Missing pip package	pip3 install requests
Permission denied: bug-bounty-workflow.sh	Script not executable	chmod +x tools/automation/bug-bounty-workflow.sh
subfinder: command not found	Go binary path not in PATH	export PATH=$PATH:$HOME/go/bin
API keys not working	Keys not exported or malformed	Run source ~/.bugbounty/credentials.sh
fatal: destination path already exists	Already cloned the repo	Navigate to existing directory or remove it
Workflow script exits immediately	No target specified	Always provide a target: ./script.sh example.com
Git clone permission denied	SSH key issue or repo access	Use HTTPS: git clone https://github.com/aw-junaid/bug-bounty.git
WSL: Scripts fail with Windows line endings	CRLF vs LF issue	Run sed -i 's/\r$//' tools/automation/bug-bounty-workflow.sh

---

📚 Next Steps in Your Journey

Now that your environment is set up, here's where to go based on your goals:

Your Goal	Next Resource
Learn web vulnerabilities systematically	Course Materials
Start hunting on real programs	FAQ#i-found-a-bug-where-do-i-report-it
Master a specific vulnerability	Complete Vulnerability Index
Understand the repo deeply	Understanding the Repository Structure
Automate everything	Recon Automation Pipeline: A Deep Dive
Read real-world examples	Write-ups Index
Meet the community	Join Discord

---

🎓 Quick Reference Card

Save this as a reference for your daily workflow:

# ┌─────────────────────────────────────────────────────────┐
# │             DAILY BUG BOUNTY COMMANDS                   │
# └─────────────────────────────────────────────────────────┘

# Source API credentials
source ~/.bugbounty/credentials.sh

# Full automated recon
./tools/automation/bug-bounty-workflow.sh TARGET.COM

# Manual subdomain discovery
subfinder -d TARGET.COM -o subs.txt

# Check live hosts
httpx -l subs.txt -o live.txt

# Collect URLs
cat live.txt | waybackurls > urls.txt

# Scan for vulnerabilities
nuclei -l live.txt -t ~/nuclei-templates/

# Fuzz directories
ffuf -u https://TARGET.COM/FUZZ -w resources/wordlists/directories-small.txt

# Test SQL injection
python3 tools/exploitation/sqli-tester.py --url "TARGET"

# Scan for XSS
python3 tools/exploitation/xss-scanner.py --input urls.txt

# Generate payloads
python3 tools/utilities/payload-generator.py --type xss

---