3059d533bc
- TASKLIST.md: add pentest tasks to completed section - TODO.md: add observation about pentest completion - ROADMAP.md: update test count (301), add decision log entry - PROJECT.md: update test count (301) - SECURITY.md: remove obsolete limitations, add v1.5.0 changes
157 lines
8.3 KiB
Markdown
157 lines
8.3 KiB
Markdown
# FlaskPaste
|
|
|
|
## Purpose
|
|
|
|
FlaskPaste is a lightweight, security-hardened pastebin REST API for self-hosted deployments. It provides a minimal, dependency-light alternative to public pastebin services, designed for environments where data privacy, authentication control, and operational simplicity are priorities.
|
|
|
|
## Problem Statement
|
|
|
|
Public pastebin services present risks:
|
|
- Data sovereignty concerns (content stored on third-party infrastructure)
|
|
- Limited authentication options
|
|
- No control over retention policies
|
|
- Abuse/spam from other users affecting service reliability
|
|
- Feature bloat and complex UIs when only an API is needed
|
|
|
|
## Solution
|
|
|
|
A self-hosted pastebin API that:
|
|
- Stores pastes locally in SQLite
|
|
- Supports client certificate authentication via reverse proxy
|
|
- Provides optional built-in PKI for certificate management
|
|
- Automatically expires content based on access patterns
|
|
- Prevents abuse through content-hash deduplication and proof-of-work
|
|
- Serves text and binary content with proper MIME detection
|
|
- Runs behind any reverse proxy (nginx, HAProxy, Caddy)
|
|
|
|
## Success Criteria
|
|
|
|
```
|
|
┌────────────────────────────────┬────────────────────────────────────────────┐
|
|
│ Criterion │ Metric
|
|
├────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ Security │ Zero injection vulnerabilities
|
|
│ │ All OWASP headers implemented
|
|
│ │ Input validation on all endpoints
|
|
│ │ Security scanning in CI (bandit)
|
|
├────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ Reliability │ SQLite ACID guarantees
|
|
│ │ Graceful degradation on errors
|
|
│ │ Health check endpoint for monitoring
|
|
├────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ Simplicity │ Single dependency (Flask)
|
|
│ │ SQLite for storage (no external DB)
|
|
│ │ Environment-based configuration
|
|
├────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ Operability │ Container-ready (Podman/Docker)
|
|
│ │ Gunicorn-compatible WSGI
|
|
│ │ Request tracing via X-Request-ID
|
|
│ │ Prometheus metrics endpoint
|
|
└────────────────────────────────┴────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Scope
|
|
|
|
### In Scope
|
|
|
|
- REST API for paste CRUD operations
|
|
- Text and binary content support
|
|
- Magic-byte MIME type detection
|
|
- Client certificate authentication (via proxy header)
|
|
- Built-in PKI (CA generation, certificate issuance, revocation)
|
|
- Configurable size limits (anon vs authenticated)
|
|
- Time-based expiry with access-touch semantics
|
|
- Content-hash deduplication for abuse prevention
|
|
- Proof-of-work spam prevention
|
|
- Entropy enforcement for encrypted content
|
|
- Client-side E2E encryption (CLI)
|
|
- Burn-after-read pastes
|
|
- Custom expiry per paste
|
|
- URL prefix for reverse proxy deployments
|
|
- Security headers (HSTS, CSP, X-Frame-Options, etc.)
|
|
- Request tracing and structured logging
|
|
- Container deployment support
|
|
- SQLite storage
|
|
- CI/CD with security scanning
|
|
|
|
### Out of Scope
|
|
|
|
- Web UI / HTML frontend
|
|
- User registration / account management
|
|
- Syntax highlighting
|
|
- Paste forking / versioning
|
|
- Public paste listing / discovery
|
|
- Multi-node clustering / distributed storage
|
|
- Alternative storage backends (S3, PostgreSQL)
|
|
|
|
## Constraints
|
|
|
|
- **Single process** - SQLite limits concurrency; scale via multiple containers
|
|
- **Reverse proxy required** - Client cert auth requires TLS termination
|
|
- **No web UI** - API-only; CLI tools (curl, httpie) are the interface
|
|
- **Ephemeral by design** - Pastes expire; not for permanent storage
|
|
|
|
## Assumptions
|
|
|
|
- Deployment behind a TLS-terminating reverse proxy
|
|
- Client certificates managed externally or via built-in PKI
|
|
- Operators have container runtime (Podman/Docker) or Python venv
|
|
- SQLite performance sufficient for expected load
|
|
|
|
## Technical Stack
|
|
|
|
```
|
|
┌─────────────────┬──────────────────────────────────────────────────────────┐
|
|
│ Component │ Technology
|
|
├─────────────────┼──────────────────────────────────────────────────────────┤
|
|
│ Framework │ Flask 3.x
|
|
│ Database │ SQLite 3 (built-in)
|
|
│ WSGI Server │ Gunicorn (production)
|
|
│ Container │ Podman / Docker
|
|
│ Testing │ pytest
|
|
│ Linting │ ruff, mypy
|
|
│ Security │ bandit, pip-audit
|
|
│ CI/CD │ Gitea Actions
|
|
│ Python │ 3.11+
|
|
└─────────────────┴──────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Current Status
|
|
|
|
**Version:** 1.5.0
|
|
|
|
```
|
|
┌─────────────────────────────────┬────────────────────────────────────────────┐
|
|
│ Feature │ Status
|
|
├─────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ Core API (CRUD) │ Complete
|
|
│ Binary content support │ Complete
|
|
│ MIME detection │ Complete
|
|
│ Client cert authentication │ Complete
|
|
│ Built-in PKI │ Complete
|
|
│ Size limits │ Complete
|
|
│ Paste expiry │ Complete
|
|
│ Content-hash deduplication │ Complete
|
|
│ Proof-of-work │ Complete
|
|
│ Anti-flood (dynamic PoW) │ Complete
|
|
│ IP-based rate limiting │ Complete (with X-RateLimit-* headers)
|
|
│ URL prefix support │ Complete
|
|
│ /client endpoint │ Complete
|
|
│ E2E encryption (CLI) │ Complete
|
|
│ Entropy enforcement │ Complete
|
|
│ Burn-after-read │ Complete
|
|
│ Custom expiry │ Complete
|
|
│ Security headers │ Complete
|
|
│ Request tracing │ Complete
|
|
│ Container deployment │ Complete
|
|
│ Security tooling │ Complete
|
|
│ CI/CD pipeline │ Complete
|
|
│ Scheduled cleanup │ Complete
|
|
│ CLI paste listing/search │ Complete
|
|
│ Public certificate registration │ Complete
|
|
│ CLI register command │ Complete
|
|
│ systemd deployment │ Complete (security-hardened)
|
|
│ Test suite │ 301 tests passing
|
|
└─────────────────────────────────┴────────────────────────────────────────────┘
|
|
```
|