Credential Encryption¶

Raven encrypts the client secrets it captures (NTLM/Kerberos hashes, cracked and configured passwords, breach passwords) at rest with AES-256-GCM. A stolen engagement.db file is useless without the encryption key, which is kept outside the database.

The key is called RAVEN_DB_KEY. This page tells you exactly where it lives for your deployment, how to view and back it up, and how to recover.

Losing the key = unrecoverable credentials

The key is the only thing that can decrypt captured credentials. If you lose it, those credentials are gone for good. There is no recovery, no reset, no backdoor. Back the key up per engagement, in a password manager, the moment it's created.

How the key is chosen¶

On startup Raven looks for a key in this order and uses the first it finds:

The RAVEN_DB_KEY environment variable.
The file named by RAVEN_DB_KEY_FILE.
The OS keychain.

If you set RAVEN_DB_KEY or RAVEN_DB_KEY_FILE yourself, that always wins. If you set nothing, Raven auto-provisions a key on first boot so encryption just works. The details differ by how you run Raven.

Idempotent, never rotated

An existing key is always reused. Raven never silently generates a new key over an old one, because that would orphan everything already encrypted.

Desktop / single-user app¶

The first time you open the dashboard with no key configured, Raven generates a key and stores it in your operating-system keychain, not in a file next to your data, where it would offer no protection.


Where	OS keychain (macOS Keychain, Windows Credential Locker, Linux Secret Service)
Service name	`raven`
Account name	`db_key`

See the one-time backup prompt¶

Open Config → Global → Credential encryption. The card shows whether encryption is On or Off and, right after a key is first generated, a one-time "Reveal & copy key" button. Reveal it, copy it into your password manager, and click Done.

View / back up the key anytime¶

Any OS (via the bundled keyring):

keyring get raven db_key

macOS (native security tool):

security find-generic-password -s raven -a db_key -w

Copy the printed value into a password manager, labelled with the engagement.

No usable keychain (headless starts, locked keychains)

If the machine has no usable keychain, Raven does not invent a key that would vanish on the next restart. Encryption stays Off and credential writes fail until you set one yourself. Generate a key and export it:

export RAVEN_DB_KEY="$(python3 -c 'import secrets,base64; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())')"

This covers more than a bare Linux box. Raven never waits on a keychain dialog. A start with no desktop session able to answer one (nohup … &, setsid, launchd, systemd, ssh, CI), or a macOS login keychain that is locked, reports the keychain as unusable and carries on serving instead of blocking. Set RAVEN_DB_KEY on those hosts.

Docker / team server¶

A container is disposable: the documented redeploy is docker rm -f raven; docker run …. So Raven never generates the key inside the container (it would be lost on every redeploy and orphan your encrypted credentials). Instead the host holds the key in a 0600 file and mounts it read-only into the container.


Where (host file)	`/opt/raven/db.key` (team/beta server) · `~/.raven/db.key` (`raven-docker.sh`) · `deploy/customers/<name>.db.key` (per customer)
Mounted as	`/etc/raven/db.key` (read-only)
Container reads it via	`RAVEN_DB_KEY_FILE=/etc/raven/db.key`

No git checkout (published image, `.deb` or tarball)¶

You do not need any file from the repository. Generate a key once, keep a copy, then start the container with it:

# 1. Generate a key on the HOST and save it in your password manager.
python3 -c "import secrets,base64; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"

# 2a. Pass it as an environment variable (simplest). Note the bare
#     `-e RAVEN_DB_KEY` with no `=value`: docker then reads the value from its
#     own environment, so the key never enters docker's argv and never shows up
#     in `ps` on the host. Writing `-e RAVEN_DB_KEY="$RAVEN_DB_KEY"` would
#     defeat that, because the shell expands it before docker is exec'd.
read -rs RAVEN_DB_KEY && export RAVEN_DB_KEY   # prompts, so the key stays out of shell history
docker run -e RAVEN_DB_KEY ...   # keep your existing -p and -v flags

# 2b. Or keep it in a host file, which stays out of `docker inspect`:
umask 077 && printf '%s' "<key>" > /opt/raven/db.key
docker run -v /opt/raven/db.key:/etc/raven/db.key:ro \
  -e RAVEN_DB_KEY_FILE=/etc/raven/db.key ...

Reuse the same key every time you redeploy. A new key cannot read data encrypted with the old one.

From a git checkout¶

The provided scripts do this for you and print a loud backup notice the first time they generate a key:

scripts/raven-docker.sh: the local Docker wrapper. Provisions ~/.raven/db.key and mounts it automatically.
deploy/new-customer.sh: provisions a per-customer key file and wires it into that customer's compose file.
Team server (raven-beta.busydadsecurity.com): the deploy provisions /opt/raven/db.key, unless team.env already sets RAVEN_DB_KEY.

Provision or reuse a key on the host by hand with the same helper:

# Generate /opt/raven/db.key if missing (0600), reuse it if present:
scripts/raven-db-key.sh /opt/raven/db.key

# Or emit ready-made docker run args:
docker run $(scripts/raven-db-key.sh --docker-args /opt/raven/db.key) ... raven:latest

View / back up the key¶

cat /opt/raven/db.key

Store that value somewhere safe. To restore onto a rebuilt host, put the same value back at the same path (chmod 600) before starting the container. The same key decrypts the existing pentests/ data.

Setting the key explicitly instead

You can always skip auto-provisioning by setting RAVEN_DB_KEY yourself, in the deployment .env/team.env or with -e RAVEN_DB_KEY=…. A mounted key file is preferred over -e on shared hosts because the file is not exposed in docker inspect or the container's environment.

Checking status¶

Web UI: Config → Global → Credential encryption shows On/Off and where the key lives.
Boot logs: the dashboard prints Credential encryption: ON/OFF at startup (visible in docker logs raven).

If the card says Off, credential capture (Responder import, crack results, manual adds) will fail until a key is configured as described above.