diff --git a/.env.demo b/.env.demo index 65f82fdf..3079e8ac 100644 --- a/.env.demo +++ b/.env.demo @@ -96,6 +96,24 @@ MAX_UPLOAD_SIZE=1073741824 # Allowed request headers (use * to allow all) # CORS_ALLOWED_HEADERS=* +# **Rate Limiting** (see SECURITY_AUDIT.md and docs/API.md) + +# **Audit Logging & SIEM Integration** (see docs/ConfigurationGuide.md#audit-logging) +# Enable HTTP request audit logging middleware +AUDIT_LOGGING_ENABLED=true +# Include client IP in audit log entries (disable for GDPR-sensitive deployments) +AUDIT_LOG_INCLUDE_CLIENT_IP=true + +# Forward audit events to an external SIEM system (Syslog, Splunk, Logstash, Grafana, etc.) +# AUDIT_SIEM_ENABLED=false +# AUDIT_SIEM_TRANSPORT=syslog # syslog | http +# AUDIT_SIEM_SYSLOG_HOST=localhost +# AUDIT_SIEM_SYSLOG_PORT=514 +# AUDIT_SIEM_SYSLOG_PROTOCOL=udp # udp | tcp +# AUDIT_SIEM_HTTP_URL= # e.g. https://splunk:8088/services/collector/event +# AUDIT_SIEM_HTTP_TOKEN= # Bearer / HEC token +# AUDIT_SIEM_HTTP_CUSTOM_HEADERS= # Comma-separated Key:Value pairs + # **Rate Limiting** (see SECURITY_AUDIT.md and docs/API.md) # Protects against DoS attacks and API abuse by limiting request rates per IP/user # Enabled by default - highly recommended for production diff --git a/app/utils/settings_service.py b/app/utils/settings_service.py index 7516f8f9..39ed812e 100644 --- a/app/utils/settings_service.py +++ b/app/utils/settings_service.py @@ -2065,6 +2065,78 @@ SETTING_METADATA = { "required": False, "restart_required": True, }, + "audit_siem_enabled": { + "category": "Security", + "description": "Enable forwarding of audit events to an external SIEM system (Syslog, Splunk, Logstash, etc.).", + "type": "boolean", + "sensitive": False, + "required": False, + "restart_required": False, + }, + "audit_siem_transport": { + "category": "Security", + "description": ( + "Transport used to forward audit events. 'syslog' sends RFC 5424 messages over UDP/TCP. " + "'http' sends JSON POST payloads to a webhook URL (Splunk HEC, Logstash, Grafana Loki, etc.)." + ), + "type": "string", + "sensitive": False, + "required": False, + "restart_required": False, + "options": ["syslog", "http"], + }, + "audit_siem_syslog_host": { + "category": "Security", + "description": "Hostname or IP of the syslog receiver.", + "type": "string", + "sensitive": False, + "required": False, + "restart_required": False, + }, + "audit_siem_syslog_port": { + "category": "Security", + "description": "Port of the syslog receiver. Default: 514.", + "type": "integer", + "sensitive": False, + "required": False, + "restart_required": False, + }, + "audit_siem_syslog_protocol": { + "category": "Security", + "description": "Protocol for syslog transport: 'udp' or 'tcp'. Default: udp.", + "type": "string", + "sensitive": False, + "required": False, + "restart_required": False, + "options": ["udp", "tcp"], + }, + "audit_siem_http_url": { + "category": "Security", + "description": ( + "HTTP endpoint URL for SIEM webhook delivery. Supports Splunk HEC, " + "Logstash HTTP input, Grafana Loki push API, or any JSON-accepting endpoint." + ), + "type": "string", + "sensitive": False, + "required": False, + "restart_required": False, + }, + "audit_siem_http_token": { + "category": "Security", + "description": "Bearer / HEC token included in the Authorization header of SIEM HTTP requests.", + "type": "string", + "sensitive": True, + "required": False, + "restart_required": False, + }, + "audit_siem_http_custom_headers": { + "category": "Security", + "description": "Comma-separated 'Key:Value' pairs of extra headers for SIEM HTTP requests.", + "type": "string", + "sensitive": False, + "required": False, + "restart_required": False, + }, # Rate Limiting "rate_limiting_enabled": { "category": "Security", diff --git a/docs/ConfigurationGuide.md b/docs/ConfigurationGuide.md index 009dc5a9..131324e4 100644 --- a/docs/ConfigurationGuide.md +++ b/docs/ConfigurationGuide.md @@ -398,6 +398,61 @@ default overage buffer applied across all plans. DocuElevate supports HTTP security headers to improve browser-side security. **These headers are disabled by default** since most deployments use a reverse proxy (Traefik, Nginx, etc.) that already adds them. Enable only if deploying directly without a reverse proxy. See [Deployment Guide - Security Headers](DeploymentGuide.md#security-headers) for detailed configuration examples. +### Audit Logging + +DocuElevate provides comprehensive audit logging that records significant actions (logins, document CRUD, settings changes) to an append-only database table. Every entry captures the timestamp, user, action, resource, client IP, and optional JSON details. + +| **Variable** | **Description** | **Default** | +|--------------------------------|---------------------------------------------------------------------------------------------------|-------------| +| `AUDIT_LOGGING_ENABLED` | Enable the HTTP request audit-logging middleware. | `true` | +| `AUDIT_LOG_INCLUDE_CLIENT_IP` | Include the client IP address in audit log entries. Disable for GDPR-sensitive deployments. | `true` | + +#### SIEM Integration + +Audit events can be forwarded in real time to external SIEM systems for centralised monitoring, alerting, and long-term retention. Two transports are supported: + +* **Syslog** – RFC 5424 structured-data messages over UDP or TCP. Works with rsyslog, syslog-ng, Graylog, Datadog, etc. +* **HTTP** – JSON POST payloads compatible with Splunk HEC, Logstash HTTP input, Grafana Loki push API, and any generic webhook. + +| **Variable** | **Description** | **Default** | +|-------------------------------------|---------------------------------------------------------------------------------------------------|---------------| +| `AUDIT_SIEM_ENABLED` | Enable forwarding of audit events to an external SIEM system. | `false` | +| `AUDIT_SIEM_TRANSPORT` | Transport: `syslog` or `http`. | `syslog` | +| `AUDIT_SIEM_SYSLOG_HOST` | Hostname or IP of the syslog receiver. | `localhost` | +| `AUDIT_SIEM_SYSLOG_PORT` | Port of the syslog receiver. | `514` | +| `AUDIT_SIEM_SYSLOG_PROTOCOL` | Protocol for syslog: `udp` or `tcp`. | `udp` | +| `AUDIT_SIEM_HTTP_URL` | HTTP endpoint URL for SIEM delivery (e.g. Splunk HEC, Logstash, Loki). | *(empty)* | +| `AUDIT_SIEM_HTTP_TOKEN` | Bearer / HEC token for the SIEM HTTP endpoint. | *(empty)* | +| `AUDIT_SIEM_HTTP_CUSTOM_HEADERS` | Comma-separated `Key:Value` extra headers for SIEM HTTP requests. | *(empty)* | + +**Example – Syslog to rsyslog:** + +```bash +AUDIT_SIEM_ENABLED=true +AUDIT_SIEM_TRANSPORT=syslog +AUDIT_SIEM_SYSLOG_HOST=syslog.internal.example.com +AUDIT_SIEM_SYSLOG_PORT=514 +AUDIT_SIEM_SYSLOG_PROTOCOL=udp +``` + +**Example – Splunk HEC:** + +```bash +AUDIT_SIEM_ENABLED=true +AUDIT_SIEM_TRANSPORT=http +AUDIT_SIEM_HTTP_URL=https://splunk.example.com:8088/services/collector/event +AUDIT_SIEM_HTTP_TOKEN=your-hec-token +``` + +**Example – Logstash HTTP input:** + +```bash +AUDIT_SIEM_ENABLED=true +AUDIT_SIEM_TRANSPORT=http +AUDIT_SIEM_HTTP_URL=https://logstash.example.com:8080 +AUDIT_SIEM_HTTP_TOKEN= +``` + ### Rate Limiting DocuElevate implements rate limiting to protect against DoS attacks and API abuse. **Rate limiting is enabled by default** and uses Redis for distributed rate limiting across multiple workers.