Unraid SecretGuard

Unraid SecretGuard helps keep Docker credentials out of Unraid's unencrypted Docker template XML files on the flash device.

Status: Public beta. Test migrations on a non-critical container first.

Installation and updates

Install SecretGuard from the public manifest:

https://raw.githubusercontent.com/mr1beast/unraid-secretguard/main/unraid-secretguard.plg

In Unraid, open Plugins -> Install Plugin and paste the URL above.

The installed plugin uses the same public manifest as its pluginURL. When a newer tested manifest is pushed to the repository's main branch, Unraid can detect it through Plugins -> Check for Updates.

main/unraid-secretguard.plg is therefore the update channel and should only contain tested release builds.

Understanding SecretGuard's protection

SecretGuard removes selected credentials from flash-stored Docker XML templates and manages them using the configured protection method.

• Plain env stores credentials outside the Docker XML template in a permission-restricted env file. Use encrypted persistent storage when possible.
• Encrypted Vault encrypts SecretGuard-managed credential files at rest and requires the master password after reboot. The master password is not stored and there is no recovery backdoor.
• HIGH / MEDIUM in the audit are detection-confidence levels, not security scores.
• SecretGuard never needs to display credential values in its audit UI.
• SecretGuard does not replace host security. Docker and a user with root access to an unlocked server may still be able to access credentials required by running containers.

What it does

• Scans only Docker containers currently installed on the Unraid host.
• Detects likely secrets such as passwords, API keys, tokens and client secrets.
• Never displays secret values in the WebGUI.
• Moves selected values from Docker XML templates into managed .env files.
• Supports an encrypted Vault mode for hosts without encrypted secret storage.
• Automatically recreates the affected Docker container after migration.
• Shows which containers are protected and which variables are managed.
• Supports variable-level rollback without restoring an old XML snapshot.
• Keeps unrelated ports, paths, labels and later template changes untouched.
• Watches new or changed installed Docker templates and can send Unraid notifications.
• When Vault mode is in use, the always-on watcher stops Vault-protected containers after reboot until the Vault is unlocked, preventing them from starting without their protected runtime env files.

Security model

SecretGuard discovers mounted persistent Unraid storage instead of assuming that every server has a cache pool. The storage selector always shows cache as the conventional Unraid choice, but an absent/unmounted cache is clearly marked NOT MOUNTED / NOT PERSISTENT and is never recommended automatically.

On systems with confirmed encrypted persistent storage, the recommended mode is Plain env files. SecretGuard prefers a mounted cache pool when available; otherwise it can use another mounted disk or pool selected by the user, for example:

/mnt/cache/appdata/secrets/
/mnt/disk1/appdata/secrets/

Plain mode is blocked when the configured path resolves to rootfs, tmpfs, RAM, or an unmounted pool path. If storage encryption cannot be confirmed, SecretGuard recommends Encrypted Vault instead.

Important: standard Docker environment variables may still be persisted in Docker's own container metadata. For strongest at-rest protection, use encrypted Docker storage or application-supported file secrets where possible.

Dedicated SecretGuard share

SecretGuard can optionally create a dedicated Unraid share named secretguard on a selected mounted persistent disk or pool. The plugin still uses the physical path directly, such as /mnt/cache/secretguard or /mnt/disk1/secretguard, rather than /mnt/user/secretguard.

When SecretGuard creates the share it sets directory permissions to 0700, disables SMB and NFS export, pins the share to the selected pool/disk, and refuses to overwrite an unrelated existing secretguard share. For Plain env mode, encrypted persistent storage is recommended; otherwise use Vault mode.

Vault lifecycle and reboot procedure

Vault mode deliberately does not store the master password or derived master key.

Persistent data contains only:

/boot/config/plugins/unraid-secretguard/vault.json
    salt
    KDF parameters
    authenticated encrypted verifier

