hv command reference manual

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 <alice@acme.com>
Never          bob         Bob <bob@acme.com>
...

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 (//).

Commands

Sites

Commands in this section manipulate sites.

A user must be using a site in order for most commands to work correctly.

`site add`

site add [-u USER] SITENAME ROOTDIR [HOST]

Creates a new site.

The specified user will be the owner of the new site. If the user is not specified, the current user will own the site. Only the site owner can use a site.

Only admins can create sites for other users.

To use a site, it must be specified as described in the credentials section.

-u USER

The user (owner) of the new site, must be an existing username. Defaults to the current user. Admins can specify a different user.

SITENAME

The name of the site that will be created, it must be unique (no site can already exist with that name). It must not exceed 64 characters, and it must be composed of alphanumerics or underscore or dash. The first character cannot be a digit or a dash.

ROOTDIR

The absolute path to the directory that will hold the vault files.

HOST

The computer from which the site can be used. It can be specified as an empty string. In this case the server will let the site to be used by any computer. However, since it is a safety feature that prevents from inadvertently using a site from a wrong computer, we do not recommend to specify it as an empty string. When creating a site for the current user, the host defaults to the current computer.

Parameters

Examples:

Create a new site:

alice@alice_PC$ hv site add alicepc /home/alice/vault_site

Ensure that is exists:

alice@alice_PC$ hv sites
Site name User  Host     Last Used  Rootdir
--------- ----- -------- ---------- ------------
alicepc   alice alice_PC Never     /home/alice/vault_site

Remember the new site in the registry:

alice@alice_PC$ hv --set -salicepc
Information has been saved into the registry.

The new site is used in all future commands: