9.5 KiB

Raw Permalink Blame History

00-OVERVIEW.md

API Security Scanner

What This Is

A full-stack web application that tests APIs for common security vulnerabilities. Point it at any API endpoint and it'll check for rate limiting weaknesses, authentication bypasses, SQL injection holes, and authorization flaws. Built with FastAPI and React, it's designed to teach you how attackers probe APIs and how to defend against them.

Why This Matters

APIs are everywhere. Your mobile app talks to an API. Your web dashboard pulls from an API. That third party integration you added last week? API. And they're constantly under attack. In 2023, API attacks increased 400% year over year according to Salt Security's research. The Optus breach in 2022 exposed 10 million customer records through an unauthenticated API endpoint. T-Mobile's API breach the same year leaked data on 37 million customers.

Most of these breaches come down to a handful of problems that show up repeatedly. Missing rate limits let attackers hammer endpoints. Broken authentication accepts invalid tokens. SQL injection still works because developers concatenate user input into queries. IDOR vulnerabilities let users access each other's data by just changing an ID in the URL.

This project teaches you to find these issues before attackers do.

Real world scenarios where this applies:

Security teams scanning their own APIs before releases
Bug bounty hunters looking for vulnerabilities in public APIs
DevOps engineers validating that rate limiting actually works
Penetration testers checking if JWT validation can be bypassed
Developers learning what attacks their code needs to defend against

What You'll Learn

This project teaches you how API security testing works under the hood. By building it yourself, you'll understand:

Security Concepts:

OWASP API Security Top 10 2023 - not just the list, but what each vulnerability looks like in real code and how to detect it automatically
Rate limiting bypass techniques - how attackers rotate IPs, spoof headers, and manipulate endpoints to evade limits
JWT vulnerabilities - why the "none" algorithm attack works, what happens when signatures aren't verified, and how to test for weak secrets
SQL injection detection - error-based, boolean blind, and time-based blind techniques with statistical analysis to reduce false positives
IDOR/BOLA testing - finding authorization gaps that let users access objects they shouldn't

Technical Skills:

Building security scanners with request throttling, retry logic, and baseline timing analysis (see backend/scanners/base_scanner.py:40-90)
Implementing layered architecture with repositories, services, and route handlers that keep business logic separate from data access
JWT authentication flows from password hashing through token creation to validation on protected endpoints
Rate limiting implementation and detection using both response analysis and header inspection
Handling concurrent HTTP requests with proper connection pooling, timeouts, and error recovery

Tools and Techniques:

FastAPI with async/await for handling multiple scans concurrently without blocking
SQLAlchemy with Alembic for database migrations and relationship management
Docker multi-stage builds that separate dev (hot reload) from production (optimized, multi-worker)
React with TanStack Query for managing server state, automatic refetching, and optimistic updates
Nginx reverse proxy configuration for routing /api to backend and serving static frontend files

Prerequisites

Before starting, you should understand:

Required knowledge:

Python basics - functions, classes, async/await. You'll be reading code like async def make_request(self, method: str, endpoint: str, **kwargs: Any) and need to understand what's happening
HTTP fundamentals - what GET/POST mean, how headers work, what status codes indicate. The scanners analyze responses to detect vulnerabilities
SQL basics - SELECT, WHERE clauses, what a JOIN does. You'll see how SQL injection payloads try to manipulate queries
REST API concepts - endpoints, request/response, authentication. The whole project revolves around testing APIs

Tools you'll need:

Docker and Docker Compose - the entire stack runs in containers
Python 3.11+ - backend code uses modern type hints and pattern matching
Node.js 20+ - frontend build requires recent npm
PostgreSQL knowledge helpful - data is stored in Postgres with relationships between users, scans, and test results

Helpful but not required:

React and TypeScript - frontend is fully implemented but understanding it helps
Previous security testing experience - we'll teach the concepts but prior exposure to tools like Burp Suite or OWASP ZAP provides context
FastAPI familiarity - we use dependency injection and Pydantic validation heavily

Quick Start

Get the project running locally:

# Clone and navigate (assuming you're already in PROJECTS/intermediate)
cd api-security-scanner

# Copy environment template
cp .env.example .env

# CRITICAL: Edit .env and change SECRET_KEY to something random
# In production this must be a cryptographically secure random string

# Start development environment (includes hot reload)
docker compose -f dev.compose.yml up --build

# Wait for all services to be healthy, then visit:
# - Frontend: http://localhost (or http://localhost:80)
# - Backend API docs: http://localhost:8000/docs
# - Direct API: http://localhost:8000

Expected output: You should see the login page. Create an account, then you can start scanning. Try scanning https://httpbin.org/get with all four tests enabled. You'll see safe results because httpbin is designed for testing.

Project Structure

api-security-scanner/
├── backend/
│   ├── config.py              # All environment variables and constants
│   ├── core/                  # Infrastructure (database, security, dependencies)
│   ├── models/                # SQLAlchemy models (User, Scan, TestResult)
│   ├── repositories/          # Data access layer, queries isolated here
│   ├── routes/                # FastAPI endpoints (auth, scans)
│   ├── scanners/              # Security testing logic (SQLi, auth, etc)
│   ├── schemas/               # Pydantic validation schemas
│   └── services/              # Business logic layer
├── frontend/
│   └── src/
│       ├── components/        # React UI components
│       ├── hooks/             # TanStack Query hooks for API calls
│       ├── services/          # API client functions
│       └── store/             # Zustand state management
├── conf/
│   ├── docker/                # Dockerfiles for dev and prod
│   └── nginx/                 # Nginx reverse proxy configs
└── compose.yml                # Production Docker Compose
└── dev.compose.yml            # Development with volume mounts

Next Steps

Understand the concepts - Read 01-CONCEPTS.md to learn the security fundamentals behind rate limiting, authentication, SQL injection, and IDOR
Study the architecture - Read 02-ARCHITECTURE.md to see how the scanner system is designed, why we use the repository pattern, and how data flows through the layers
Walk through the code - Read 03-IMPLEMENTATION.md for detailed explanation of how each scanner works, with line-by-line breakdowns of the actual code
Extend the project - Read 04-CHALLENGES.md for ideas to build on, from adding XSS detection to implementing custom scanner plugins

Common Issues

Docker containers fail to start

Error: port is already allocated

Solution: Another service is using port 80, 5432, or 8000. Check docker ps and stop conflicting containers, or edit .env to change HOST_NGINX_PORT, HOST_DB_PORT, or HOST_BACKEND_PORT

Frontend can't reach backend

Network Error / Failed to fetch

Solution: Check VITE_API_URL in .env. For Docker setup, it should be http://localhost/api. If running backend directly (not in Docker), use http://localhost:8000

Database migrations fail

sqlalchemy.exc.OperationalError: could not connect to server

Solution: Database container isn't ready yet. Wait 10 seconds and try again. The healthcheck in dev.compose.yml:13-17 ensures Postgres is accepting connections before backend starts

Scans timeout on every test

All tests return ERROR status

Solution: The target URL might be blocking requests. Try https://httpbin.org/get first to verify the scanner works. Check SCANNER_CONNECTION_TIMEOUT in config.py:51 - default is 180 seconds

If you found this interesting, check out:

network-traffic-analyzer network-traffic-analyzere - Goes deeper into packet analysis and protocol dissection, complements this by showing what's happening at the network layer
docker-security-audit docker-security-audit - Focuses on container security, teaches you to scan Docker images and configurations for vulnerabilities
bug-bounty-platform bug-bounty-platform - Full platform for managing security findings, shows how professional security teams track and remediate issues

9.5 KiB Raw Permalink Blame History