From 79e07af746dd4e72975d22b1bf16eacc3259d232 Mon Sep 17 00:00:00 2001 From: Guy Korland Date: Sat, 2 May 2026 19:20:50 +0300 Subject: [PATCH 1/2] docs(operations): add Security guide Create a comprehensive security guide at operations/security.md covering: - Authentication (requirepass, Docker, Docker Compose) - Access Control Lists (ACLs) with graph-level permissions - TLS/SSL encryption for self-hosted and Cloud - Network isolation (bind address, Docker networks, K8s policies) - Least-privilege patterns (separate users, disable default, restrict commands) - Production security checklist Also adds the Security guide to the Operations index page. Addresses audit item P2.1. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- operations/index.md | 4 + operations/security.md | 276 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 280 insertions(+) create mode 100644 operations/security.md diff --git a/operations/index.md b/operations/index.md index 062a9d0c..906648c1 100644 --- a/operations/index.md +++ b/operations/index.md @@ -59,4 +59,8 @@ Comprehensive guides for migrating your data to FalkorDB from RedisGraph, Neo4j, ## 12. [Building Docker](/operations/building-docker) +## 13. [Security Guide](/operations/security) + +Comprehensive security guide covering authentication, ACL access control, TLS/SSL encryption, network isolation, and least-privilege patterns for production deployments. + Build custom FalkorDB Docker containers from source with platform-specific examples. diff --git a/operations/security.md b/operations/security.md new file mode 100644 index 00000000..af79ba40 --- /dev/null +++ b/operations/security.md @@ -0,0 +1,276 @@ +--- +title: "Security" +parent: "Operations" +nav_order: 13 +description: "Security guide for FalkorDB covering authentication, ACL access control, TLS encryption, network isolation, and least-privilege patterns for production deployments." +--- + +# Security Guide + +This guide consolidates FalkorDB's security features into a single reference. It covers authentication, access control lists (ACLs), TLS encryption, network isolation, and least-privilege design patterns for production environments. + +--- + +## 1. Authentication + +FalkorDB uses the Redis authentication mechanism. Enable a global password with the `requirepass` directive to prevent unauthenticated access. + +### Docker + +```bash +docker run -p 6379:6379 -p 3000:3000 -it \ + -e REDIS_ARGS="--requirepass " \ + --rm falkordb/falkordb:latest +``` + +### Docker Compose + +```yaml +services: + falkordb: + image: falkordb/falkordb:latest + ports: + - "6379:6379" + - "3000:3000" + environment: + - REDIS_ARGS=--requirepass +``` + +### Connecting with Authentication + +When authentication is enabled, clients must provide the password before executing any commands: + +```python +from falkordb import FalkorDB + +db = FalkorDB(host='localhost', port=6379, password='') +``` + +> **Tip:** For production, use a strong, randomly generated password and store it in a secrets manager rather than in plain text configuration files. + +--- + +## 2. Access Control Lists (ACLs) + +ACLs provide fine-grained, per-user access control. Each user can be granted or restricted to specific commands and graph patterns. + +### Creating Users + +``` +ACL SETUSER analyst on >analyst-password ~analytics_* +GRAPH.RO_QUERY +GRAPH.EXPLAIN -GRAPH.DELETE +``` + +This creates a user `analyst` who can only run read-only queries and explain plans on graphs matching `analytics_*`. + +### Graph Permissions + +FalkorDB extends ACL with graph-level read/write permissions: + +| Permission | Description | +|:---|:---| +| `%R~` | Read-only access to matching graphs | +| `%W~` | Write-only access to matching graphs | +| `%RW~` | Full access (equivalent to `~`) | + +**Example — read-only user for a specific graph:** + +``` +ACL SETUSER readonly_user on >secure-password %R~production_graph +GRAPH.RO_QUERY -GRAPH.QUERY -GRAPH.DELETE +``` + +### Persisting ACL Users + +By default, `ACL SETUSER` only updates the in-memory user table. Users are lost on restart unless you persist them. + +**Recommended approach — ACL file:** + +1. Mount an ACL file into the container +2. Set the `aclfile` directive +3. Run `ACL SAVE` after any changes + +See [ACL Persistence on Docker](/operations/durability/acl-persistence) for a complete step-by-step guide. + +### Listing and Inspecting Users + +``` +ACL LIST # List all users and their rules +ACL GETUSER # Inspect a specific user's permissions +ACL DELUSER # Remove a user +``` + +For the full command reference, see [ACL Commands](/commands/acl). + +--- + +## 3. TLS / SSL Encryption + +TLS encrypts all communication between clients and the FalkorDB server, preventing eavesdropping and man-in-the-middle attacks. + +### Self-Hosted TLS Configuration + +FalkorDB supports TLS through Redis's native TLS support. You need: + +- A **certificate** file (server.crt) +- A **private key** file (server.key) +- A **CA certificate** file (ca.crt) for client verification + +**Docker example:** + +```bash +docker run -p 6379:6379 -it \ + -v /path/to/certs:/tls:ro \ + -e REDIS_ARGS="--tls-port 6379 --port 0 \ + --tls-cert-file /tls/server.crt \ + --tls-key-file /tls/server.key \ + --tls-ca-cert-file /tls/ca.crt" \ + --rm falkordb/falkordb-server:latest +``` + +> **Note:** Setting `--port 0` disables the non-TLS port, ensuring all connections are encrypted. + +**Connecting with TLS (Python):** + +```python +from falkordb import FalkorDB + +db = FalkorDB( + host='localhost', + port=6379, + ssl=True, + ssl_ca_certs='/path/to/ca.crt' +) +``` + +### FalkorDB Cloud + +FalkorDB Cloud provides TLS on all paid tiers (Startup, Pro, Enterprise) with certificates managed automatically. No additional configuration is required — connect using the `rediss://` (note double `s`) URL scheme provided in your Cloud dashboard. + +--- + +## 4. Network Isolation + +Restrict which hosts and networks can reach your FalkorDB instance. + +### Bind Address + +By default, Redis binds to all interfaces (`0.0.0.0`). In production, restrict binding to specific interfaces: + +```bash +docker run -p 127.0.0.1:6379:6379 -it \ + -e REDIS_ARGS="--bind 127.0.0.1" \ + --rm falkordb/falkordb-server:latest +``` + +### Docker Networks + +Use Docker networks to isolate FalkorDB so only your application containers can reach it: + +```yaml +services: + app: + image: your-app:latest + networks: + - backend + + falkordb: + image: falkordb/falkordb-server:latest + networks: + - backend + # No ports published to host — only accessible from the backend network + +networks: + backend: + driver: bridge +``` + +### Kubernetes Network Policies + +When deploying on Kubernetes, use NetworkPolicy resources to restrict which pods can communicate with FalkorDB: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: falkordb-access +spec: + podSelector: + matchLabels: + app: falkordb + ingress: + - from: + - podSelector: + matchLabels: + role: app-server + ports: + - port: 6379 +``` + +### Firewall Rules + +For self-hosted deployments, ensure: + +- Port **6379** (FalkorDB server) is not exposed to the public internet +- Port **3000** (FalkorDB Browser) is restricted to trusted networks or VPN +- Use a reverse proxy with authentication for any web-facing access + +--- + +## 5. Least-Privilege Patterns + +Follow these patterns to minimize the blast radius of a compromised credential: + +### Separate Read and Write Users + +``` +# Application user — read/write on its own graphs +ACL SETUSER app_user on >app-secret ~myapp_* +GRAPH.QUERY +GRAPH.RO_QUERY + +# Analytics user — read-only across all graphs +ACL SETUSER analytics on >analytics-secret %R~* +GRAPH.RO_QUERY +GRAPH.EXPLAIN +GRAPH.PROFILE + +# Admin user — full access (use sparingly) +ACL SETUSER admin on >admin-secret ~* +@all +``` + +### Disable the Default User + +In production, disable the default (passwordless) user and create named users instead: + +``` +ACL SETUSER default off +``` + +> **Warning:** Make sure you have at least one admin user configured before disabling the default user, or you will lock yourself out. + +### Restrict Dangerous Commands + +Prevent non-admin users from running commands that could affect the whole server: + +``` +ACL SETUSER app_user ... -GRAPH.DELETE -FLUSHALL -FLUSHDB -CONFIG -SHUTDOWN -DEBUG +``` + +--- + +## 6. Security Checklist + +Use this checklist when preparing a FalkorDB deployment for production: + +- [ ] **Authentication enabled** — `requirepass` or ACL users configured +- [ ] **Default user disabled** — `ACL SETUSER default off` +- [ ] **TLS enabled** — non-TLS port disabled (`--port 0`) +- [ ] **Network isolated** — FalkorDB not exposed to public internet +- [ ] **ACL users persisted** — ACL file mounted and `ACL SAVE` run +- [ ] **Least-privilege applied** — each user has minimum required permissions +- [ ] **Browser access restricted** — port 3000 not publicly accessible, or using `falkordb-server` image +- [ ] **Secrets managed** — passwords stored in a secrets manager, not in code + +--- + +## Related Pages + +- [ACL Commands](/commands/acl) — Full ACL command reference +- [ACL Persistence on Docker](/operations/durability/acl-persistence) — Persist ACL users across restarts +- [Docker Deployment](/operations/docker) — Docker configuration including authentication +- [Configuration](/getting-started/configuration) — FalkorDB configuration parameters +- [FalkorDB Cloud](/cloud) — Managed deployment with built-in TLS and security From aff1ffbef24e46bff87c9ef1c945ecb349ecd94c Mon Sep 17 00:00:00 2001 From: Guy Korland Date: Sat, 2 May 2026 20:23:30 +0300 Subject: [PATCH 2/2] docs(security): add technical terms to spellcheck wordlist Add crt, NetworkPolicy, VPN, passwordless to .wordlist.txt to fix check-spelling CI failure on operations/security.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .wordlist.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index bbd34ca4..0250474b 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -833,3 +833,7 @@ erroring namespaces tracebacks eval +crt +NetworkPolicy +VPN +passwordless