Skip to main content

vault

Active license required

Description​

Preserves user-provided passwords for individual package versions in the package store.

By default, rl-secure can scan password-protected files, but cannot decrypt them to extract their contents. To decrypt such files, you need to associate passwords with the files when scanning them for the first time. Without a password, rl-secure cannot detect any issues in the file, since the file cannot be extracted.

Use this command to manage passwords used by rl-secure for decrypting password-protected files during analysis.

File format support

Decrypting password-protected files is supported only for a limited set of file formats.

In the list of supported formats, those with a checkmark in the "Password Support" column can be decrypted and extracted with passwords saved in the vault.

Password vault​

For rl-secure to successfully decrypt the files, their passwords must be saved in the password vault. When you initialize a package store, it does not use the password vault by default.

If you want to initialize a package store and its password vault simultaneously, use init with the --vault-key option.

In an existing package store, you can enable the vault with the following commands:

  • vault - creates the vault at any point after the package store has been initialized
  • scan with the --vault-key and --password/--password-list/--encoded-password-list options - automatically creates the vault when you scan a password-protected file and provide its password along with the vault key

With the vault init sub-command, the password vault is initialized for the selected package store. During the vault initialization, you need to provide the vault key, which can be any arbitrary string. This key is required to access and modify the passwords, and it's used to protect the vault and the passwords inside it. If your organization has key rotation policies in place, you can use this sub-command to update your vault key at any time.

Every password saved in the vault must be associated with a specific package version. You cannot save a password as a "global" value or associate it with a project so that it automatically applies to all packages and versions in it.

The vault update sub-command allows you to change saved passwords or add new ones to the existing password vault.

Passwords associated with the specified package versions can be deleted from the vault with the vault remove sub-command. Note that vault remove is used only for deleting individual passwords. The password vault itself cannot be removed from your package store once it's initialized.

Passwords saved to the vault are only used for extracting protected files during analysis (with the scan and sync commands). Passwords don't need to be used when removing password-protected files from the package store, or when exporting analysis reports.

Usage​

rl-secure vault <sub-command> [<option>]

rl-secure vault init <key> [<options>]

rl-secure vault update <purl> <key> [<options>]

rl-secure vault remove <purl> [<options>]

Options​

Supported sub-commands:

  • init
  • update
  • remove
OptionDescription
-h, --helpDisplay usage information and exit. Supported for all sub-commands.
-p, --purlRequired. Package URL of the project or package for which you want to add or modify the password in the vault. Must be in the format [pkg:type/]<project>[/<package>]. Project and package names must be unique on the package store level.
-k, --vault-keyProvide the password vault key used to protect the stored passwords. Required if a password is provided. Note that this value is case-sensitive and can be changed at any time.
--passwordUsed only with the update sub-command. Password to add to the vault. You can provide multiple passwords at once as a comma-separated list: --password example1, Example2, exampl3. Note that these values are case-sensitive. Only the last provided password is used to extract the file during the analysis. Passwords do not need to be provided when removing a password-protected package version from the package store or when exporting a report.
--password-listUsed only with the update sub-command. Password list file (newline-separated plain text) to add to the vault. You can provide multiple password list files at once: --password-list path/to/file.txt --password-list ./another-file.txt.
--encoded-password-list, --encoded-listUsed only with the update sub-command. Specify the Base64-encoded contents of a password list that will be used when trying to unpack password protected files. You can provide multiple Base64-encoded contents of password list files at once: --encoded-password-list FirstBase64EncodedString --encoded-password-list SecondBase64EncodedString.
--replaceUsed only with the update sub-command. Remove all existing vault entries for a package version and replace them with new entries provided with the --password and/or --password-list parameters.
--silentUsed only with the remove sub-command. Don't prompt for removal confirmation.
-r, --reset-keyUsed only with the init sub-command. Change the existing vault key to a new value.
-s, --rl-storePath to an initialized package store containing the package URL. If you don't specify the path, the current directory is used.

Examples​

Initialize the password vault​

This example initializes a password vault in an existing package store and creates a vault key that protects the passwords that will be stored inside the vault.

The command expects the package store to exist in the current directory. Use the -s or --rl-store options to provide an alternative path to the package store.

rl-secure vault init --vault-key SECRETKEY -s /home/armando/my_repository/

Update the vault key​

This example replaces the old vault key value with a new one for the specified package store.

The command expects the package store to exist in the current directory. Use the -s or --rl-store options to provide an alternative path to the package store.

rl-secure vault init -k OLDKEY -r NEWKEY -s /home/armando/my_repository/

Update the passwords stored in vault​

This example replaces the existing passwords stored in the vault for a specified package version with the new ones.

There are 3 ways to provide the password for a package version:

  • as a literal password string with the --password parameter
  • as a path to the file containing a list of passwords (one on each line) with the --password-list parameter
  • as Base64-encoded contents of a password list file in a string format with the --encoded-password-list parameter

Note that you can also use all three password options in the following ways:

  • --password with --password, --password-list and/or --encoded-password-list
  • --password-list with --password-list, --encoded-password-list and/or --password
  • --encoded-password-list with --encoded-password-list, --password and/or --password-list

After this, if you want to re-scan the package with the new passwords, you can do so with the sync command.

The command expects the package store to exist in the current directory. Use the -s or --rl-store options to provide an alternative path to the package store.

rl-secure vault update --vault-key SECRETKEY --replace --password NEWPASSWORD --purl pkg:rl/my_project/test@v2

Remove the stored passwords​

This command deletes all passwords stored in the password vault for a specific project.

For every package version in the project, you will get a prompt to choose whether you want to remove passwords for that package or not. To automatically skip those prompts, you can use the --silent option.

The command expects the package store to exist in the current directory. Use the -s or --rl-store options to provide an alternative path to the package store.

rl-secure vault remove --purl=pkg:rl/my_project/* --silent