# Contributing Guidelines

Thank you for your interest in contributing to this cybersecurity projects repository! I welcome full project implementations that provide educational value to the security community.

***Contact - [carterperez@certgames.com](mailto:carterperez@certgames.com)***

## Contributing a Full Project

### 1. Fork the Repository

Start by forking the repository to your GitHub account:

**Repository:** [https://github.com/CarterPerez-dev/Cybersecurity-Projects](https://github.com/CarterPerez-dev/Cybersecurity-Projects)

Click the **Fork** button in the top-right corner, then clone your fork locally:

```bash
git clone https://github.com/YOUR-USERNAME/Cybersecurity-Projects.git
cd Cybersecurity-Projects
```

### 2. Create Your Project Directory

Create a new directory in `/PROJECTS/{difficulty}` where difficulty is `beginner`, `intermediate`, or `advanced`. Use a descriptive, lowercase, hyphenated name for your project.

**Naming Convention:**
- ✅ `reverse-shell-handler`
- ✅ `api-security-scanner`
- ✅ `encrypted-p2p-chat`
- ❌ `reverse_shell_handler` (no underscores)
- ❌ `reverse.shell.handler` (no dots)
- ❌ `reverseShellHandler` (no camelCase)
- ❌ `ReverseShellHandler` (no PascalCase)
- ❌ `Reverse-Shell-Handler` (no capital letters)

**Difficulty Levels:**
- **Beginner:** Basic tools, single-file scripts, foundational concepts
- **Intermediate:** Multi-component systems, API integrations, moderate complexity
- **Advanced:** Full-stack applications, distributed systems, complex architectures

**Examples:**

| Project Name | Difficulty | Directory Path |
|-------------|------------|----------------|
| Simple Port Scanner | Beginner | `PROJECTS/beginner/simple-port-scanner` |
| OAuth Token Analyzer | Intermediate | `PROJECTS/intermediate/oauth-token-analyzer` |
| Bug Bounty Platform | Advanced | `PROJECTS/advanced/bug-bounty-platform` |
| API Security Scanner | Intermediate | `PROJECTS/intermediate/api-security-scanner` |

### 3. Project Structure

Ensure your project structure is coherent and uses **intuitive, idiomatic naming** that follows common developer conventions.

**Required:**
- `README.md` - Detailed documentation (see below)
- `learn/` - Educational documentation folder (see section 4)
- Complete source code
- Any necessary configuration files

**If applicable:**
- `.env.example` - Template for environment variables (never commit actual `.env` files)
- `examples/` - Usage examples for advanced projects
- `requirements.txt` or `pyproject.toml` - Python dependencies
- `package.json` - Node.js dependencies
- `docker-compose.yml` - Container orchestration
- `Dockerfile` - Container builds

**Example Structure:**
```
PROJECTS/
├── beginner/
│   └── simple-port-scanner/
│       ├── README.md
│       ├── learn/
│       │   ├── 00-OVERVIEW.md
│       │   ├── 01-CONCEPTS.md
│       │   ├── 02-ARCHITECTURE.md
│       │   ├── 03-IMPLEMENTATION.md
│       │   └── 04-CHALLENGES.md
│       └── src/
├── intermediate/
│   └── oauth-token-analyzer/
│       ├── README.md
│       ├── learn/
│       ├── .env.example
│       ├── requirements.txt
│       ├── src/
│       │   ├── __init__.py
│       │   ├── main.py
│       │   └── utils/
│       └── tests/
└── advanced/
    └── bug-bounty-platform/
        ├── README.md
        ├── learn/
        ├── .env.example
        ├── docker-compose.yml
        ├── backend/
        ├── frontend/
        ├── tests/
        └── examples/
```

### 4. Educational Documentation (learn/ Folder)

All projects must include a `learn/` directory with educational documentation. This helps users understand not just how to use your project, but how it works and what security concepts it teaches.

**Required files:**

Copy the template from `.github/learn-folder-template/` to get started:

```bash
cp -r .github/learn-folder-template PROJECTS/[difficulty]/[project-name]/learn
cd PROJECTS/[difficulty]/[project-name]/learn
rm README.md  # Remove the template instructions
```

Then fill in these five files:

1. **00-OVERVIEW.md** - Project introduction
   - What the project does and why it matters
   - Real world scenarios where it applies
   - What users will learn (security concepts, technical skills)
   - Prerequisites and quick start instructions
   - Common issues and solutions

2. **01-CONCEPTS.md** - Security concepts and theory
   - Core security concepts explained in depth
   - Common attacks and defense strategies
   - Real world examples and breaches
   - Industry standards (OWASP, MITRE, CWE)
   - Further reading resources

3. **02-ARCHITECTURE.md** - System design
   - High level architecture diagrams
   - Component breakdown and responsibilities
   - Data flow examples
   - Design decisions and trade-offs
   - Performance and security considerations

4. **03-IMPLEMENTATION.md** - Code walkthrough
   - Step by step implementation guide
   - Real code from the project with file:line references
   - Security implementation details
   - Common pitfalls and debugging tips
   - Testing and deployment

5. **04-CHALLENGES.md** - Extension ideas
   - Easy to expert level challenges
   - Hints without full solutions
   - Real world integration ideas
   - Performance and security challenges

**Quality standards:**

- Reference actual code with `filename:line` format
- Include real world examples (breaches, CVEs, incidents)
- Use ASCII diagrams for architecture and data flow
- Show common mistakes and how to avoid them
- Write in a clear, human voice (avoid marketing speak)
- See `.github/learn-folder-template/README.md` for detailed writing guidelines

**Checklist:**

Use `.github/learn-folder-template/CHECKLIST.md` to verify your learn/ folder is complete before submitting.

### 5. Package Managers if using Python and or Node (Doesn't matter what you use for any other framework/libary/language though)

**Python:** Use [uv](https://github.com/astral-sh/uv) for dependency management. It's faster, better, and if you think pip or poetry is superior in 2026, you're simply not ready to contribute here. (I'm only slightly joking..... but use uv pls...)
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv and install deps
uv sync
```

**Node.js:** Use [pnpm](https://pnpm.io/) or [Bun](https://bun.sh/). npm is for people who enjoy watching progress bars.
```bash
# pnpm
pnpm install

# bun
bun install
```


### 6. README Requirements

Your project README should include:

- **Project Title & Description** - What does it do and why is it useful?
- **Features** - Key functionality and capabilities
- **Educational Value** - What will users learn from this project?
- **Prerequisites** - Required tools, versions, and dependencies
- **Installation** - Step-by-step setup instructions
- **Usage** - How to run and use the project with examples
- **Configuration** - Environment variables and settings explained
- **Architecture** (for complex projects) - How components interact
- **Security Considerations** - Any warnings or best practices
- **License** - Project licensing information

### 7. Code Quality Standards

**Linting & Type Checking:**

All Python code must pass the following tools (with reasonable ignores as needed):

```bash
# Linting
ruff check .
pylint your_module/

# Type checking
mypy your_module/
```

**Code Formatting:**

Format your code using the repository's custom YAPF configuration. Copy the [.style.yapf](https://github.com/CarterPerez-dev/Cybersecurity-Projects/blob/main/TEMPLATES/.style.yapf) file and place it in the root of your project directory.
```bash
yapf -i -r -vv your_project/
```

Don't have YAPF installed?
```bash
# With uv (you're using uv, right?)
uv pip install yapf

# Or if you insist on being difficult
pip install yapf
```

More info: [YAPF Documentation](https://github.com/google/yapf)

**Security Best Practices:**
- No hardcoded secrets, API keys, or credentials
- Input validation and sanitization
- Proper error handling
- Secure defaults
- Dependencies from trusted sources
- No oudtated dependencies (prefferably the current stable version)

### 8. Full-Stack Projects

Building a full-stack application? Use the included template as a starting point:

**[Fullstack Template](./TEMPLATES/fullstack-template)** - A production-ready template with FastAPI, React, Docker, and more. Check the [GitHub repository](https://github.com/CarterPerez-dev/fullstack-template) for the latest updates.

### 9. Submit a Pull Request

**Create a new branch:**
```bash
git checkout -b add-your-project-name
```

**Commit your changes with clear messages:**
```bash
git add .
git commit -m "Add your-project-name: brief description"
```

**Push to your fork:**
```bash
git push origin add-your-project-name
```

**Open a Pull Request:**

1. Navigate to the [original repository](https://github.com/CarterPerez-dev/Cybersecurity-Projects)
2. Click **Pull Requests** → **New Pull Request**
3. Click **compare across forks**
4. Select your fork and branch
5. Fill out the PR template completely:
   - Provide a clear description of your project
   - Check the appropriate boxes in the checklist
   - Link any related issues
   - Add any additional context reviewers should know

**PR Template Checklist:**
- [ ] Code follows existing style and conventions
- [ ] Project has been tested
- [ ] README documentation is complete
- [ ] learn/ folder is complete with all 5 required files
- [ ] Educational documentation follows quality standards
- [ ] No security vulnerabilities introduced
- [ ] Read and followed CONTRIBUTING.md guidelines

## General Guidelines

- **Keep it educational** - Focus on practical learning value
- **Keep it legal and ethical** - Only include projects that can be used responsibly
- **Test thoroughly** - Verify your code works before submitting
- **Write clear commit messages** - Describe what changed and why
- **Be responsive** - Address review feedback promptly

## Questions?

If you have questions about contributing or want to discuss a project idea before starting, [open an issue](https://github.com/CarterPerez-dev/Cybersecurity-Projects/issues) for discussion.