hzhang
58f23ddcb8
Critical: - backup: prevent Zip Slip path traversal and zip bombs in restore/convert via safe_extract(); serialize get_backup() with backup_lock and always restore CWD so concurrent requests can't corrupt the os.chdir state - app: only enable the Werkzeug debugger/reloader when ENVIRONMENT=dev; always init rate limits (also under WSGI), not just under __main__ - apikey: fix create_key never committing (session.commit -> commit()), validate roles against an allowlist, and fix revoke_key/update_last_used operating on detached instances so revocation actually persists - env_provider: redact DB_PASSWORD and SESSION_SECRET_KEY in summerize() High: - markdown: filter private/protected docs for non-admins in the listing, get_home, get_index and search endpoints (was an anonymous data leak); escape LIKE metacharacters and cap search results - webhooks: validate target URL to block SSRF (loopback/private/link-local/ metadata IPs), disable redirects, safely parse additional_header - auth: validate JWT issuer and require exp/iat; add timeout to JWKS fetch; harden Authorization header parsing against malformed values - log: require admin for GET /api/log and auth for POST; bound entry size Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
HangmanLab Backend
This project provides the backend infrastructure for the HangmanLab application. It is built using Flask, SQLAlchemy, and other supporting libraries.
Table of Contents
- Features
- Requirements
- Installation
- Configuration
- Docker Deployment
- Usage
- API Endpoints
- Database Models
- Logging
- License
Features
- Authentication: JWT-based authentication integrated with Keycloak.
- Rate Limiting: Protects endpoints using Flask-Limiter.
- CRUD Operations: Manage paths, markdown files, resources, and logs.
- Database Support: Uses MySQL with SQLAlchemy ORM.
- ETag Support: Optimized response caching with ETags.
- Modular Design: Easy-to-extend and maintain.
Requirements
- Python 3.9 or higher
- MySQL 8.0 or higher
- Keycloak for authentication
- Node.js (optional, for frontend integration)
Installation
1. Clone the repository
git clone https://git.hangman-lab.top/hzhang/HangmanLab.Backend.git
cd hangmanlab-backend
2. Install dependencies
pip install -r requirements.txt
3. Set up the database
Ensure you have a MySQL instance running. Update the .env file with the database credentials.
cp .env.example .env
Edit the .env file to configure your environment variables.
4. Initialize the database
Configuration
The application uses environment variables to manage configuration. These variables are set in the .env file. Key variables include:
- Database Configuration:
DB_HOSTDB_PORTDB_NAMEDB_USERDB_PASSWORD
- Keycloak Configuration:
KC_HOSTKC_REALMKC_CLIENT_ID
- Other Settings:
SESSION_SECRET_KEYFRONTEND_HOST
Usage
Running the Application
Run the following command to start the Flask server:
python app.py
The server will start on http://0.0.0.0:5000.
Accessing the API
All endpoints are prefixed with /api (e.g., /api/path, /api/log).
Docker Deployment
Image
Pull the latest Docker image from the registry
docker pull git.hangman-lab.top/hzhang/hangmanlab-backend:latest
Running the Docker Container
docker run -d -p 80:80 --name hangmanlab-backend hangmanlab-backend:latest
API Endpoints
Path Management
- GET
/api/path/: Retrieve root paths. - GET
/api/path/<int:path_id>: Retrieve a specific path. - POST
/api/path/: Create a new path. - PUT/PATCH
/api/path/<int:path_id>: Update an existing path. - DELETE
/api/path/<int:path_id>: Delete a path.
Markdown Management
- GET
/api/markdown/: Retrieve all markdown files. - GET
/api/markdown/by_path/<int:path_id>: Retrieve markdowns by path. - POST
/api/markdown/: Create a new markdown file. - PUT/PATCH
/api/markdown/<int:markdown_id>: Update an existing markdown file. - DELETE
/api/markdown/<int:markdown_id>: Delete a markdown file.
Resource Management
- GET
/api/resource/<identifier>: Retrieve a resource. - POST
/api/resource/: Create a new resource. - DELETE
/api/resource/<identifier>: Delete a resource.
Logging
- GET
/api/log/: Retrieve logs with filtering options. - POST
/api/log/: Create a new log entry.
Configuration Management
- GET
/api/config/limits: Retrieve current rate limits. - PUT
/api/config/limits: Update rate limits.
Database Models
Key Models
- Path: Represents a file system path.
- Markdown: Represents markdown files associated with paths.
- Resource: Binary resources (e.g., images, documents).
- Log: Application logs for auditing and debugging.
Logging
The project uses a custom DatabaseLogHandler to log messages directly to the database. Logs include the following details:
- Level (e.g., INFO, ERROR)
- Message
- Timestamp
- Application name