From cb6eebee5979b5fea28e482589d14ed6d46d5b81 Mon Sep 17 00:00:00 2001 From: Username Date: Wed, 24 Dec 2025 17:10:42 +0100 Subject: [PATCH] docs: update for v1.5.0 features - Add PKI audit logging, request duration metrics to features list - Update test count from 216 to 283 - Add audit.py and metrics.py to project structure - Document audit logging in api.md - Update TASKLIST.md with completed tasks - Update TODO.md (remove resolved debt items) - Update ROADMAP.md decision log --- README.md | 8 +++++++- ROADMAP.md | 10 ++++++++-- TASKLIST.md | 7 +++++-- TODO.md | 8 +++++--- documentation/api.md | 33 +++++++++++++++++++++++++++++++++ 5 files changed, 58 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 003dd1f..a079687 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ A lightweight, secure pastebin REST API built with Flask. - **Security headers** - HSTS, CSP, X-Frame-Options, X-Content-Type-Options - **CLI client** - Standalone `fpaste` tool with encryption support - **Request tracing** - X-Request-ID for log correlation +- **Audit logging** - PKI certificate lifecycle events (issue, revoke, auth failure) +- **Observability** - Request duration metrics via Prometheus histogram - **Minimal dependencies** - Flask + SQLite, optional cryptography for CLI ## Quick Start @@ -356,10 +358,12 @@ flaskpaste/ │ ├── __init__.py # Flask app factory │ ├── config.py # Configuration classes │ ├── database.py # SQLite management +│ ├── audit.py # Audit logging for PKI events +│ ├── metrics.py # Prometheus metrics and histograms │ └── api/ │ ├── __init__.py # Blueprint setup │ └── routes.py # API endpoints -├── tests/ # Test suite +├── tests/ # Test suite (283 tests) ├── data/ # SQLite database ├── run.py # Development server ├── wsgi.py # Production WSGI entry @@ -384,6 +388,8 @@ flaskpaste/ - **Rate limiting** - Per-IP throttling with auth multiplier - **Request tracing** - X-Request-ID for log correlation - **PKI support** - Built-in CA for client certificate issuance +- **Audit logging** - PKI certificate events for compliance and forensics +- **Observability** - Prometheus metrics for monitoring and alerting ## License diff --git a/ROADMAP.md b/ROADMAP.md index e92159c..f69a859 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -28,7 +28,10 @@ FlaskPaste v1.5.0 is deployed with comprehensive security hardening and abuse pr - CLI with list, search, update, export commands - Public certificate registration (PoW-protected) - CLI register command for certificate enrollment -- Comprehensive test suite (216 tests) +- Comprehensive test suite (283 tests) +- PKI audit logging (certificate lifecycle events) +- Request duration metrics (Prometheus histogram) +- Memory leak detection in CI pipeline ## Phase 1: Hardening (Complete) @@ -44,7 +47,7 @@ Focus: Production readiness and operational excellence. │ 4 │ Proxy trust validation │ Done │ 5 │ Proof-of-work spam prevention │ Done │ 6 │ Entropy enforcement │ Done -│ 7 │ Test coverage > 90% │ Done (205 tests) +│ 7 │ Test coverage > 90% │ Done (283 tests) │ 8 │ Documentation complete │ Done └───┴─────────────────────────────────┴────────────────────────────────────┘ ``` @@ -178,6 +181,9 @@ These features will not be implemented: | 2024-12 | CLI encrypt-by-default | Security-first design | 2024-12 | CLI retry on PoW failure | Graceful handling of stale tokens | 2024-12 | Public cert registration | Self-service onboarding with PoW protection +| 2024-12 | PKI audit logging | Full certificate lifecycle traceability +| 2024-12 | Request duration metrics | Prometheus histogram for observability +| 2024-12 | Memory leak CI job | tracemalloc-based leak detection in CI ## Review Schedule diff --git a/TASKLIST.md b/TASKLIST.md index e931bac..d02cbf1 100644 --- a/TASKLIST.md +++ b/TASKLIST.md @@ -23,8 +23,6 @@ Prioritized, actionable tasks. Each task is small and completable in one session | Status | Task |--------|-------------------------------------------------------------- | ☐ | Fix mypy type errors (currently ignored) -| ☐ | Add test for concurrent identical submissions -| ☐ | Add integration tests for container deployment ## Priority 4: Documentation @@ -37,6 +35,11 @@ Prioritized, actionable tasks. Each task is small and completable in one session | Date | Task |------------|-------------------------------------------------------------- +| 2024-12 | Integrate PKI audit logging (CERT_ISSUED, CERT_REVOKED, AUTH_FAILURE) +| 2024-12 | Integrate request duration metrics (Prometheus histogram) +| 2024-12 | Add memory leak detection tests (tracemalloc) +| 2024-12 | Add concurrent paste creation tests +| 2024-12 | Add container deployment integration tests | 2024-12 | Add tiered auto-expiry (anon/untrusted/trusted) | 2024-12 | Add admin list all pastes (`--all` flag) | 2024-12 | Add batch delete with confirmation (`--confirm N`) diff --git a/TODO.md b/TODO.md index c1777f0..f4df872 100644 --- a/TODO.md +++ b/TODO.md @@ -9,11 +9,12 @@ Unstructured intake buffer for ideas, issues, and observations. Items here are r - Rate limit headers in responses (X-RateLimit-*) - Paste compression for large text content - ETag support for conditional requests -- Paste listing for authenticated users (their own pastes only) - Neovim/Vim plugin for editor integration - Webhook notifications for paste events - Certificate renewal reminder in CLI - Admin endpoint for CA key rotation +- Shell completions (bash, zsh, fish) +- Clipboard integration (pbcopy/xclip) ## Observations @@ -23,6 +24,9 @@ Unstructured intake buffer for ideas, issues, and observations. Items here are r - CI pipeline: lint runs parallel with security, tests wait for lint - Ruff replaces flake8/isort/pyupgrade with single fast tool - Bandit configured for medium+ severity only (-ll flag) +- PKI audit events now logged: CERT_ISSUED, CERT_REVOKED, AUTH_FAILURE +- Request duration metrics recorded via Prometheus histogram +- Memory leak tests use tracemalloc to detect leaks (CI job) ## Questions @@ -36,8 +40,6 @@ Unstructured intake buffer for ideas, issues, and observations. Items here are r ## Debt - Mypy has pre-existing type errors (runs with --ignore-missing-imports) -- No integration tests for container deployment -- Missing test for concurrent paste creation - Could add more deployment examples (Kubernetes, systemd) ## External Dependencies diff --git a/documentation/api.md b/documentation/api.md index 78b59a3..f83c9d3 100644 --- a/documentation/api.md +++ b/documentation/api.md @@ -1198,3 +1198,36 @@ curl -H "X-SSL-Client-SHA1: $(openssl x509 -in client.crt -fingerprint -sha1 -no - The PKCS#12 bundle has no password (empty password) - CA is auto-generated on first registration if not present - Private key is generated server-side and included in response + +--- + +## Audit Logging + +FlaskPaste logs PKI certificate lifecycle events for compliance and forensics. + +**Logged Events:** + +| Event | Trigger | Details | +|-------|---------|---------| +| `cert_issued` | Certificate registration or issuance | Type, CN, fingerprint, expiry | +| `cert_revoked` | Certificate revocation | Serial, fingerprint | +| `auth_failure` | Revoked/expired certificate used | Fingerprint, reason | + +**Log Format (production):** +```json +{ + "time": "2024-12-24T10:30:00", + "level": "INFO", + "logger": "app.audit", + "event": "cert_issued", + "outcome": "success", + "client_id": "a1b2c3d4...", + "client_ip": "192.168.1.100", + "details": {"type": "registration", "common_name": "alice"} +} +``` + +**Notes:** +- Audit logs are written to stdout in JSON format (production mode) +- Events include client IP and certificate fingerprint for traceability +- AUTH_FAILURE events are logged when revoked/expired certificates are used