Credential Encryption

Raven encrypts protected credential fields (captured NTLM/Kerberos hashes, cracked and configured passwords, and breach passwords) at rest with AES-256-GCM. The installation-wide key is kept outside engagement.db.

This protects those credential fields, not the whole engagement. Hostnames, findings, notes, logs, exports, and ordinary configuration are outside that protection. BYO provider keys are stored in a separate private file on the Raven host; they are not encrypted by the credential database key. Protect the host, settings, backups, and exported files accordingly.

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 up the installation key in a password manager and retain it with recovery records for every engagement using that key.

How the key is chosen

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

1. The RAVEN_DB_KEY environment variable.
2. The file named by RAVEN_DB_KEY_FILE.
3. The OS keychain.

Explicit RAVEN_DB_KEY or RAVEN_DB_KEY_FILE settings take precedence. The current individual Docker image can create a key on its persistent account mount. A desktop start can create one in a usable OS keychain. Other deployments need an explicit key; Raven does not generate a disposable replacement when safe persistence is unavailable.

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 Settings → Data & recovery → This installation → 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 Raven installation and the engagements that use it.

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.

Individual Docker image

With the documented separate mount at /home/raven/.raven, the current individual image creates /home/raven/.raven/db.key on first boot and reuses it on later starts. The file is owned by the raven user with private permissions; the account directory is separate from engagement data. This is the persistent auth/ bind mount or account named volume, rather than the disposable container layer. See Install Raven for the mounts.

Back up the account mount together with the engagements that use its key. Deleting the account volume while keeping encrypted engagement data loses the key. Raven refuses to invent a replacement in that recovery case; restore the original account volume or configure the original key explicitly.

To view the saved key for a secure backup:

docker exec --user raven raven-pro cat /home/raven/.raven/db.key

Copy it directly into your password manager. Keep it out of shared logs and support messages. If you supplied an explicit environment key or mounted key file, back up that original source instead.

A missing persistent account mount leaves credential writes disabled. An invalid, unreadable, or unsafe explicit key is diagnosed rather than silently replaced. Existing RAVEN_DB_KEY and RAVEN_DB_KEY_FILE settings retain their precedence.

Explicit keys and custom or Team deployments

You can continue to supply a key from the host. Custom or Team deployments retain their explicit key setup; the individual image's account-volume provisioning is not a general Team-server provisioner.

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

You do not need any file from the repository to configure an explicit key. Generate it once, keep a secure 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 deployment: 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: Settings → Data & recovery → This installation → 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.