How to Contribute

How to Contribute

A complete guide to contributing to the Bug Bounty Knowledge Base. Whether you're fixing a typo, adding a new methodology, or building a tool — this guide has you covered.

---

📋 Table of Contents

• Code of Conduct
• Ways to Contribute
• Getting Started
• Contribution Workflow
• Style Guides
• Commit Message Conventions
• Pull Request Process
• Review Process
• Recognition & Credits

---

📜 Code of Conduct

Read this first. All contributors must adhere to our Code of Conduct.

In short:

• Be respectful and inclusive
• No harassment, trolling, or personal attacks
• Focus on constructive feedback
• Respect ethical boundaries — all contributions must be for authorized testing only
• Report unacceptable behavior to the maintainers

Violations may result in removal from the community.

---

🎯 Ways to Contribute

Every contribution matters. Here's how you can help, from smallest to largest effort:

Quick Wins (No Coding Required)

Contribution Type	Time Required	Impact
Fix typos and grammar	5-10 minutes	📚 Improves readability
Improve existing explanations	15-30 minutes	🧠 Helps beginners understand better
Add missing references/links	10-20 minutes	🔗 Better interconnectedness
Report outdated techniques	5 minutes	📅 Keeps content current
Suggest new content ideas	10 minutes	💡 Shapes the roadmap

Medium Effort

Contribution Type	Time Required	Impact
Write a new cheatsheet	1-2 hours	⚡ Quick reference for others
Add a write-up	1-3 hours	📖 Real-world learning material
Improve existing tools	2-4 hours	🛠️ Better functionality
Create a new wordlist	1-2 hours	🎯 Better recon results
Translate existing content	2-5 hours	🌍 Accessibility

Major Contributions

Contribution Type	Time Required	Impact
Write a full methodology	3-8 hours	⚔️ New attack knowledge
Build a new tool/script	5-20 hours	🤖 Automation for everyone
Create a course module	5-15 hours	🎓 Structured learning
Add a target profile (e.g., HackerOne, Bugcrowd)	3-6 hours	🎯 Platform intelligence
Comprehensive security research	Ongoing	🔬 Pushing boundaries

---

🚀 Getting Started

Step 1: Set Up Your Environment

# Fork the repository (do this on GitHub.com first)

# Clone your fork
git clone https://github.com/YOUR-USERNAME/bug-bounty.git
cd bug-bounty

# Add the upstream remote
git remote add upstream https://github.com/aw-junaid/bug-bounty.git

# Verify remotes
git remote -v
# origin    https://github.com/YOUR-USERNAME/bug-bounty.git (fetch)
# origin    https://github.com/YOUR-USERNAME/bug-bounty.git (push)
# upstream  https://github.com/aw-junaid/bug-bounty.git (fetch)
# upstream  https://github.com/aw-junaid/bug-bounty.git (push)

# Create a branch for your contribution
git checkout -b contribution/my-awesome-addition

Step 2: Find Something to Work On

Source	Link
GitHub Issues labeled good first issue	Issues
GitHub Issues labeled help wanted	Issues
Content that needs improvement	Search repo for TODO, FIXME, WIP
Your own ideas	Open an issue first to discuss

Step 3: Sync with Upstream

Always work from the latest version:

# Fetch upstream changes
git fetch upstream

# Switch to main branch
git checkout main

# Merge upstream changes
git merge upstream/main

# Update your fork on GitHub
git push origin main

# Rebase your contribution branch
git checkout contribution/my-awesome-addition
git rebase main

---

🔄 Contribution Workflow

