Getting started with hv

This section covers the essentials you need to start using hv command-line tool: setting up authentication and understanding vault path formats.

hv credentials

In order to connect to the vault server, hv must at least have:

• a username

• a password

• a hostname

For example:

$ hv -hhexvault.acme.com:65433 -uadmin -psecret users
LastActive Adm    Login        Email
---------- --- ------------ ------------
2022-06-27  *  admin
2022-06-22     alice       Alice <[email protected]>
Never          bob         Bob <[email protected]>
...

There are 3 ways to specify credentials (in decreasing order of priority):

• providing them as command-line arguments (as in the example above)

• storing them in environment variables

• storing them in the registry+keychain (recommended)

All credentials, including usernames, are case-senstive, meaning that "Joe" and "joe" would be different users.

Command line

Passing credentials on the command line will always take precedence over environment variables and registry+keychain.

-uUSERNAME	specify username
-pPASSWORD	specify password
-hHOST	specify host (server:port) (if port is omitted, defaults to 65433)
-sSITENAME	specify site
--set	remember credentials. This option doesn’t require the credentials to be passed through the command line, credentials passed through environment variables will work as well

Environment variables

Credentials can also be passed through environment variables. They will take precedence over those possibly found in the registry+keychain.

VAULT_HOST	the server host name
VAULT_PORT	the server port
VAULT_USER	the username to connect to the server
VAULT_PASS	the user’s password
VAULT_SITE	the site to use (most commands need a site to operate)

Registry + keychain

Unless environment variables or command-line arguments are provided, hv will look for credentials in the registry (and the OS’s keychain for passwords.)

Credentials can be stored in the registry (and keychain) like so:

alice@alice_PC$ hv --set -ualice -palice -hvaultserver -salice_on_alicepc

The user, host (and optional site) will be persisted in the registry, while the password will be saved to the OS’s keychain.

For this operation to succeed, at least a user and host must be provided

In order to keep the various commands' syntax as clear as possible, we will assume that the user has stored credentials (in either the registry+keychain or environment variables) for the rest of this manual.

Best practices

We recommend persisting credentials using the registry+keychain method.

Once that is done, commands will become cleaner:

>./hv info

Hex-Rays Vault Server v1
Vault time: 2022-04-14 15:36:29, up since 2022-04-14 15:17:25
...

if you login to the server using hvui and save the login information, it will end up in the the registry+keychain method, and thus hv will then be able to use that information as well.

Path formats

Local paths refer to a file on the host file system.

Vault paths refer to a file mapped on the vault. They can start with // to refer to the root of the vault.

Some vault paths can optionally specify the revision of the path.

Special symbols were created to access specific revisions:

^	last revision available on the vault
=	current revision, that is synced on the site
*	all revisions

Special file revision symbols

subdir/	means all files in all subdirectories
subdir	means all files in all subdirectories (same as subdir/)
subdir/*	means all files in the directory

Directories and wildcards

Examples

Get the first revision of a file:

$ hv sync //malware/Ransomware.WannaCry/41aa.exe.i64#1
ok synced //malware/Ransomware.WannaCry/41aa.exe.i64#1 (838724 bytes)
ok sync completed

Sync to the last version of a file:

$ hv sync malware/Ransomware.WannaCry/41aa.exe.i64#^
ok synced //malware/Ransomware.WannaCry/41aa.exe.i64#3 (846916 bytes)
ok sync completed

Force sync to the current revision (we must specify -f to force a file transfer):

$ hv sync -f malware/Ransomware.WannaCry/41aa.exe.i64#=
ok synced //malware/Ransomware.WannaCry/41aa.exe.i64#2 (846916 bytes)
ok sync completed

Display md5 checksums of all revisions of a file:

$ hv md5 malware/Ransomware.WannaCry/41aa.exe.i64#*
ok 8F464140FA3DA4A20B03166F2E80325B //malware/Ransomware.WannaCry/41aa.exe.i64#1
ok E0F7B984151FEF497985F375C64FA5C7 //malware/Ransomware.WannaCry/41aa.exe.i64#2
ok 5C3B88306CF0D93DC35FFD67A710AE3B //malware/Ransomware.WannaCry/41aa.exe.i64#3

List Hex-Rays Vault server’s toplevel directory contents:

$ hv dir //
2022-06-02 10:29:30       140267 CL29/edit //malware/cppobj_virtcall.i64#9
2022-06-14 16:44:19      2173541 CL36/edit //iOS/dyld_ios16.i64#3

Plan to add a file to the vault:

$ hv add /path/to/local_rootdir/enable.png
ok added '//enabled.png'

Plan to add a directory:

$ hv add /path/to/local_rootdir/REsearch
ok added '//REsearch/vm2vm.dat'
ok added '//REsearch/vm2vm.exe'
ok added '//REsearch/vm2vm.i64'

Plan to delete a file:

$ hv del /path/to/local_rootdir/REsearch/*.dat
ok checked out '//REsearch/vm2vm.dat' for 'del' (worklist 1)

Show worklist to which files were added:

$ hv worklist show
WL 1 add  //REsearch/vm2vm.exe#0
WL 1 add  //REsearch/vm2vm.i64#0
WL 1 edit //cppobj_virtcall.i64#9
WL 1 add  //enabled.png#0

It is safe to interrupt a command using Ctrl-C. The file transfers in action will be gracefully terminated, so that no partially received files will be left on the disk. However, the requests that were delivered to the server will still be carried out up to the completion. For example, if the user asked to check out thousands of files for editing, this will be performed even if the user presses Ctrl-C after invoking the command.

If the command syntax specifies ellipsis (…​), it means that multiple path patterns can be specified. The path patterns can be specified using local paths or vault paths, which start with a double slash (//).