Status: Phase 1 (Reconnaissance) - Development
Version: 1.0.0-alpha
Target Users: Penetration Testers, Security Engineers, Security Researchers

WebPentest is a containerized web application penetration testing orchestration platform. v1 MVP focuses on Phase 1: Reconnaissance using Nmap for network discovery and port scanning.

• ✅ Self-contained Docker Compose deployment
• ✅ Multi-interface access (CLI, REST API)
• ✅ Secure authentication (API keys + simple login)
• ✅ Full audit logging (immutable)
• ✅ PostgreSQL persistence with backups
• ✅ Zero-vulnerability hardening

• 🔄 Phase 2: Scanning (Burp Suite, OWASP ZAP)
• 🔄 Phase 3: Exploitation (Metasploit, SQLMap)
• 🔄 Phase 4: Reporting (Advanced reports, integrations)

• Docker & Docker Compose (v3.8+)
• Linux/macOS (or WSL on Windows)
• 2GB+ RAM available

# 1. Clone repository
git clone <repo> webpentest
cd webpentest

# 2. Generate secrets
make setup

# 3. Build images
make build

# 4. Start services
make up

# 5. Verify health
curl http://localhost:8000/health

# Create admin user (via orchestrator container)
docker-compose exec orchestrator python scripts/create_user.py admin yourpassword

# Start a pentest
curl -X POST http://localhost:8000/pentest/start \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"target": "example.com"}'

# Check status
curl http://localhost:8000/pentest/1/status \
  -H "X-API-Key: your-api-key"

# Get results
curl http://localhost:8000/pentest/1/results \
  -H "X-API-Key: your-api-key"

1. Orchestrator Service — Central coordinator (Python + FastAPI)
2. API Server — REST endpoints for users
3. PostgreSQL — Data persistence
4. Tool Containers — Isolated Nmap (v1), future tools

User (CLI/API)
    ↓
REST API Server
    ↓
Orchestrator Service
    ↓
Tool Container (Nmap)
    ↓
PostgreSQL Database
    ↓
Results (JSON, HTML, Reports)

make up              # Start all services
make down            # Stop all services
make logs            # View orchestrator logs
make test            # Run test suite
make lint            # Run security checks
make clean           # Clean everything
make setup           # Generate secrets
make shell           # Open shell in orchestrator
make health          # Check service health

# Database
DB_PASSWORD=<strong-password>

# API
API_KEY_SECRET=<strong-secret>

# Logging
LOG_LEVEL=INFO

# Nmap
NMAP_TIMEOUT=3600

# Python
PYTHONUNBUFFERED=1

# Option 1: Using make
make setup

# Option 2: Manual
DB_PASSWORD=$(openssl rand -base64 32)
API_KEY_SECRET=$(openssl rand -base64 32)
echo "DB_PASSWORD=$DB_PASSWORD" > .env
echo "API_KEY_SECRET=$API_KEY_SECRET" >> .env

• ✅ No hardcoded secrets
• ✅ All SQL queries parameterized
• ✅ All command arguments escaped
• ✅ Containers run as non-root
• ✅ API keys hashed (bcrypt)
• ✅ Audit logs immutable
• ✅ Security scanning (Bandit, pip-audit)

# Run security checks
make security

# Specific checks
bandit -r orchestrator/app/
pip-audit

webpentest/
├── orchestrator/          # Main service
│   ├── app/
│   │   ├── models.py
│   │   ├── database.py    # (TODO)
│   │   ├── api.py         # (TODO)
│   │   └── ...
│   ├── tests/
│   ├── scripts/
│   ├── Dockerfile
│   └── requirements.txt
├── cli/                   # Command-line interface (TODO)
├── .claude/
│   ├── DESIGN.md          # Architecture & design
│   ├── TASKS.md           # Implementation tasks
│   └── CHECKLIST.md       # Pre-launch verification
├── docker-compose.yml
├── init.sql
├── .env.example
└── Makefile

# Run all tests
make test

# Run specific test
pytest orchestrator/tests/test_health.py -v

# Coverage report
pytest --cov=orchestrator/app orchestrator/tests/

# Format code
make format

# Lint
make lint

# Security scan
make security

# Check logs
make logs
make logs-db

# Verify health
make health

# Rebuild images
make build

# Reset database
docker-compose down -v
make up

# Connect to database
make shell-db

# Backup database
make backup-db

# Restore database
make restore-db

Change port in docker-compose.yml:

orchestrator:
  ports:
    - "9000:8000"  # Changed from 8000:8000

• DESIGN.md — Complete architecture & design
• TASKS.md — Implementation breakdown
• CHECKLIST.md — Pre-launch verification
• DEPLOYMENT.md — Detailed deployment guide (TODO)
• API.md — API endpoint documentation (TODO)
• CLI.md — CLI command reference (TODO)

• ✅ Phase 1: Reconnaissance (Nmap)
• ✅ CLI + API interfaces
• ✅ PostgreSQL persistence
• ✅ Audit logging
• ✅ Security hardening

• 🔄 Phase 2: Scanning (Burp, ZAP)
• 🔄 Phase 3: Exploitation (Metasploit, SQLMap)
• 🔄 Web dashboard (React)
• 🔄 DefectDojo integration

• 🔄 Phase 4: Reporting (Advanced)
• 🔄 Cloud deployment (AWS, GCP, Azure)
• 🔄 Horizontal scaling
• 🔄 Multi-tenant support

See .claude/TASKS.md for implementation tasks and contribution guidelines.

⚠️ v1 is designed for internal use only.

• Keep .env file secure (never commit to git)
• Use strong passwords (32+ chars)
• Run on trusted networks
• Regularly update Docker images
• Monitor audit logs

[To be determined]

For issues, questions, or contributions:

• Check TROUBLESHOOTING.md (TODO)
• Review DESIGN.md
• Inspect logs: make logs

Version: 1.0.0-alpha
Last Updated: 2026-06-18
Status: Phase 1 Foundation (In Development)