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:
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:
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:
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:
Sync to the last version of a file:
Force sync to the current revision (we must specify -f to force a file transfer):
Display md5 checksums of all revisions of a file:
List Hex-Rays Vault server’s toplevel directory contents:
Plan to add a file to the vault:
Plan to add a directory:
Plan to delete a file:
Show worklist to which files were added:
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 addsite 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:
Ensure that is exists:
Remember the new site in the registry:
The new site is used in all future commands:
site del
site delsite del [-f] SITENAME
Deletes a site.
If -f was passed and the site has some pending worklists, they will be deleted.
This is not a reversible operation, so we recommend caution.
Only admins can delete sites that belong to other users.
-f
Force the deletion even if the site still has worklists.
SITENAME
Name of the site to delete.
Parameters
Example:
Delete the site, forcing deletion of the site’s worklists
site edit
site editsite edit [-u USER] SITENAME ROOTDIR [HOST]
Edits an existing site’s details, such as the rootdir and the host it is bound to.
Admins can reassign a site to a new user or edit sites of other users.
-u USER
The new user (owner) of the site, can only be different than the previous owner if the current user is admin.
SITENAME
The name of the site that will be edited. It must exist and be owned by the current user, unless if the current user is admin.
ROOTDIR
The new absolute path to the directory that will hold the site files.
HOST
The new hostname that will be used for the site. It can be omitted if no changes are desired.
Parameters
Examples:
Change the root directory of a site:
Transfer ownership of site "local_on_shared_machine" to Bob:
sites
sitessites [SITENAME]
Lists all sites.
Show a list of sites, and their associated information.
SITENAME
Name of the site to show.
Parameters
Example:
Site filters
filt get
filt get [-s SITENAME]
Displays the filter table associated with the site.
Only admins can see filter tables of other users.
-s SITENAME
The sitename whose filter table should be displayed. If omitted, defaults to the current site.
Parameters
Examples:
Show the default (i.e., empty) filter table
Set site filters from the standard input:
Verify the new filters:
filt set
filt set [-s SITENAME] [@file]
Sets the filter table associated to the site, either interactively or from @file.
Information about the format of site filters can be retrieved by issuing thecommand.
Only admins can modify filter tables of other users.
-s SITENAME
The sitename whose filter table should be set. If omitted, defaults to current site.
@file
File containing the new table.
Parameters
Examples:
Make everything in the current site hidden, but .bak files
Set site filters, from a file
File manipulation
add
addadd [-s] [-w WORKLIST_ID] PATH_PATTERN…
Adds new file(s) to a worklist.
Issuing this command will not upload the file(s) to the server right away: the new file name(s) will be placed into a worklist, which then needs to be committed to the server. Once a worklist is committed, its files will be available to other users.
The specified file(s) are not required to exist, it is possible to add a file that does not exist yet.
The files must be inside the site’s rootdir.
The files will be filtered using hvignore rules.
-s
Silent mode; do not output any messages.
-w WORKLIST_ID
The id of the worklist that the file(s) will be added to. If omitted, defaults to worklist 1.
PATH_PATTERN…
Local path to file(s) to add to the vault.
Parameters
Examples:
add files to worklist 2
copy
copycopy [-s] [-w WORKLIST_ID] SRC_PATH DST_PATH
Makes a copy of vault file(s).
This command creates a copy of the original file at the requested destination, and place the new file into a worklist. Once the worklist is committed, the new file will be visible to other users.
The source file will be downloaded from the server to the new file. If the source file was modified locally, those modifications won’t be part of the copy. This implies that if a file has just been added to the Hex-Rays Vault server but not committed yet, it can’t be copied because it does not exist on the server yet.
-s
Silent mode; do not output any messages.
-w WORKLIST_ID
The id of the worklist that the files will be added to. If omitted, defaults to worklist 1.
SRC_PATH
The source path.
DST_PATH
The destination path.
Parameters
Examples:
Copy newfile into the rust_samples subdirectory. The worklist #2 will hold the change.
Copy an entire subdirectory (note the trailing slash at the destination):
Copy a subdirectory without recursion:
Copy a file that was just added but not yet committed, it will fail:
move
movemove [-s] [-w WORKLIST_ID] SRC_PATH DST_PATH
Opens tracked file(s) for moving/renaming.
This is similar to performing a, followed by a: the new file will be checked out for copy while the original file will be checked out for deletion.
-s
Silent mode; do not output any messages.
-w WORKLIST_ID
The id of the worklist that the file(s) will be added to. If omitted, defaults to the worklist 1.
SRC_PATH
The source path.
DST_PATH
The destination path.
Parameters
Example:
del
deldel [-s] [-w WORKLIST_ID] PATH_PATTERN…
Opens tracked file(s) for deletion, adding them to a worklist.
Once the worklist is committed, the file(s) won’t be tracked anymore by the Hex-Rays Vault server, and will be removed from the local filesystem.
That this does not remove all revisions of the file on the server: that is the role of thecommand.
-s
Silent mode; do not output any messages.
-w WORKLIST_ID
The id of the worklist that the file(s) will be added to. If omitted, defaults to worklist 1.
PATH_PATTERN…
Vault path of file(s) to delete.
Parameters
Example:
edit
editedit [-s] [-w WORKLIST_ID] PATH_PATTERN…
Opens tracked file(s) for edit, adding them to a worklist.
This command is used to instruct the Hex-Rays Vault server that we will be working on files, so that it knows what revision of the file(s) that work will be based on and so later cmd.diff orcommands can work correctly.
-s
Silent mode; do not output any messages.
-w WORKLIST_ID
The id of the worklist that the file(s) will be added to. If omitted, defaults to worklist 1.
PATH_PATTERN…
Vault path of file(s) to checkout for edit.
Parameters
Example:
scan
scanscan [-a] [-e] [-d] [-s] [PATH_PATTERN…]
Reconciles the contents of the current directory (or the one(s) provided) on the local filesystem, with those of the corresponding path(s) on the server.
This command will recursively look for:
new files (if
-ais provided)deleted files (if
-dis provided)modified files (if
-eis provided)
If any is found will create a new worklist and, add those for addition/deletion/modification.
This command is particularly useful if the user didn’t have access to the server at a time it was necessary (e.g., to issue ancommand, while flying across the Atlantic.) Users can still get work done in such cases, and once they gain access to the server again, issue ato commit the changes.
The -e option causes thecommand to compute checksums of the local files, in order to compare them against those known to the server, in order to spot modifications.
If no options were given, defaults to -e -d.
The files found by the scan command will be filtered by hvignore.
-a
Checkout for add files that are present only on the client side.
-e
Checkout for edit files that are present on both the vault and the client side but differ.
-d
Checkout for delete files that are present only on the server side.
-s
Silent mode; do not output any messages.
PATH_PATTERN…
Local path of file(s) to scan, if omitted defaults to current directory.
Parameters
Example:
Working with worklists
worklists
worklistsworklists [WORKLIST_ID] [USER]
Lists information about worklists.
Show a (possibly filtered) list of pending worklists, and their metadata:
the timestamp of when they were last changed
the number of files they contain
the owner
the site
their description
See also worklist show
WORKLIST_ID
Restrict to the provided worklist, defaults to showing all worklists.
USER
Restrict to user USER, defaults to the current user.
Parameters
Example:
Manipulating a worklist
The following worklist commands will also work with the shorter wk alias.
worklist add
worklist add DESCRIPTION
Creates a new worklist, with the provided description.
The worklist will initially be empty, and assigned a free ID.
Files can be associated to that new worklist when they are marked for addition, deletion, or edition.
DESCRIPTION
The description of the new worklist.
Parameters
Example:
worklist show
worklist show [-s SITE] [-u USER] [WORKLIST_ID]
Lists worklist contents.
Show a list of files opened for editing, addition or deletion, and their associated worklist(s).
-s SITE
Restrict to site SITE. If omitted, defaults to the current site.
-u USER
Restrict to user USER. If omitted, defaults to the current user.
WORKLIST_ID
Restrict to the provided worklist, defaults to showing all worklists.
Parameters
Examples:
Show the worklist contents of another user
worklist edit
worklist edit WORKLIST_ID DESCRIPTION
Edits a worklist description.
WORKLIST_ID
The worklist to modify.
DESCRIPTION
The new description for the worklist.
Parameters
Example:
change description of worklist 4
worklist del
worklist del WORKLIST_ID
Deletes a worklist.
This command will only succeed if the worklist is currently empty.
WORKLIST_ID
The worklist to delete.
Parameters
Example:
Committing a worklist to the server
commit
commit [-f] [-s] WORKLIST_ID [DESCRIPTION]
Commits files to the vault (push).
This command uploads files from the local computer to the vault.
After a successful commit, the modifications made to the files contained in the worklist will be made available for other users.
A commit may fail if another user uploaded another revision of the changed files meanwhile. In this caseis necessary to merge the changes.
If the worklist does not yet have a proper description, the DESCRIPTION is mandatory.
-f
Force commit of unchanged files.
-s
Silent mode; do not output any messages.
WORKLIST_ID
The id of the worklist to commit to the vault.
DESCRIPTION
A description for the commit.
Parameters
Example:
Syncing files, resolving & reverting
sync
sync [-f] [-p] [-s] [@COMMIT_ID] [PATH_PATTERN[=REVISION]…]
Downloads the requested revisions of the files from the server, and stores them on the local filesystem.
If no paths are provided, all files from the server will be retrieved.
Requires that a site to be currently selected.
-f
Force sync. This will force a download of the files, even when the server thinks the client has the desired revision. This is a dangerous operation: any modification made to local files will be lost.
-p
The server will perform sync without really transferring files. This options is useful if the local files are already in sync but the server has stale info about them.
-s
Silent mode; do not output any messages.
@COMMIT_ID
Sync to state right after COMMIT_ID was committed, cannot be used with =REVISION.
PATH_PATTERN[=REVISION]…
Vault path of file(s) to sync, if path is omitted, defaults to current directory, if no revision is specified, defaults to last revision available on vault (#^).
Parameters
Examples:
Sync all
Sync only the specified subtree
Sync a file to specific revision
resolve
resolve METHOD PATH_PATTERN
Resolves conflicts in a file, using the specified strategy.
After the strategy is successfully applied and the local file has incorporated both the "local" and "remote" changes, it will be ready to be committed.
METHOD
One of "auto", "lmerge", "rmerge", "manual", "local" or "remote".
PATH_PATTERN
Vault path of file(s) to resolve.
Parameters
Example:
revert
revert [-a] [-p] [-s] PATH_PATTERN…
Reverts opened files to their current revisions.
-a
Revert only unchanged files.
-p
The server will revert the files without transferring files.
-s
Silent mode; do not output any messages. This options is useful if the local files are already in sync but the server has stale info about them.
PATH_PATTERN…
Vault path of file(s) to revert.
Parameters
Example:
migrate
migrate [-s] PATH_PATTERN… WORKLIST_ID
Moves opened files between worklists.
-s
Silent Mode; do not output any messages.
PATH_PATTERN…
Vault path of file(s) to move.
WORKLIST_ID
The id of the worklist to move the files to, the worklist must already exist.
Parameters
Example:
Various information
files
filesfiles [-d] [-s] [PATH_PATTERN_OR_SUBSTRING[=REVISION]…]
Displays the list of the files present in the vault.
The command will collect files from the vault (that match the selection) and display for each file:
the file path
the revision
the file size if it hasn’t been deleted
the last commit id
the last action
-d
Include deleted files.
-s
Search for substring instead of using a path.
PATH_PATTERN_OR_SUBSTRING[=REVISION]…
Vault path of file(s) to include in search or substring to search for if -s. If revision is not specified, defaults to current revision (#=). If no path is specified, defaults to the root directory of the vault.
Parameters
Examples:
dir
dirdir [-d] [-s] [-u] PATH_PATTERN_OR_SUBSTRING…
Displays vault directory listing (current revisions).
For each file entry the command will display:
the timestamp of when the file was committed
the file size
the commit id
the type of action that was executed on the file in the commit
the path
the current revision on disk
an extra label if the file is unsynced
Directories will be displayed as: <subdir> PATH
-d
Include deleted files.
-s
Path patterns are simple substrings.
-u
Include unsynced files.
PATH_PATTERN_OR_SUBSTRING…
Vault path of file(s) to include in search or substring to search for if -s.
Parameters
Examples:
show
showWrites the contents of a file on the vault to the command line.
PATH_PATTERN[=REVISION]
Vault path to file(s) to display. If no revision is specified, defaults to current revision (#=). If the file revision denotes a deleted revision of the file, the contents will not be displayed.
Parameters
Example:
diff
diffdiff PATH[=REVISION] PATH_OR_REV[=REVISION]
Compares two databases, will launch IDA in diff mode.
Only IDA databases (.i64, .idb) can be diffed with this command. If revisions of databases requested for comparison are currently not in the site, they will be downloaded to a temporary directory and will be deleted when IDA exits. On unix the temporary directory can be specified with $TMPDIR.
PATH[=REVISION]
Database 1.
PATH_OR_REV[=REVISION]
Database 2. If no path is specified, it will default to the path of Database 1. If no revision is specified, it will default to the current revision (#=).
Parameters
Examples:
with interfaces.i64 opened for edit and changed, this will open IDA and show the differences with the current revision on vault
md5
md5Prints the md5 checksum of a file on the vault.
PATH_PATTERN[=REVISION]
Vault path of file(s) to process, if no revision is specified, defaults to the current revision (#=).
Parameters
Example:
info
infoinfo
Displays info about the vault and current session.
Example:
changes
changeschanges [-s SITENAME] [-u USERNAME] [-c MIN_COMMIT] [-C MAX_COMMIT] [-m MAX_REPORTED_ENTRIES] [-d MIN_DATE] [-D MAX_DATE] [-l] [PATH_PATTERN…]
Displays list of commits that affect a path.
List can be refined using options.
For each commit the following info will be displayed:
the commit id
the timestamp of the commit
if only one file was changed, the action that was done to it (e.g.
edit)the user who sent the commit
the site from which the commit was sent
a description of the commit, truncated to 40 chars unless if
-lis enabled
TIP
This command is also available under the alias commits.
-s SITENAME
Restrict to commits from SITENAME.
-u USERNAME
Restrict to commits from USERNAME.
-c MIN_COMMIT
Restrict to commits after commit: MIN_COMMIT.
-C MAX_COMMIT
Restrict to commits prior to commit: MAX_COMMIT.
-m MAX_REPORTED_ENTRIES
Limit number of reported commits to: MAX_REPORTED_ENTRIES.
-d MIN_DATE
Restrict to commits after MIN_DATE using format YYYY-MM-DD.
-D MAX_DATE
Restrict to commits prior to MAX_DATE using format YYYY-MM-DD.
-l
Display long (>40 characters) commit descriptions.
PATH_PATTERN…
Filter commits by vault paths. If omitted, defaults to all files.
Parameters
Examples:
find all commits made by john
show last 2 commits on a file with full descriptions
users
usersusers
Shows users.
Example:
groups
groupsgroups
Displays all the existing groups and their users.
Example:
group show
group showgroup show GROUP_NAME
Displays the list of users in a group.
GROUP_NAME
A group name.
Parameters
Example:
user show
user showuser show USERNAME
Displays the full details of a specific user.
The following details will be displayed:
the timestamp of when the user was last active
the username, with a
*next to it if the user has admin privilegesthe license id of the user
the full name of the user
the email address of the user
notes about the user
USERNAME
The username of the user to display.
Parameters
Example:
commit show
commit showcommit show COMMIT_ID
Displays the contents of a commit.
This will list all of the files that were changed by the commit.
For each file the following details will be displayed:
the action that was performed on it in the commit
the path
the revision
if it’s unsynced, an extra label will be displayed
the size of the file
COMMIT_ID
The id of the commit to display.
Parameters
Example:
Misc.
passwd
passwdpasswd PASS [USER]
Sets a new password for a user.
PASS
The new password.
USER
The username whose password should be changed. Only admins can change other users' passwords. If omitted, defaults to the current user.
Parameters
Examples:
commit edit
commit editcommit edit COMMIT_ID DESCRIPTION
Edits a commit description.
Regular users may modify only their own commits. Admins may modify any commit.
COMMIT_ID
The id of the commit to amend.
DESCRIPTION
New description of the commit.
Parameters
Example:
licenses
licenseslicenses
Shows active licenses
Example:
borrow
borrowborrow PRODUCT END_DATE
Borrow a license
A borrowed license can be used offline but other users will not have access to it.
A borrowed license can be returned to the vault using. If not returned earlier, it will automatically be returned to the vault at the expiration time.
PRODUCT
The product code or license id.
END_DATE
YYYY-MM-DD - exact date, +Nd - N days since now, +Nw - N weeks since now. DD-MON-YYYY can be used to specify an exact date too.
Parameters
Example:
return
returnreturn PRODUCT
Return a borrowed license
A returned license becomes available to other vault users.
PRODUCT
The product code or license id.
Parameters
Example:
Administrative commands
These commands require that the user executing them has admin privileges.
Managing users
user add
user add USERNAME REALNAME EMAIL IS_ADMIN NOTES
Adds a user.
USERNAME
The username of the user.
REALNAME
The full name of the user.
EMAIL
The email address of the user.
IS_ADMIN
Should be 1 if the user is admin, otherwise 0.
NOTES
Extra notes about the user.
Parameters
Example:
user edit
user edit USERNAME REALNAME EMAIL IS_ADMIN NOTES
Edits a user definition.
USERNAME
The username of the user to modify.
REALNAME
The full name of the user.
EMAIL
The email address of the user.
IS_ADMIN
Should be 1 if the user is admin, otherwise 0.
NOTES
Extra notes about the user.
Parameters
Example:
user del
user del [-b] [-f] USERNAME
Deletes a user.
Cuation: deleting a user with borrowed licenses will make the borrowed licenses unavailable until their expiration date.
-b
Force deletion even if the user has borrowed licenses.
-f
Force deletion even if the user has checked out files.
USERNAME
The name of the user to delete from the vault.
Parameters
Example:
Managing groups
group add
group add GROUP_NAME
Adds a new group.
An empty group with the specified name is created.
GROUP_NAME
the name of the new group.
Parameters
Example:
group edit
group edit GROUP_NAME USER ADD_OR_DELETE
Edits a group by adding or deleting users.
GROUP_NAME
the name of the group.
USER
the name of the user.
ADD_OR_DELETE
add or delete the specified user from the group, 0 is delete, 1 is add.
Parameters
Example:
group del
group del GROUP_NAME
Deletes a group.
GROUP_NAME
the name of the group to delete.
Parameters
Example:
Managing permissions
perm get
perm get
Displays permission table.
The current permission table is printed to the standard output.
Example:
perm set
perm set [@FILE]
Sets new permissions table from STDIN or from file.
The installed permission table becomes active immediately.
We recommend usingto ensure that the new permission table works correctly.
@FILE
The file from which to set the new permissions table.
Parameters
Example:
perm check
perm check USERNAME PATH_PATTERN
Checks permissions for a user.
The list of files that are visible to the user is printed, along with the permissions that the user has. The read access is denoted by 'r' and the write access is denoted by 'w'.
USERNAME
The USERNAME of the user whose permissions that will be tested.
PATH_PATTERN
Vault path of file(s) that will be tested.
Parameters
Example:
Others
sessions
sessions
Displays the sessions info.
For each session on the vault, the following info will be displayed:
the site
the user
the hostname
the timestamp of the login time
the timestamp of the last activity
"ADM" if the user has admin privileges
"*" for the session executing the command
Example:
purge
purge [-s] [-y] PATH_PATTERN…
Purges file(s) from the Vault server, permanently deleting it and all of its history.
The path patterns must be specified using full paths, starting with //
-s
Silent mode; do not output any messages.
-y
Really purge the files, without this parameter the command does a dry-run.
PATH_PATTERN…
Vault path of file(s) to purge from the vault.
Parameters
Example:
Concepts
What is a "site"?
A site represents a mapping of the server files to the local filesystem. Normally each computer has a site associated with it. A site has the following attributes:
A site name
A host name
The path to a folder on the filesystem (a.k.a., "root directory")
Path filters (optional)
Root directory
The root directory is the essential attribute of a site. It denotes where all files from the vault server will be mapped to the local disk. Everything inside the root directory can potentially be uploaded to the vault server and shared with other team members.
The vault server cannot manage files located outside the root directory. However, this limitation is straightforward to overcome: create a symbolic link (or, on Windows, a junction point) from the root directory to the directory of your choice. This will make the target of the symbolic link visible as part of the root directory.
The vault server keeps track of each site’s state: what files have been downloaded to the local disk, what files have been checked out for editing, etc. This simplifies the housekeeping tasks, especially for big repositories with millions of files. Even for them, downloading the latest files or reconciling the local disk with the server, are almost instantaneous.
The host name is a security feature that prevents from using a site on a wrong computer. Since the server keeps track of the files downloaded to each site, using a wrong site may lead to an inconsistent mapping between the server and local disk. However, if the user does not want this protection, it is possible to erase the host name in the site definition.
Sites can be edited from the "Sites" view.
Path filters
By default all server files are visible, but for servers that manage gigabytes of data this can be problematic: it may be undesirable for users to download all files to their local computer.
Site filters provide a mechanism that lets users restrict the set of files their IDA Teams client works with. Users who want to work on some specific projects can set a filter that restricts the visibility only to selected subdirectories.
Each site has its own filters, that con be modified at any time. Filters do not directly affect any files on the local disk, or on the server: they are strictly about visibility.
Site filters are meant simplify a user’s life by letting them focus on specific projects. Since they can be modified by users, they should not be considered a security measure: that would be the role of the permissions system, which can only be managed by Hex-Rays Vault server administrators.
The purpose of site filters is to create a subset of the full set of files provided by the server. Site filters don’t directly affect what locally-available files (i.e., present in the site’s rootdir, but not tracked by the server) are visible by IDA Teams clients.
There is another mechanism to specify what files should not be added to the vault. See .hvignore for more info.
Examples
An empty filter
Hide all files, except those in malware/
Show all files, except those from the pentesting team
Show all files but those from the pentesting team, except their produced documents
Resolving conflicts in a file
When a user needs to commit changes made to a file, but that same file has received other modifications (likely from other users) in the meantime, it is necessary to first "merge" the two sets of modifications together.
When the two sets of modifications do not overlap, merging is trivial - at least conceptually. But when they do overlap, they produce conflict(s).
Since IDA Teams focuses on collaboration over IDA database files, the rest of this section will focus on the different strategies that are available for resolving conflicts among those.
IDA Teams comes with multiple strategies to help in conflict resolution of IDA database files:
Auto-resolve (if no conflicts)
Launch IDA in a non-interactive batch mode, attempting to perform all merging automatically.
If any conflict is discovered, bail out of the merge process, and don’t modify the local database.
Auto-resolve, prefer local
Launch IDA in a non-interactive batch mode, attempting to perform all merging automatically.
If a conflict is discovered, assume that the "local" change (i.e., the current user’s change) is the correct one, and apply that.
Once all merging is done and conflicts are resolved, write those to the local database and exit IDA
Auto-resolve, prefer remote
Launch IDA in a non-interactive batch mode, attempting to perform all merging automatically.
If a conflict is discovered, assume that the "remote" change (i.e., the change made by another user) is the correct one, and apply that.
Once all merging is done and conflicts are resolved, write those to the local database and exit IDA
Interactive merge mode
Manual merge mode.
This will launch IDA in an interactive, 3-pane mode, allowing the user to decide how to resolve each conflict.
Once all merging is done and conflicts are resolved, exit IDA and write the changes to the local database.
Use local, discard remote
Select the local database, ignoring all changes in the remote database.
No IDA process is run.
Use remote, discard local
Select the remote database, ignoring all changes in the local database.
No IDA process is run.
hvignore (and .hvignore) files
hvignore (and .hvignore) filesIDA Teams comes with a mechanism that lets users specify what files should be ignored when adding files from their local machines to the Vault.
The main hvignore file (path/to/install-dir/hvignore)
hvignore file (path/to/install-dir/hvignore)In IDA Teams' install directory, you will find the "main" hvignore file, that is pre-populated with a list of files that you would typically not want to add to the Hex-Rays Vault server, such as .bak backup files and unpacked IDA database files: .id0, .nam, etc…
The syntax for hvignore is very close to that of .gitignore files.
Additional .hvignore files
.hvignore filesIn addition to that file, you can have .hvignore file (notice the . - dot) placed in your site's directory structure.
When found, those files' contents will be appended to the main file’s contents.
The registry
On Microsoft Windows, IDA Teams will store certain bits of information in the registry (host name, user name, site name.)
On macOS and Linux, it will use a pseudo-registry file, located at $HOME/.idapro/hvui.reg.
Passwords storage in the OS’s keychain
While hosts, user names & site names are persisted to the registry, passwords are stored securely in the operating system’s keychain.
On Windows, the Windows Credential Store is used (therefore requiring Windows 7 or newer)
On macOS, the macOS Keychain is used
On Linux, the "Secret service" is used (through
libsecret-1)
Managing permissions on a vault
Hex-Rays Vault includes a way to restrict the access of users and groups to the data stored in the Vault.
The permission file is a text file that contains the permission table. The file consists of lines that grant or deny access to certain path patterns in the vault. The syntax for an entry is the following:
grant/deny group/user NAME PERMISSION VAULT_PATH_PATTERN
Possible PERMISSION values are: list, read and write. read includes list, write includes read (and thus also includes list).
Example of a permission file:
An empty permission table means that no permissions are enforced rendering all files accessible by everyone. As soon as a non-empty permission table is specified, all access is denied to everyone by default.
Path patterns may refer to (yet) unexisting files. Users and groups too may refer to unexisting users and groups.
The order of the permission file is important as the last lines will take precedence over the preceding lines (if there are conflicts).
Admins are not affected by the permission table, they are granted all access.
To install a new permission table, use perm set
The current permissions can be retrieved using perm get
Last updated