┌─────────────────────────────────────────────────────────────┐
│                 CONTRIBUTION LIFECYCLE                       │
└─────────────────────────────────────────────────────────────┘
                            │
                ┌───────────┴───────────┐
                ▼                       ▼
        ┌──────────────┐        ┌──────────────┐
        │  Open an     │        │  Find an     │
        │  Issue       │        │  existing    │
        │  (New idea)  │        │  issue       │
        └──────┬───────┘        └──────┬───────┘
               │                       │
               └───────────┬───────────┘
                           ▼
                ┌─────────────────────┐
                │   Discuss & Get     │
                │   Approval          │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │   Fork & Clone      │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │   Create Branch     │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │   Make Changes      │
                │   Follow Style      │
                │   Guides            │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │   Test Your         │
                │   Changes           │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │   Commit with       │
                │   Proper Message    │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │   Push to Your      │
                │   Fork              │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │   Open Pull         │
                │   Request           │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │   Address Review    │
                │   Feedback          │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │   PR Merged! 🎉     │
                └─────────────────────┘

---

📝 Style Guides

Consistency makes the repository maintainable. Follow these conventions for every contribution.

General Markdown Style

# Use Title Case for Top-Level Headings

## Use Title Case for Second-Level Headings

### Use Title Case for Third-Level Headings

#### Use Title Case for Fourth-Level Headings (Rarely Needed)

**Bold** for emphasis on key terms, tools, and warnings.

*Italic* for file paths, variable names, and light emphasis.

`inline code` for commands, payloads, file names, and technical terms.

> Blockquotes for important notes, tips, and warnings.

---

Horizontal rules (`---`) to separate major sections.

Methodology File Template

All new methodology files should follow this structure:

# [Vulnerability/Technology Name]

> A one-sentence description of what this guide covers.

## 📋 Table of Contents (Optional, for long guides)

