vault

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 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

Option	Description
-h, --help	Display usage information and exit. Supported for all sub-commands.
-p, --purl	Required. 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-key	Provide 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.
--password	Used 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-list	Used 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.
--replace	Used 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.
--silent	Used only with the remove sub-command. Don't prompt for removal confirmation.
-r, --reset-key	Used only with the init sub-command. Change the existing vault key to a new value.
-s, --rl-store	Path 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.

Input

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

Output

Password vault initialized for /home/armando/my_repository/.rl-secure 

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.

Input

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

Output

Password vault re-initialized for /home/armando/my_repository/.rl-secure 

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. These passwords can be provided either directly in the terminal with --password or as a path to the file containing passwords by using --password-list.

Note that you can also use the --password and the --password-list options simultaneously.

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.

Input --password

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

Input --password-list

rl-secure vault update --vault-key SECRETKEY --replace --password-list ~/passes.txt --purl pkg:rl/my_project/test@v2

Output

Appended 1 entries to password vault for 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.

Input

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

Output

 ... done
Silently removed passwords my_project/test@v2
 ... done
Silently removed passwords my_project/test@v1