<secret directory>/*.sgv
    encrypted SecretGuard data

While the Vault is unlocked, volatile RAM contains:

/run/unraid-secretguard/master.key
/run/unraid-secretguard/env/*.env

/run disappears at reboot.

After reboot

1. SecretGuard starts with the Vault LOCKED.
2. The background watcher stops Vault-protected containers that autostart while locked.
3. Open Settings -> User Utilities -> Unraid SecretGuard.
4. Enter the same Vault master password used when the Vault was created (or the most recently changed password).
5. SecretGuard derives the same key from the password, stored salt and KDF parameters.
6. The authenticated verifier confirms whether the derived key is correct.
7. SecretGuard decrypts runtime env files into /run.
8. Containers remembered by the lock/boot guard are recreated and started.

A wrong password does not alter or delete encrypted data.

Failed unlock protection

Failed attempts are rate-limited for the current boot:

• Attempts 1-3: 2 second cooldown
• Attempts 4-5: 10 second cooldown
• Attempts 6-10: 60 second cooldown
• Attempt 11 and later: 15 minute cooldown

Repeated failures generate syslog events and Unraid notifications. The retry state is intentionally volatile and resets at reboot; its purpose is to slow WebGUI guessing, not to replace Argon2id protection against offline attacks.

SecretGuard never automatically destroys Vault data after failed password attempts.

Changing the master password

The current master password must be verified first. SecretGuard then:

1. decrypts the existing Vault data in memory;
2. generates fresh salt/KDF metadata and a new derived key;
3. re-encrypts every .sgv to temporary files;
4. decrypts and authenticates each temporary file with the new key;
5. only after all files verify, activates the new files and Vault metadata.

If staging or verification fails, SecretGuard attempts to retain/restore the old encrypted Vault.

If the master password is forgotten, SecretGuard has no recovery password or backdoor. Back up important credentials separately in a secure password manager.

Versioning

SecretGuard uses Unraid-style date versions (YYYY.MM.DD). If multiple releases are needed on the same day, a numeric revision suffix is used, for example 2026.09.13.5.

Resetting the Vault

The WebGUI provides Delete / Reset Vault. The action is fail-safe: it is blocked while any installed container still uses Vault mode or any encrypted .sgv file remains in the configured secret directory. After a successful reset, a new Vault can be initialized with a completely new master password.

WebGUI layout

SecretGuard opens on the Overview tab, which contains the protection overview and expandable Docker template audit. Storage, dedicated share and Vault configuration are grouped under the Settings tab.

Installation

Download unraid-secretguard.plg from a release and install it on Unraid. The manifest downloads the matching SHA256-verified .txz release asset and installs it with Unraid's Slackware package tooling:

plugin install /path/to/unraid-secretguard.plg

After installation open:

Settings -> User Utilities -> Unraid SecretGuard

Local build

Requirements:

• bash
• tar with xz support
• sha256sum

Build with:

./build.sh

Output is written to:

dist/

Repository layout

.
├── README.md
├── CHANGELOG.md
├── LICENSE
├── .gitignore
├── build.sh
└── src/
    └── usr/local/emhttp/plugins/unraid-secretguard/

Rollback behavior

SecretGuard does not restore a complete historical Docker XML file.

Each migrated variable stores the metadata required to rebuild only that Docker variable. Rollback restores those variables, removes the SecretGuard env source, deletes the managed secret file, and recreates the container.

This avoids rolling back unrelated changes made to ports, paths, labels or other container configuration after the secret migration.

Adopting an existing env file

An installed container shown as Protected / plain / Legacy env: no variable metadata can be adopted by SecretGuard when its Docker template points to an existing, parseable env file on confirmed persistent storage.

Before adoption, SecretGuard shows a confirmation containing only the container name, env path, and variable names. Adoption does not read secret values into the UI, rewrite the env file, change Docker ExtraParams, or recreate the container.

SecretGuard stores only non-secret adoption metadata in:

/boot/config/plugins/unraid-secretguard/adopted/<safe-container>.json

After adoption, Protection overview shows Managed by SecretGuard and Adopted existing env. Rollback to Docker XML remains unavailable because a legacy env file does not contain the original XML variable metadata required for a safe rollback.

License

MIT License.

Publisher

mr1beast