Security
This page tells what ndb protects, what it does not protect, and what you must do. Read it before you put ndb on a network.
Threat model
- ndb is a database for servers. Your apps, the console server and the CLI talk to it. A browser must not talk to it directly.
- ndb trusts every client that can open the unix socket. It trusts every TCP client that has a token.
- ndb does not trust web pages in a browser on the same machine. It does not trust clients on the network that have no token.
- ndb has no TLS, no user accounts and no encryption of data at rest. A proxy, the network and the disk give these.
Listeners
ndb listens on a unix socket and, optionally, on TCP.
- Unix socket (
listen.unix). The file permission is the access control. The default mode is0660: the owner and the group have full access, with no token. Put in the group only the users and containers that may read and write all data. Uselisten.unix_modeor-unix-modeto change the mode. - TCP (
listen.tcp). A server install has no TCP listener. A user install (a laptop) listens on127.0.0.1:7070with no token. Bind TCP to127.0.0.1or to a private address only. Never bind it to a public address.
Tokens and scopes
-token-file(orNDB_TOKEN_FILE,NDB_TOKEN) ortokens:inndb.ymlmake every TCP request sendAuthorization: Bearer <token>. A missing or wrong token is401 unauthorized.- A scoped token can read, write or administer only some collections. A token without the right is
403 forbidden. See Scoped tokens. - ndb compares tokens in constant time. Logs show the token name, never the secret.
- Make each token from 32 random bytes. Give each app its own token with the smallest scope.
POST /_backupworks only on the unix socket.
Browser attacks (CSRF and DNS rebinding)
A web page in a browser can send requests to 127.0.0.1:7070. ndb refuses two attacks.
CSRF. A page sends a "simple" request (for example POST with Content-Type: text/plain). The browser sends no preflight, but it adds the Origin header.
- ndb refuses each request that has an
Originheader with403 forbidden. The message names the origin and the setting. - ndb also refuses a request with
Sec-Fetch-Site: cross-siteorsame-site(an image, a link from another site). - curl, the SDKs, the CLI and the console server send no
Origin. They work as before. - This guard applies to every listener, the unix socket too.
- To let a browser app call ndb directly, put its origin in
cors_origins(for examplehttps://app.example.com). ndb then answers withAccess-Control-Allow-OriginandVary: Origin, and answers the preflightOPTIONSwith204. Without an allowed origin,OPTIONSstays405 method_not_allowed. The page must still send a token: do this only with a token of a small scope.
DNS rebinding. A page at evil.example changes its DNS record to 127.0.0.1. Then its requests go to ndb, and the page can read the answers. The browser sends Host: evil.example.
- On TCP with no token configured, ndb accepts only a
Hostthat is an IP address,localhost, a name with no dot (a Docker Compose service such asndb) or a name inallowed_hosts. Any otherHostis403 forbidden. - With a token, ndb does not check the
Host: a rebound page cannot send the token. - The unix socket does not check the
Host. - Use
allowed_hostsfor a private DNS name, for examplendb.internal, when the daemon has no token.
The best protection is a token, also on a laptop. With a token, a web page cannot read or write anything.
Brute force
ndb counts the failed token checks (401) of each client IP.
- After
auth_failuresfailures (default10) inauth_window(default1m), the IP gets429 too_many_requestsforauth_lockout(default5m). The answer has aRetry-Afterheader. The daemon writes awarnlinetoken lockoutwith the IP. - During the lockout, ndb refuses all TCP requests from that IP, also with the right token. Thus a guess cannot be tested.
- A request with the right token never counts as a failure.
- An IPv6 client counts by its
/64network. - ndb remembers at most 10 000 IPs. Over that, it forgets the IP it saw least recently.
- The unix socket has no token check, so it has no lockout.
auth_failures: 0turns the lockout off.
Behind a proxy, all clients have the IP of the proxy. Then one bad client locks out all clients. Set trust_proxy: true to use the last hop of X-Forwarded-For (the address that the proxy added). Set it only when a proxy is in front: without a proxy, a client can write any X-Forwarded-For.
TLS
ndb has no TLS. Plain HTTP is safe on the same host (the unix socket, 127.0.0.1) and over an encrypted private network such as WireGuard (Two VMs). When clients come from a network that is not encrypted, you must put a TLS proxy in front. Voodu does this for you.
Caddy gets and renews the certificate:
ndb.example.com {
reverse_proxy 127.0.0.1:7070
}nginx:
server {
listen 443 ssl;
server_name ndb.example.com;
ssl_certificate /etc/ssl/ndb.crt;
ssl_certificate_key /etc/ssl/ndb.key;
location / {
proxy_pass http://127.0.0.1:7070;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_buffering off; # _watch streams
proxy_read_timeout 1h; # _watch streams and block_ms reads
}
}Always set a token when a proxy publishes ndb. With a proxy, set trust_proxy: true.
Data at rest
ndb writes plain files: the WAL is NDJSON, the segments are Parquet, the blobs are raw bytes, and a backup is NDJSON. Any user who can read the data dir can read all data.
- Keep the data dir owned by the
ndbuser with mode0750or less. - Use disk encryption (LUKS, an encrypted cloud volume) when the data is sensitive.
- Encrypt the backups before you copy them off the host (for example
ageorgpg), and limit who can read them. A backup holds the encryption key unless it comes from the env. - A token file must have mode
0600.
The encryption key
Each data dir has one encryption key of 32 bytes. The encrypted fields use it. At start the daemon takes, in this order:
NDB_ENCRYPTION_KEY: 64 hex characters (openssl rand -hex 32). It is not written to the data dir; only its fingerprint is, so a later start with no env, or with another key, stops with an error instead of reading nothing.- The key kept in the data dir, in
_system/settings.wal(mode0600). - None: the daemon makes one, keeps it, and logs a
warnline once.
GET /_cluster/settings shows the key masked (e5af****…****edff) and where it came from. No answer and no log line has the whole key.
What protects what:
| Leak | The key kept in the data dir (default) | The key in NDB_ENCRYPTION_KEY |
|---|---|---|
| a backup file | not protected: a backup holds the settings, the key with them | protected |
| a copy of the data dir or of the disk | not protected | protected |
| the memory of the daemon | not protected | not protected |
To change the key, use a key rotation (ndb key rotate, on the host only). NDB_ENCRYPTION_KEY_OLD gives the old env key during one.
So the default makes a restore need nothing. To keep the key out of the files, give it in NDB_ENCRYPTION_KEY from a secret store, and keep a copy of it: a backup of a data dir with an env key can only be restored with the same key.
Encrypted fields
The full guide, with the examples of each client, is Encrypted fields. This part is the security view.
A field in encrypted is not stored as you send it. Before the WAL, the daemon replaces its value with "ndb:e1:k1:<base64url>": AES-256-GCM of its JSON (a string, a number or an object), with a random nonce. So the WAL, the segments, the backups and the logs never have the plain value.
curl --unix-socket /run/ndb/ndb.sock -X PUT http://ndb/users -d '{"encrypted":["cpf","private_key"]}'e1is the format andk1the key. Each value is bound to its collection and field: a value copied to another field or collection does not decrypt.Who reads the value: an answer has the stored
"ndb:e1:k1:..."by default. It has the plain value only when the call asks with?decrypt=1and the caller has the right: the unix socket, the token of-token-file, or a token withdecrypton the collection. A caller without the right that sends?decrypt=1gets the stored value, not an error. This applies to every read:_doc,_search,_count,_aggregate,_watch, thedocof_updateand_lock, and the documents that a lookup adds (with the right on the collection they come from).bashcurl --unix-socket /run/ndb/ndb.sock http://ndb/users/_doc/u1 # "cpf":"ndb:e1:k1:..." curl --unix-socket /run/ndb/ndb.sock 'http://ndb/users/_doc/u1?decrypt=1' # "cpf":"390.533.447-05"SDKs send
decrypt=1on every read, so an app with the right reads the values.encrypted(Govault.Encrypted(), TSvault.encrypted(), Rubyvault.encrypted, RailsSecret.encrypted) sendsdecrypt=0: for a list of secrets that shows none of them, and a second read with the value when the user asks for it.Writes:
_doc,_bulk, upsert,_txand$setencrypt the field.$inc,$pushand the other operators on it are400 invalid_query: they need the value.Filters: only
$exists. Any other filter on the field is400 invalid_query, unless the field is blind.Aggregate:
$matchfollows the filter rules.$firstand$lastof the field give its value. Any other use ($sum,$max,$project) is400 invalid_query; a$groupby the field needs it to be blind.Logs: no request body or document of a collection with encrypted fields goes in a log line, at any level.
A field added to
encrypted(orblind) later is encrypted in the old documents by a background job, as an index build. See A field added later. The old plain values stay in the WAL files and in older backups untilwal_retentionand your backup rotation drop them.Console: it never sends
decrypt=1, so it shows[encrypted], never the value. An edit of the document keeps the stored value.Cost: a write of a document with a 2 KB
.pemtakes about 10% more time, a read about 8% more (make bench, with a check at 25%).The key protects the files only when it is in
NDB_ENCRYPTION_KEY(see The encryption key). With the default key, encrypted fields keep the value out of the API for tokens with nodecrypt, the logs and the console.
Blind fields
A blind field is an encrypted field that a filter can find by its value. A field in blind is also encrypted: you do not have to put it in encrypted too. The daemon keeps a second value in the document, <field>_bidx: an HMAC-SHA256 of the normalized value ("ndb:h1:k1:<hex>"), with a key of its own. A filter on the field is changed to a filter on that hash.
curl --unix-socket /run/ndb/ndb.sock -X PUT http://ndb/users \
-d '{"encrypted":["cpf"],"blind":{"cpf":"numeric"},"unique":["cpf"],"indexes":["cpf"]}'
curl --unix-socket /run/ndb/ndb.sock http://ndb/users/_search -d '{"query":{"cpf":"390.533.447-05"}}'| Normalization | The hash of | For |
|---|---|---|
exact (default) | the value as sent | tokens, ids |
lower | the value in lower case, with no spaces at the ends | an email |
upper | the value in upper case, with no spaces at the ends | a car plate, a code |
numeric | only the digits (a zero at the start stays) | a CPF, a card, a phone, with or without dots and dashes |
blind is an object of field and normalization, or a list of fields that are all exact: "blind":["card_token"].
- Filters:
$eq(or a plain value),$in,$ne,$ninand$exists, also inside$and,$or,$nor, in_count,_update_by_query,_delete_by_queryand in$match. A range,$regexor a sort need the value:400 invalid_query. - Indexes:
indexesanduniqueon the field (also in a compound key) use<field>_bidx; the definition shows that name. - Aggregate:
{"$group":{"_id":"$cpf"}}(also as a key of a compound_id) groups by the hash, so390.533.447-05and39053344705are one group. The_idof each group is the value of one of its documents: plain for a caller that may decrypt, else"ndb:e1:k1:...". A$sortor$matchon that_idafter the group sees the hash. <field>_bidxis in no answer. A value sent in it is replaced.- The hash of a value is the same for each document, so who reads the files sees which documents have the same value. It does not show the value: the HMAC key is derived from the master key.
- A field made blind later gets a hash in the old documents from the same job. Until it is
ready, a filter also finds the old plain values.
What to encrypt
- A user password: do not encrypt it. Keep a hash (bcrypt or argon2) made by the app. Nobody needs to read a password back, the daemon too.
- A card number, a CPF, a document number:
encrypted, andblindwhen the app finds the record by it. Givedecryptonly to the service that must show or send the value. - A key or a certificate (
.pem,.pfx), an API token of a third party:encrypted.
Logs
At the debug level, a request line has the body, and a write line has the documents (cut to log_body_max, default 2048 bytes). So debug logs contain your data.
- Use
debugonly for a short time.PUT /_logchanges the level without a restart. - Set
log_body_max: 0to log no bodies. - Logs never contain the
Authorizationheader or a token secret, nor a body or a document of a collection with encrypted fields.
Images
| Image | Use |
|---|---|
ghcr.io/thadeu/ndb | the daemon, for servers. |
ghcr.io/thadeu/ndb-ui | the console. It has no login: run it only behind authentication (a proxy with a login, a VPN) or on 127.0.0.1. |
ghcr.io/thadeu/ndb-stack | the daemon and the console in one image, for development only. It has no token by default and listens on 0.0.0.0. Never use it in production. |
Denial of service limits
ndb has limits, so that one request cannot stop the daemon:
- Body size:
max_line_sizeof the collection (default 1 MiB),blob_max_sizefor blobs. Over it:413 request_too_large. - Regular expressions use RE2: the time is linear, with no catastrophic backtracking. A pattern is at most 1 KiB.
- Collection patterns match at most 256 collections (
pattern_too_wide). - Aggregate: one group table is at most
group_limit(group_limit_exceeded). A lookup attaches at most 10 000 documents (lookup_too_large). - Client cancel: when the client leaves, ndb stops its query.
max_connslimits the open TCP connections (default0, no limit). Over it, a new connection waits until another one closes. The SDK pools limit the connections of one app (GoWithMaxConns, Rubypool_size:);max_connslimits the whole daemon. An idle keep-alive connection uses a slot for up to 60 s.max_watcheslimits the open_watchstreams (default0, no limit). Over it, a new_watchis429 too_many_requestsbefore the stream starts./_metricsshows the open streams inndb_watch_streams.- Slow headers: a client has 10 s to send the request headers.
Operator injection in apps
A query is a JSON object, and its values can be operators such as $ne, $gt or $regex. ndb has no $where and runs no code, but if an app puts user input in a query as an object, a user can change the query. For example, a login form that sends {"password": {"$ne": ""}} matches every user.
- Never pass user input as a query object. Read the input as a string or a number, then build the query in code:
{"email": email}whereemailis a string. - Check the type of each field from a request body before you use it in a query.
- Do not let users choose the collection name, the
sortor thefieldswithout an allow list.