7.6 KiB

Raw Permalink Blame History

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

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

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

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
│       └── src/
├── intermediate/
│   └── oauth-token-analyzer/
│       ├── README.md
│       ├── .env.example
│       ├── requirements.txt
│       ├── src/
│       │   ├── __init__.py
│       │   ├── main.py
│       │   └── utils/
│       └── tests/
└── advanced/
    └── bug-bounty-platform/
        ├── README.md
        ├── .env.example
        ├── docker-compose.yml
        ├── backend/
        ├── frontend/
        ├── tests/
        └── examples/

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

Python: Use 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...)

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv and install deps
uv sync

Node.js: Use pnpm or Bun. npm is for people who enjoy watching progress bars.

# 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):

# 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 file and place it in the root of your project directory.

yapf -i -r -vv your_project/

Don't have YAPF installed?

# 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

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 - A production-ready template with FastAPI, React, Docker, and more. Check the GitHub repository for the latest updates.

9. Submit a Pull Request

Create a new branch:

git checkout -b add-your-project-name

Commit your changes with clear messages:

git add .
git commit -m "Add your-project-name: brief description"

Push to your fork:

git push origin add-your-project-name

Open a Pull Request:

Navigate to the original repository
Click Pull Requests → New Pull Request
Click compare across forks
Select your fork and branch
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
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 for discussion.

7.6 KiB Raw Permalink Blame History