Getting Started

Getting Started

Prerequisites

General Requirements

• Git 2.x+
• Docker & Docker Compose
• Python 3.13+ (for Python projects)
• Go 1.23+ (for Go projects)
• Node.js 20+ (for frontend projects)
• uv (Python package manager)
• pnpm (Node.js package manager)

Cloning the Repository

This repo uses git submodules for the fullstack template. Clone with:

git clone --recurse-submodules https://github.com/CarterPerez-dev/Cybersecurity-Projects.git

If you already cloned without submodules:

cd Cybersecurity-Projects
git submodule update --init --recursive

Project Organization

Projects are organized by difficulty level:

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

Each completed project contains a learn/ folder with educational documentation:

any-project/
├── learn/
│   ├── 00-OVERVIEW.md        # Quick start, prerequisites
│   ├── 01-CONCEPTS.md        # Security theory, real breaches, CVEs
│   ├── 02-ARCHITECTURE.md    # System design, ASCII diagrams
│   ├── 03-IMPLEMENTATION.md  # Code walkthrough
│   └── 04-CHALLENGES.md      # Extension ideas
├── src/                       # Source code
├── tests/                     # Test suite
└── README.md

Running Projects

Quick Start Pattern

Most projects follow this pattern:

cd PROJECTS/<difficulty>/<project-name>

# Full-stack projects (Docker-based)
make dev
# or
docker compose -f dev.compose.yml up --build

# CLI tools (Python)
uv sync
uv run python src/main.py

# CLI tools (Go)
go build -o bin/ ./cmd/...
./bin/<tool-name>

Project-Specific Instructions

Beginner Projects

Project	Setup	Access
Simple Port Scanner	cd src && g++ -o scanner scanner.cpp	CLI
Keylogger	uv sync && uv run python src/keylogger.py	CLI
Caesar Cipher	uv sync && uv run python src/caesar.py	CLI
DNS Lookup	uv sync && uv run python -m dnslookup	CLI
Vulnerability Scanner	go build ./cmd/vulnscan	CLI
Metadata Scrubber	uv sync && uv run python src/scrubber.py	CLI
Network Traffic Analyzer	uv sync && sudo uv run python src/analyzer.py	CLI
Base64 Tool	uv sync && uv run python src/base64_tool.py	CLI

Intermediate Projects

Project	Setup	Access
API Security Scanner	make dev	http://localhost:3000
SIEM Dashboard	make dev	http://localhost:3000
Docker Security Audit	go build ./cmd/audit	CLI

Advanced Projects

Project	Setup	Access
API Rate Limiter	uv sync && uv run python examples/demo.py	Library / CLI
Encrypted P2P Chat	make dev	http://localhost:3000
Bug Bounty Platform	make dev	http://localhost:3000

Development Environment

Recommended Tools

• IDE: VS Code with Python, TypeScript, Go, Docker extensions
• API Testing: Bruno, Postman, or httpie
• Database: DBeaver or pgAdmin for PostgreSQL
• Network: Wireshark for packet analysis

Python Setup (uv)

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

# Navigate to a Python project
cd PROJECTS/beginner/dns-lookup

# Create venv and install deps
uv sync

# Run
uv run python -m dnslookup example.com

Node.js Setup (pnpm)

# Install pnpm
npm install -g pnpm

# Navigate to a frontend project
cd PROJECTS/intermediate/api-security-scanner/frontend

# Install dependencies
pnpm install

# Development server
pnpm dev

Go Setup

# Navigate to a Go project
cd PROJECTS/beginner/simple-vulnerability-scanner

# Build
go build -o bin/vulnscan ./cmd/vulnscan

# Run
./bin/vulnscan --help

Environment Variables

Full-stack projects have a .env.example file. Copy and configure:

cp .env.example .env
# Edit .env with your values

Never commit .env files with secrets.

Code Quality

All projects use strict linting and type checking:

# Python
ruff check .          # Linting
mypy .                # Type checking
pylint src/           # Additional linting

# Go
go vet ./...          # Static analysis
golangci-lint run     # Linting

# Frontend
pnpm lint             # ESLint
pnpm typecheck        # TypeScript checking

Next Steps

1. Browse the Project Roadmap to find a project that interests you
2. Read the project's wiki page and learn/00-OVERVIEW.md
3. Clone and run locally
4. Work through the learn/ documentation
5. Try the challenges in learn/04-CHALLENGES.md
6. Want to contribute? See Contributing