This document describes SoliKV's security model and the hardening shipped in the SEC-001…SEC-016 series and the 2026-09 audit follow-up (phases 1–7).
Please report security issues privately to the maintainers rather than via public GitHub issues. Include reproduction steps and affected versions.
SoliKV is a Redis-protocol-compatible server. Two trust boundaries matter:
- Network → server: any party who can open a TCP connection to the
RESP port (6379), the REST port (5020) or, in cluster mode, the cluster
bus (RESP port + 10000 unless
--cluster-port), and any party on the path of the links the server opens itself: to its master (replication), toMIGRATEtargets, and to other cluster nodes. - Local user → daemon: any local UNIX user who shares the host (e.g. multi-tenant deployments, shared CI runners).
Out of scope: an attacker with root on the same host, or with write access to the data directory after server startup. A replica trusts its master completely (it applies the master's stream as the master's own writes, as Redis does), and cluster nodes trust each other: compromising one member compromises the cluster.
| Channel | Authentication | Encryption |
|---|---|---|
| RESP (client → server) | requirepass / ACL users (AUTH, HELLO … AUTH); optional client certificates |
TLS with --tls-cert/--tls-key |
| REST (client → server) | Bearer token (--rest-token, else requirepass) acting as --rest-token-user, or Basic credentials of any ACL user; optional client certificates |
TLS with the same certificate |
| Replication (replica → master) | --masterauth (+ --masteruser for an ACL user) |
TLS with --tls-replication yes |
MIGRATE (server → target) |
AUTH / AUTH2 arguments |
TLS with --tls-replication yes |
| Cluster bus (node ↔ node) | HMAC-SHA-256 envelope keyed by --cluster-bus-secret, receiver-bound, replay-protected |
TLS with --tls-cluster yes (mutual, CA-checked) |
--cluster-dump / --cluster-restore (tool → nodes) |
--cluster-password (+ --cluster-user) |
TLS when given the nodes' --tls-cert/--tls-key/--tls-ca-cert |
- Protected mode (SEC-001): starting with
--bindset to a non-loopback address while thedefaultuser needs no password is refused. The check runs after--aclfileis loaded, so a password given todefaultthere counts. Operators must set a password or pass--protected-mode no. - TLS (SEC-002):
--tls-cert PATH --tls-key PATH(PKCS#8, PKCS#1 or SEC1 keys) enables TLS on the RESP and REST ports; handshakes are bounded by--tls-handshake-timeout(default 10 s). The same certificate is this node's client certificate on the links it opens.- Client certificates (mTLS):
--tls-ca-cert PATH(also accepted as--tls-client-ca, andtls-ca-cert-filein a config file) checks client certificates on RESP and REST per--tls-auth-clients yes|optional|no—yesby default once a CA is set, as in Redis. A certificate proves membership of the CA, not an ACL identity: clients stillAUTH, unless--tls-auth-clients-user CNis set (Redis 8'stls-auth-clients-user): then a RESP client whose verified certificate's subject CN names an existing, enabled ACL user starts authenticated as that user. Off by default; refused at startup without client certificates to read. REST keeps its Bearer/Basic authentication. - Cluster dump/restore tool: given the nodes'
--tls-cert/--tls-key/--tls-ca-cert,--cluster-dump/--cluster-restoreconnect over TLS, check each node against the CA and present the certificate; a CA without a certificate refuses to run rather than dump in clear. - Replication and
MIGRATE:--tls-replication yesmakes a replica dial its master over TLS and check the master's certificate against the CA;MIGRATEuses the same setting, as in Redis. - Cluster bus:
--tls-cluster yesruns every bus connection over TLS both ways; the listening node requires a certificate signed by the CA from the dialling node, and the dialling node checks the listener's. The HMAC envelope stays underneath. - Peer names are not checked: peers are verified against the CA, not against the address dialled (Redis does the same — nodes are reached by IP and change roles in failovers). Anything holding a certificate from the CA counts as a member: use a private CA for the cluster.
- Misconfiguration refuses to start: TLS options without a certificate,
--tls-auth-clientswithout a CA, or outbound TLS without a CA.
- Client certificates (mTLS):
- REST credentials: the Bearer token defaults to the RESP password;
--rest-token-file/SOLIKV_REST_TOKEN/--rest-tokenset a separate one, so a leaked REST token is not also the RESP password. The token acts as the ACL user--rest-token-user(defaultdefault); other users authenticate withAuthorization: Basic. Every REST route is checked against the request's ACL user exactly as the command it runs would be over RESP (a denial is a403with Redis'NOPERMmessage and is recorded inACL LOG). A server with no token and a password-lessdefaultuser is open over REST as over RESP.--rest-port 0disables the REST API;--rest-max-connections(default 1024) answers503past the cap, counting TLS handshakes in flight. - DNS rebinding: on a loopback bind the REST API only answers requests
whose
Hostislocalhost,127.0.0.1or::1(plus--rest-allowed-hosts), so a web page that rebinds its own name to 127.0.0.1 cannot read or write keys. On other binds the check runs when--rest-allowed-hostsis set. - AUTH rate limiting (SEC-004): both the RESP server and the REST
middleware track failed AUTH attempts per peer IP and block the IP for
30 s after 10 failures, logging every failed attempt at
warn. A REST request with no credentials is refused but not counted — behind a reverse proxy, counting it let anonymous probes lock everyone out. Both failure maps are pruned of expired entries. - Pre-auth limits: before AUTH a connection may not nest arrays at all,
may buffer at most 128 KiB, and must authenticate within
--auth-timeoutseconds of connecting (default 10; the deadline covers the whole connection, so a byte-at-a-time trickle does not extend it). Inline commands and RESP header lines are capped at 64 KiB before their CRLF. After AUTH, nesting is capped at 32 levels and the query buffer at--client-query-buffer-limit(default 1 GiB, as in Redis).--timeoutcloses idle authenticated clients (default 0 = never);--maxclients(default 10 000) refuses connections past it with Redis' error.
- ACL: users with SHA-256-hashed passwords, command rules by name,
category and
command|subcommand, key patterns (~,%R~,%W~) and channel patterns (&), as in Redis 7, including selectors ((~key* +cmd …)): a command is allowed when the user's own permissions or any one selector allow all of it.--aclfileloads users at startup;ACL SAVEwrites the file0600.requirepassis thedefaultuser's password. Checks cost one flag test for unrestricted users. - Secrets stay out of the logs:
MONITORdoes not show administrative commands (ACL,CONFIG,DEBUG, …) orAUTH, andMONITORandSLOWLOGshow(redacted)for the passwords ofHELLO … AUTH,MIGRATE … AUTH|AUTH2,ACL SETUSERpassword rules andCONFIG SET requirepass|masterauth, as Redis does.
- REST denylist (SEC-005):
POST /cmdrejects destructive or DoS-prone commands (KEYS,SCAN/HSCAN/ZSCAN/SSCAN,RENAME,RENAMENX,RESET,LATENCY,MEMORY,WAIT,FAILOVER,CLIENT,INFO,DBSIZE,FLUSHDB,FLUSHALL,SHUTDOWN,EVAL,CONFIG, …) whatever the user's ACL allows;/infoand/dbsizehave their own read-only routes behind the same authentication. DEBUGis refused unless--enable-debug-command local|yes.CONFIG SETaccepts only the parameters it can change safely at runtime;dir,dbfilenameand the like are not settable, so Redis' "write a file anywhere" trick does not apply.
- A replica authenticates with
--masterauth/--masteruser; a replica of a master that requires a password but has no--masterauthsays so rather than failing later. Without--tls-replication, the password and the whole dataset cross the network in cleartext. min-replicas-to-write/min-replicas-max-lagmake a master refuse writes (NOREPLICAS) unless enough replicas acknowledged recently.CLIENT KILL TYPE replica|mastercloses replication links (they reconnect);CLIENT PAUSE … WRITE|ALLnever holds replication links.
- Every frame carries an HMAC-SHA-256 over length-prefixed fields
(timestamp, nonce, receiver, payload). The key is
--cluster-bus-secret-file/SOLIKV_CLUSTER_BUS_SECRET/--cluster-bus-secret(at least 32 bytes); cluster mode refuses to start without one. It is separate from--cluster-password, which only authenticates--cluster-dump/--cluster-restoreto nodes; using--cluster-passwordas the bus key still works, with a deprecation warning, so one credential handed to an operator tool is not the key to the topology. - Frames name their receiving node, so a capture cannot be replayed at other
nodes; only
PING/MEET— the handshake, sent before the peer's id is known — may be unaddressed, and they carry no slot ownership. One nonce memory spans all bus connections and keeps each nonce until its timestamp leaves the ±5 min window. - Frames are read with a hard 1 MiB line limit, at most 256 bus connections are served at once, idle connections are dropped after 30 s, and rejected frames are logged at most once a second. Slot numbers ≥ 16384 are refused everywhere.
- Without
--tls-cluster, a non-loopback bus logs a warning at startup: it is authenticated but cleartext.
- RDB length sanitization (SEC-006):
read_bytesrejects any chunk longer than 512 MB (MAX_VALUE_LEN) and grows with the bytes actually present; collections preallocate at most 4096 slots whatever count the file declares. Snapshots end with a CRC-32 that is checked on load. The Redisdump.rdbimporter (--import-redis-rdb) reads strings withtake+read_to_endinstead ofvec![0; len], refuses LZF strings claiming more than the compressed bytes could expand to, and caps collection pre-allocation at 4096 slots. - AOF replay (SEC-006): nothing is allocated from a length in the file
before the bytes are there. A file that ends part-way through a command
(a crash mid-write) loads everything before it with a
warn, like Redis'aof-load-truncated yes. Anything else that does not parse is corruption, and the server refuses to start rather than serve a partial dataset and append after the damage. A trailingMULTIblock without itsEXECis not applied. - File permissions: the data directory is created
0700and every file the server writes (snapshot, AOF,cluster.json, cluster dumps,functions.lib, the ACL file, pid file, daemon log)0600, opened withO_NOFOLLOWwhere it is created. - AOF replay denylist (SEC-007):
EVAL,EVALSHA,SCRIPT,DEBUG,SHUTDOWN,BGREWRITEAOF,BGSAVE,SAVE,SLAVEOF/REPLICAOF,CLUSTER,MIGRATE,RESTORE,MODULEare skipped (with awarn) on replay. Scripts are never replayed: their effects are logged as they run. The data directory must still be on a filesystem only the SoliKV UID can write to — replay is not authenticated.
- Daemon log:
--daemonlogs to<data-dir>/solikv.log(or--logfile), not a fixed/tmp/solikv.loganother user could pre-create as a symlink. - Container: the Docker image runs as UID 10001, not root; a bind-mounted data directory must be writable by that UID.
- PID file (SEC-003):
<data-dir>/solikv.pid. The "kill old daemon" path resolves/proc/<pid>/exe, canonicalizes both that andcurrent_exe(), and only signals the PID if the canonical paths match. - Cluster dump password (SEC-008):
--cluster-dump/--cluster-restoreonly send--cluster-passwordto the seed node by default; pass--cluster-password-seed-only=falseto AUTH against discovered nodes.--cluster-userauthenticates as an ACL user. - Secret sources (SEC-009):
--requirepass-file,--cluster-password-file,--cluster-bus-secret-fileand--rest-token-file(preferred), or theSOLIKV_REQUIREPASS/SOLIKV_CLUSTER_PASSWORD/SOLIKV_CLUSTER_BUS_SECRET/SOLIKV_REST_TOKENenvironment variables. Secret files are opened withO_NOFOLLOWand rejected if their mode is looser than0600. The CLI forms remain for compatibility but log awarnbecause/proc/<pid>/cmdlineexposes them to other local users. - Installer (SEC-011):
install.shverifies the tarball against the release'sSHA256SUMSline for it, and aborts on any missing piece. The checksum comes from the same origin as the tarball: it proves integrity, not authenticity.
- EVAL/EVALSHA arithmetic (SEC-012):
numkeys + 2useschecked_add; same forZUNIONSTORE/ZINTERSTORE. - RESP decoder (SEC-013): no allocation from an untrusted
*Nheader; an unauthenticated peer cannot declare arrays larger than 32 elements or bulk strings larger than 64 KiB; nesting is bounded (see above). - FFI memory safety (SEC-010): no
static mut; everysolikv_*extern validates pointers and lengths. - Lua (SEC-014): scripts run on Lua 5.1 with Redis 7's isolation:
globals and libraries (
string,table,math,redis,cjson, …) are read-only, and nothing a script leaves behind survives it. Each VM is capped at--lua-memory-limitbytes (default 64 MB), scripts are loaded in text mode only, andSCRIPT KILL/FUNCTION KILLcan stop a read-only script past--busy-reply-threshold. - Build artifact hygiene (SEC-015):
.gitignoreexcludes rustc artifacts. - Per-command resource bounds:
SETRANGEoffsets are capped at 512 MB;SETBIT/GETBIToffsets must be below 2^32;BF.RESERVErefuses filters above 512 MB; pop/scanCOUNTs no longer size an allocation; TTL arithmetic is checked. - Solo mode thread safety:
--solokeeps its store unlocked on the promise that one thread touches it; nothing hands its worker to a second thread (block_in_placeruns inline in solo mode), and debug builds assert the store is never entered twice.
- No Sentinel: failover exists in cluster mode only; a standalone master/replica pair has no automatic failover.
- Bus membership is shared: the bus secret (and, with
--tls-cluster, the CA) proves membership, not identity — any member can sign as any node. A compromised node can rewrite the topology. - Argv password leakage: secrets given as CLI flags remain visible in
/proc/<pid>/cmdlineuntil the process exits. Prefer the file or environment form.
- Run with
--requirepass-file(or ACL users in--aclfile) and 0600 files. - Bind to loopback (
--bind 127.0.0.1) unless TLS is configured. - For multi-host deployments:
--tls-cert/--tls-keyplus--tls-ca-cert(client certificates on RESP and REST),--tls-replication yesfor replicas, and give REST its own token — or disable it with--rest-port 0if unused. - In cluster mode, set
--cluster-bus-secret-file(separate from any client password) and--tls-cluster yesunless the bus runs on a private network; use a CA dedicated to the cluster. - Keep the data directory on a filesystem writable only by the SoliKV UID (AOF replay trusts the file).