- [Overview](#overview)
- [Detection](#detection)
- [Exploitation](#exploitation)
- [Advanced Techniques](#advanced-techniques)
- [Remediation](#remediation)
- [References](#references)

---

## Overview

Brief explanation of the vulnerability/technology. What is it? Why does it matter?

- **Severity:** Critical / High / Medium / Low
- **Prerequisites:** What you need to know before reading
- **Common In:** Where this vulnerability typically appears

---

## Detection

How to identify if this vulnerability exists.

### Manual Detection

Step-by-step manual testing approach.

### Automated Detection

Tools and commands to detect at scale.

```bash
# Example command
tool-name --target https://example.com --check xss

---

Exploitation

Basic Exploitation

Simple, reliable exploitation techniques.

Payload:

<insert payload here>

Steps:

1. Step one with explanation
2. Step two with explanation
3. Verify the impact

Advanced Exploitation

Bypasses, chaining, and advanced scenarios.

---

Remediation

Brief guidance on fixing the vulnerability (for reports).

---

References

• Link Title
• Another Reference

---

⚠️ Warning: Standard ethical testing disclaimer.

### Cheatsheet File Template

Cheatsheets should be concise and command-focused:

```markdown
# [Topic] Cheatsheet

> Quick reference for [vulnerability/technology].

## Common Payloads

```payload
payload1
payload2

Commands

# Tool-specific commands
tool-name --flag value

Bypass Techniques

Technique	Payload/Command	Notes
Technique 1	payload	When to use
Technique 2	payload	When to use

Quick Detection

# One-liner for quick check
curl -s "https://target.com/?param=test"

### Write-up File Template

```markdown
# [Target/Program Name] — [Vulnerability Summary]

| Field | Details |
|:---|:---|
| **Program** | HackerOne / Bugcrowd / Private |
| **Target** | example.com |
| **Vulnerability** | Stored XSS, IDOR, SSRF, etc. |
| **Severity** | Critical / High / Medium / Low |
| **Bounty** | $X,XXX (if applicable) |
| **Date** | Month Year |

---

## Summary

One paragraph explaining what was found and its impact.

---

## Reconnaissance

How the target was discovered and analyzed.

---

## Discovery

How the vulnerability was found.

---

## Exploitation / Proof of Concept

Step-by-step reproduction with screenshots and code blocks.

```http
GET /vulnerable-endpoint HTTP/1.1
Host: example.com

---

Impact

What an attacker could achieve with this vulnerability.

---

Remediation

How the vulnerability was or should be fixed.

---

Timeline

Date	Event
Date 1	Reported
Date 2	Triaged
Date 3	Resolved
Date 4	Bounty Awarded

---

Lessons Learned

What you learned from finding and reporting this bug.

### Tool/Script File Standards

**Python Scripts:**

```python
#!/usr/bin/env python3
"""
Tool Name: Short description of what this tool does.

Usage:
    python3 tool-name.py --target https://example.com

Dependencies:
    pip3 install requests beautifulsoup4

Author: Your Name (@yourhandle)
License: MIT
"""

import argparse
import sys
from typing import Optional

def main():
    """Main execution function."""
    parser = argparse.ArgumentParser(
        description="Tool description"
    )
    parser.add_argument(
        "--target",
        required=True,
        help="Target URL to test"
    )
    args = parser.parse_args()
    
    # Tool logic here
    print(f"[+] Testing {args.target}")

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\n[!] Interrupted by user")
        sys.exit(1)

Bash Scripts:

#!/bin/bash
#
# Script Name: Short description
#
# Usage: ./script-name.sh <target>
#
# Dependencies: tool1, tool2
#
# Author: Your Name (@yourhandle)
# License: MIT

set -euo pipefail  # Exit on error, undefined var, pipe failure

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

function usage() {
    echo "Usage: $0 <target-domain>"
    echo "Example: $0 example.com"
    exit 1
}

# Check arguments
if [ $# -ne 1 ]; then
    usage
fi

TARGET="$1"
echo -e "${GREEN}[+] Starting scan on $TARGET${NC}"

# Script logic here

File Naming Conventions

Content Type	Naming Convention	Example
Methodology (Web Pen)	Descriptive Name.md	File Upload Vulnerabilities.md
Methodology (Web Tech)	Platform/Technology Name.md	WordPress Penetration Testing.md
Cheatsheet	Same Name as Methodology.md	File Upload.md
Course Module	Descriptive-Topic-Name.md	Python-Programming.md
Tool (Python)	kebab-case-name.py	sql-injection-tester.py
Tool (Bash)	kebab-case-name.sh	url-collector.sh
Write-up	target-name.md	slack.md
Wordlist	descriptive-name.txt	xss-payloads.txt

Content Standards

Do:

• ✅ Use clear, concise language
• ✅ Include practical examples and commands
• ✅ Add code blocks with syntax highlighting
• ✅ Link to related resources within the repo
• ✅ Include detection steps before exploitation
• ✅ Add the standard ethical warning at the end
• ✅ Cite sources and references

Don't:

• ❌ Copy-paste from other sources without attribution
• ❌ Include actual client data or real targets
• ❌ Use overly technical jargon without explanation
• ❌ Skip the detection phase — exploitation without detection is useless
• ❌ Add broken or unverified commands/payloads
• ❌ Include malicious or destructive payloads without warnings

---

💬 Commit Message Conventions

Follow the Conventional Commits specification.

Format

<type>(<scope>): <short description>

[optional body]

[optional footer(s)]

Types

Type	When to Use
feat	Adding a new methodology, tool, cheatsheet, or feature
fix	Fixing a bug, typo, broken command, or incorrect information
docs	Documentation-only changes (README, comments, wiki)
style	Formatting, markdown linting, whitespace (no content change)
refactor	Restructuring code without changing behavior
test	Adding or updating tests
chore	Maintenance tasks, dependency updates

Scopes

Scope	For Changes To
methodology	Files in methodologies/
cheatsheet	Files in resources/cheatsheets/
wordlist	Files in resources/wordlists/
template	Files in resources/templates/
tool	Files in tools/
course	Files in course/
write-up	Files in write-ups/
profile	Files in profiles/
docs	Root documentation files
workflow	CI/CD and automation files

Examples

Good Commits:

feat(methodology): add HTTP Request Smuggling methodology

Added comprehensive guide covering CL.TE, TE.CL, and TE.TE
desync attacks with detection and exploitation techniques.
Includes real-world examples and Nuclei template references.

Closes #42

fix(cheatsheet): correct SQLi union payload syntax

Fixed incorrect column count enumeration syntax in the
ORDER BY technique section. Updated with verified payloads.

Reported-by: @security-researcher

docs(readme): update installation instructions for macOS

Added Homebrew commands and fixed Python path references
for Apple Silicon Macs.

feat(tool): add GraphQL introspection scanner

New Python script for automated GraphQL endpoint discovery
and schema enumeration. Supports query depth analysis.

Co-authored-by: @contributor <email@example.com>

chore(wordlist): merge and deduplicate directory wordlist

Removed 200+ duplicate entries and sorted alphabetically
for better performance with ffuf and gobuster.

Bad Commits (Avoid These):

# Too vague
fix stuff

# No type specified
updated the file

# Too long, should be in body
feat: added a new methodology and also fixed a bug and updated some docs and changed some formatting

# No scope
feat: add new guide

---

📬 Pull Request Process

Before You Submit

Checklist:

• Your branch is up-to-date with upstream/main
• You've followed the relevant style guide
• Commands and payloads are verified and working
• Code is tested (for tools/scripts)
• No sensitive data is included
• Links to related issues are in the PR description
• You've read the Code of Conduct

PR Title Format

Follow the same convention as commits:

<type>(<scope>): <short description>

PR Description Template

Copy this template into your pull request:

## Description
<!-- Brief description of what this PR does -->

## Type of Change
- [ ] New methodology
- [ ] New cheatsheet
- [ ] New tool/script
- [ ] New write-up
- [ ] New wordlist
- [ ] Bug fix
- [ ] Documentation improvement
- [ ] Other: ___________

## Related Issues
<!-- Link to issues this PR addresses -->
Closes #___

## Testing Performed
<!-- How did you test your changes? -->
- [ ] Verified all commands/payloads
- [ ] Tested tool/script on sample target
- [ ] Checked markdown formatting
- [ ] Reviewed for sensitive data

## Screenshots (if applicable)
<!-- Add screenshots of tool output, markdown rendering, etc. -->

## Checklist
- [ ] I have read the [Code of Conduct](CODE_OF_CONDUCT.md)
- [ ] I have followed the [Style Guides](link-to-wiki)
- [ ] My commits follow [conventional commits](https://www.conventionalcommits.org/)
- [ ] All content is for authorized testing only
- [ ] I have added appropriate references and citations
- [ ] No sensitive or proprietary data is included

The PR Lifecycle

┌─────────────────────────────────────────────────────────┐
│                   PULL REQUEST LIFECYCLE                 │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
                ┌─────────────────────┐
                │  PR Opened          │
                │  (Draft or Ready)   │
                └──────────┬──────────┘
                           ▼
                ┌─────────────────────┐
                │  Automated Checks   │
                │  • Linting          │
                │  • Links valid?     │
                │  • Commit format?   │
                └──────────┬──────────┘
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
        ┌──────────┐            ┌──────────────┐
        │ Checks   │            │ Checks Fail  │
        │ Pass     │            │ → Fix & Push │
        └────┬─────┘            └──────────────┘
             ▼
    ┌─────────────────┐
    │  Maintainer     │
    │  Review         │
    └────────┬────────┘
             │
    ┌────────┴────────┐
    ▼                 ▼
┌──────────┐   ┌──────────────┐
│ Approved │   │ Changes      │
│          │   │ Requested    │
└────┬─────┘   └──────┬───────┘
     │                │
     │                ▼
     │        ┌──────────────┐
     │        │ Author Makes │
     │        │ Changes      │
     │        └──────┬───────┘
     │               │
     │               ▼
     │        ┌──────────────┐
     │        │ Re-Review    │
     │        └──────┬───────┘
     │               │
     └───────────────┘
             │
             ▼
    ┌─────────────────┐
    │  PR Merged! 🎉  │
    └─────────────────┘

---

🔍 Review Process

What Reviewers Look For

Aspect	What We Check
Accuracy	Are commands correct? Are payloads valid? Are techniques up-to-date?
Style	Does it follow the style guide? Is formatting consistent?
Completeness	Does it have detection AND exploitation? Are references included?
Ethics	Are warnings present? Is there any sensitive data?
Integration	Does it link to related resources? Does it fit the overall structure?
Originality	Is it original content? Are sources properly cited?

Review Timeline

PR Type	Typical Review Time
Typo/Documentation fix	1-3 days
Cheatsheet/Wordlist	3-5 days
Methodology	5-10 days
New Tool/Script	7-14 days
Major new feature	14-30 days (discussion required)

Tip: Open an issue and discuss before starting major contributions. This prevents wasted effort if the idea doesn't fit the project direction.

Handling Feedback

1. Be open to suggestions — reviewers want to help improve your contribution
2. Ask questions — if feedback is unclear, ask for clarification
3. Push updates — make changes on your branch; the PR updates automatically
4. Be patient — maintainers are volunteers with limited time

---

🏆 Recognition & Credits

How Contributors Are Credited

Contribution Type	Recognition
Merged PR	Name in contributors list, mention in release notes
Major methodology	Attribution in the file header
New tool	Attribution in script docstring
Write-up	Your name and handle on the write-up
Bug fixes	Mentioned in commit history
Long-term contributor	Core contributor status, maintainer consideration

Contributor Tiers

┌─────────────────────────────────────────┐
│         CONTRIBUTOR JOURNEY             │
└─────────────────────────────────────────┘
                    │
                    ▼
        ┌───────────────────┐
        │  First-time       │
        │  Contributor      │
        │  (1 merged PR)    │
        └────────┬──────────┘
                 ▼
        ┌───────────────────┐
        │  Regular          │
        │  Contributor      │
        │  (5+ merged PRs)  │
        └────────┬──────────┘
                 ▼
        ┌───────────────────┐
        │  Core             │
        │  Contributor      │
        │  (15+ merged PRs, │
        │   consistent      │
        │   quality)        │
        └────────┬──────────┘
                 ▼
        ┌───────────────────┐
        │  Maintainer       │
        │  (Invitation only,│
        │   review & merge  │
        │   permissions)    │
        └───────────────────┘

---

📋 Contribution Ideas (If You're Looking for Inspiration)

Methodologies We'd Love to See

• GraphQL subscription-based attacks
• WebRTC security testing
• gRPC API penetration testing
• Kubernetes API exploitation
• AWS Lambda security testing
• Terraform state file exploitation
• Service mesh (Istio/Linkerd) attacks
• WebAssembly security considerations
• AI/LLM prompt injection in web apps
• IoT web interface testing

Tools We'd Love to Have

• GraphQL batch query fuzzer
• JWT brute forcer with key validation
• OAuth flow analyzer and debugger
• Multi-cloud metadata SSRF checker
• WebSocket message fuzzer
• DOM-based XSS scanner with headless browser
• CI/CD pipeline security scanner
• Dependency confusion checker
• Subdomain takeover checker with cloud provider validation
• API schema diff tool (compare documented vs actual API)

Resources We Need

• More write-ups (any bounty, any platform)
• Wordlists for specific technologies (GraphQL endpoints, API paths)
• Bug report examples (anonymized)
• Cheatsheets for missing tools
• Platform profiles (Synack, Intigriti, YesWeHack)
• Course modules on specific topics (API security, cloud testing)

---

🆘 Getting Help

Need Help With	Where to Go
Understanding the codebase	Understanding the Repository Structure
Setting up your environment	Getting Started Guide for Bug Hunters
Discussing an idea	Open an Issue
Quick questions	Discord Community
Style guide questions	This page — leave a comment on the PR
Review process questions	This page — tag @awjunaid in your PR

---

⚠️ Final Reminder

All contributions must be for authorized security testing and educational purposes only. Do not submit:

• Exploits targeting real companies without permission
• Stolen or proprietary data
• Malicious code designed to cause harm
• Content that encourages illegal activity

Violations will result in immediate PR rejection and potential removal from the community.

---

🔗 Related Pages

Page	Link
Code of Conduct	CODE_OF_CONDUCT.md
Security Policy	SECURITY.md
Project Overview	Project Overview & Philosophy
Repository Structure	Understanding the Repository Structure
FAQ	FAQ

---