From 0bd956a9db613222f85b65bf831d7fb71652111e Mon Sep 17 00:00:00 2001 From: Pulse Monitor Date: Wed, 13 Aug 2025 19:56:21 +0000 Subject: [PATCH] docs: update documentation for security changes and API improvements Documentation Updates: - Fix CORS documentation to reflect new secure defaults (no CORS by default) - Add API token management endpoints to API.md - Document CORS configuration in SECURITY.md - Update environment variable documentation with defaults - Add authentication variables (PULSE_PASSWORD, API_TOKEN, etc.) - Add troubleshooting for CORS and authentication issues - Remove outdated references to ALLOWED_ORIGINS=* - Clarify that CORS defaults to same-origin only All documentation now accurately reflects: - Security improvements from recent audit - New API token management features - Correct CORS behavior and configuration - Complete environment variable reference --- README.md | 2 +- docs/API.md | 10 ++++++++++ docs/CONFIGURATION.md | 24 ++++++++++++++---------- docs/FAQ.md | 12 ++++++++++++ docs/SECURITY.md | 29 ++++++++++++++++++++++++++++- 5 files changed, 65 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index b5948d369..c6592db43 100644 --- a/README.md +++ b/README.md @@ -120,7 +120,7 @@ services: # - AUTO_UPDATE_TIME=03:00 # Time to install updates HH:MM (default: 03:00) # CORS & logging - # - ALLOWED_ORIGINS=* # CORS allowed origins (default: *) + # - ALLOWED_ORIGINS=https://app.example.com # CORS origins (default: none, same-origin only) # - LOG_LEVEL=info # Log level: debug/info/warn/error (default: info) restart: unless-stopped diff --git a/docs/API.md b/docs/API.md index 9ad4f5715..855b85ff2 100644 --- a/docs/API.md +++ b/docs/API.md @@ -207,6 +207,16 @@ GET /api/config/system # Get system config POST /api/config/system # Update system config ``` +### API Token Management +Manage API tokens for programmatic access. + +```bash +GET /api/system/api-token # Get token status +GET /api/system/api-token?reveal=true # Get actual token (auth required) +POST /api/system/api-token/generate # Generate new token +DELETE /api/system/api-token/delete # Remove token +``` + ### Export/Import Configuration Backup and restore Pulse configuration. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 54b4c619e..0003e7357 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -45,16 +45,20 @@ sudo systemctl restart pulse-backend ``` **Available variables:** -- `FRONTEND_PORT` - Web UI port -- `POLLING_INTERVAL` - Node check interval (seconds) -- `CONNECTION_TIMEOUT` - Connection timeout (seconds) -- `UPDATE_CHANNEL` - stable or rc -- `AUTO_UPDATE_ENABLED` - true/false -- `AUTO_UPDATE_CHECK_INTERVAL` - Hours between checks -- `AUTO_UPDATE_TIME` - Update time (HH:MM) -- `ALLOWED_ORIGINS` - CORS origins -- `LOG_LEVEL` - debug/info/warn/error -- `DISCOVERY_SUBNET` - Network subnet for auto-discovery (default: auto, e.g., 192.168.0.0/24) +- `FRONTEND_PORT` - Web UI port (default: 7655) +- `POLLING_INTERVAL` - Node check interval in seconds (default: 3) +- `CONNECTION_TIMEOUT` - Connection timeout in seconds (default: 10) +- `UPDATE_CHANNEL` - stable or rc (default: stable) +- `AUTO_UPDATE_ENABLED` - true/false (default: true) +- `AUTO_UPDATE_CHECK_INTERVAL` - Hours between checks (default: 24) +- `AUTO_UPDATE_TIME` - Update time HH:MM (default: 03:00) +- `ALLOWED_ORIGINS` - CORS origins (default: none, same-origin only) +- `LOG_LEVEL` - debug/info/warn/error (default: info) +- `DISCOVERY_SUBNET` - Network subnet for auto-discovery (default: auto-detect) +- `PULSE_PASSWORD` - Password for web UI authentication (optional) +- `API_TOKEN` - Token for API authentication (optional) +- `ALLOW_UNPROTECTED_EXPORT` - Allow export without auth (default: false) +- `PULSE_DEV` - Enable development mode features (default: false) ### 3. Secure Environment Variables For sensitive data like API tokens and passwords: diff --git a/docs/FAQ.md b/docs/FAQ.md index a28cde0e1..720f4cdd5 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -58,6 +58,18 @@ Yes! When you add one cluster node, Pulse automatically discovers and monitors a - Verify API token not expired - Confirm user has required permissions +### CORS errors in browser? +- By default, Pulse only allows same-origin requests +- Set `ALLOWED_ORIGINS` environment variable for cross-origin access +- Example: `ALLOWED_ORIGINS=https://app.example.com` +- Never use `*` in production + +### Authentication issues? +- Password auth: Check `PULSE_PASSWORD` environment variable +- API token: Verify `API_TOKEN` is set correctly +- Session expired: Log in again via web UI +- Account locked: Wait 15 minutes after 5 failed attempts + ### High memory usage? Reduce `metricsRetentionDays` in settings and restart diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 93f19316e..0760a3192 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -192,9 +192,36 @@ curl -H "X-API-Token: your-token" http://localhost:7655/api/health - Protects auto-registration endpoint - Enable by setting API_TOKEN environment variable +## CORS (Cross-Origin Resource Sharing) + +By default, Pulse only allows same-origin requests (no CORS headers). This is the most secure configuration. + +### Configuring CORS for External Access + +If you need to access Pulse API from a different domain: + +```bash +# Docker +docker run -e ALLOWED_ORIGINS="https://app.example.com" rcourtman/pulse:latest + +# systemd +sudo systemctl edit pulse-backend +[Service] +Environment="ALLOWED_ORIGINS=https://app.example.com" + +# Multiple origins (comma-separated) +ALLOWED_ORIGINS="https://app.example.com,https://dashboard.example.com" + +# Development mode (allows localhost) +PULSE_DEV=true +``` + +**Security Note**: Never use `ALLOWED_ORIGINS=*` in production as it allows any website to access your API. + ## Troubleshooting **Export blocked?** Set API_TOKEN or ALLOW_UNPROTECTED_EXPORT=true **Rate limited?** Wait 1 minute and try again **Can't login?** Check PULSE_PASSWORD environment variable -**API access denied?** Verify API_TOKEN is correct \ No newline at end of file +**API access denied?** Verify API_TOKEN is correct +**CORS errors?** Configure ALLOWED_ORIGINS for your domain \ No newline at end of file