Contributing

Want to contribute a project? Here's how to get started.

For the full, detailed contributing guide, see CONTRIBUTING.md in the repository.

Quick Overview

Fork the repository
Create your project in PROJECTS/{difficulty}/{project-name}/
Include a learn/ folder with educational documentation
Submit a pull request

Project Structure

Projects live in difficulty-based directories:

PROJECTS/
├── beginner/           # Basic tools, single-file scripts
├── intermediate/       # Multi-component systems, API integrations
└── advanced/           # Full-stack apps, distributed systems

Naming convention: lowercase, hyphenated (e.g., api-security-scanner, dns-lookup)

Required: learn/ Folder

Every project must include a learn/ directory with five educational files:

File	Content
`00-OVERVIEW.md`	What it does, prerequisites, quick start
`01-CONCEPTS.md`	Security theory, real breaches, CVE references
`02-ARCHITECTURE.md`	System design with ASCII diagrams
`03-IMPLEMENTATION.md`	Code walkthrough with file:line references
`04-CHALLENGES.md`	Extension ideas from easy to expert

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

Package Managers

Python: Use uv (not pip)
Node.js: Use pnpm or Bun (not npm)

Code Quality

All Python code must pass:

ruff check . (linting)
mypy . (type checking)
pylint src/ (additional linting)

Format with the repo's YAPF configuration (see TEMPLATES/.style.yapf).

Documentation Standards

Reference actual code with filename:line format
Include real-world examples (breaches, CVEs, incidents)
Use ASCII diagrams for architecture
Write in a clear, human voice (no marketing speak)
Ground concepts in real-world security scenarios

Full-Stack Template

Building a full-stack app? Use the included fullstack-template with FastAPI, React, Docker, and more.

Questions?

Open an issue to discuss project ideas before starting.

Home

Beginner Projects

Intermediate Projects

Advanced Projects

Guides

Resources

Progress: 14/60

View on GitHub