IDA Teams uses a subscription-based licensing model, allowing users to pay an annual fee per seat. It uses a server that keeps track of all work done by the team.
After your purchase of IDA Teams licenses, you will receive an e-mail that contains a link to a download area, where you will find, among other things:
an installer for the IDA Teams server (also called the "Hex-Rays Vault server")
an administration guide for the IDA Teams server
Please follow the instructions in the administration guide to install the server.
IDA Teams can be used either online (i.e., with a connection to its server), or offline (e.g., if you have to travel.)
To enable this mechanism, it is possible to "borrow" a license for a certain amount of time, through IDA's "Help" menu.
IDA 8.0 introduces IDA Teams - a mechanism that provides revision control for your IDA database files. Perhaps the most essential feature of this new product is the ability to natively diff and merge databases using IDA, allowing multiple reverse engineers to manage work on the same IDA database.
This document discusses in detail the steps involved when diffing and merging IDA databases.
Before continuing, you might want to take a quick look at the tutorial for HVUI, the GUI client for IDA Teams' revision control functionality. It will be referenced multiple times in this document, although here we will focus specifically on the merging functionality.
After having done some reverse-engineering work on an IDA database, it is possible to view those changes in a special mode in IDA: right-click, and choose the diff action:
Here a new instance of IDA will be launched in a special "diff" mode:
This new IDA mode lets the user compare two databases, in a traditional "diff" fashion: essentially a two-panel window, showing the unmodified file on the left and the version with your changes on the right.
Shows the "untouched" version of the database (i.e., the one without your changes)
Shows your version of the database (i.e., featuring your changes)
Notice how both panels have a little area at the bottom, that is labeled "Details".
Details are available on certain steps of the diffing process, and provide additional information about the change that is currently displayed.
The actions in the toolbar are:
Using actions in the toolbar, you can now iterate through the differences between the two databases, with each change shown in context as if viewed through a normal IDA window.
The ability to view changes in context was a major factor in the decision to use IDA itself as the diffing/merging tool for IDA Teams.
Move to the previous change
Re-center the panels to show the current chunk (useful if you navigated around to get more context)
Move to the next change
Toggle the visibility of the "Details" widgets in the various panels (note that some steps do not provide details, so even if the "Details" are requested, they might not be currently visible.)
It is important to note the difference between the terms "diff" and "merge".
This document will sometimes use the two terms interchangeably. This is because to IDA, a diff is just a specialized merge. Both diffing and merging are handled by IDA’s "merge mode", which involves up to 3 databases, one of which can be modified to contain the result of the merge.
A diff is simply a merge operation that involves only 2 databases, neither of which are modified.
This is why often times you will see the term "merge" used in the context of a diff. In this case "merge" is referring to IDA’s "merge mode", rather than the process of merging multiple databases together into a combined database.
We must stress the fact that performing a merge between two IDA databases is quite different than performing a merge between, say, two text files. A change in a chunk of text file will not have an impact over another chunk.
IDA databases are not so simple. A change in one place in an idb will often have an impact on another place. For example, if a structure mystruct changed between two databases, it will have an impact not only on the name of the structure, but on cross-references to structure members, function prototypes, etc.
This is why IDA’s merge mode is split into a strict series of "steps":
Within a single step it is possible to go forward & backward between different chunks. But because of possible inter-dependencies between steps, it is not possible to move backwards between steps, you can only go forward:
Since IDA’s diff mode is just a variation of its merge mode, diffing databases is also subject to this sequential application of steps in order to view certain bits of information. That is why, in some steps (e.g., the "Disassembly/Items") IDA might not report some changes that were performed at another level.
For instance, if a user marked a function as noret, the listings that will be shown in "Disassembly/Items" step, will not advertise that there was a change at that place (even though the "Attributes: noreturn" is visible in the left-hand listing), only the changes to the instructions (and data, …) are visible in the current step:
The change will, however, be visible at a later step (i.e., "Functions/Registry"):
The changes applied during the "diff" process are only temporary. Exiting IDA (at any moment) will not alter the files being compared.
As with any collaborative tool, it may happen that two coworkers work on the same dataset (e.g., IDA database), and make modifications to the same areas, resulting in "conflicts". Conflicts must be "resolved" prior to committing.
To do that, right-click and pick one of the "resolve" options:
When a conflict is encountered, you’ll have the ability to pick, for all conflicts, which change should be kept (yours, or the other). Every time you pick a change (and thus resolve a conflict), IDA will proceed with the merging, applying all the non-conflicting changes it can, until the next conflict - if any. When all conflicts are resolved, you can leave IDA, and the new resulting file is ready to be submitted.
This section provides a detailed overview of the steps involved in the merge process. The list of predefined merge steps is defined in merge.hpp of the IDASDK:
The list of merge steps is not final. If for example there is a conflict in structure members then the new merge phase to resolve this conflict will be created. The same is hold for UDT, functions, frames and so on. In other words in general case the exact number of merge steps is undefined and depends on the databases.
Each item in a merge step is assigned to a difference position named diffpos. It may be an EA (effective address), enum id, structure member offset, artificial index and so on. In other words, a diffpos is a way of addressing something in the database.
Every merge step starts with the calculation of differences and conflicts between items at the corresponding difference positions. As the result there is a list of diffpos with differences or conflicts. The diffpos`s without differences are not included in the list. Adjacent `diffpos`s are combined into a difference range called `diffrange.
The merging process operates on a difference range diffrange. For one diffrange, a single merge policy can be selected.
Merging of global database attributes. These attributes are mainly stored in the idainfo structure. This phase has two subphases:
Global settings/Database attributes/Graph mode
Global settings/Database attributes/Text mode
The "Detail" pane is absent.
Merging of global processor options. Usually these options are stored in the idpflags netnode.
The "Detail" pane is absent.
Merging of registered string literal encodings. These encodings are used to properly display string literal in the disassembly listing.
The "Detail" pane is absent.
Merging of default string encodings: what string encoding among the registered ones are considered as the default ones.
The "Detail" pane is absent.
Merging of embedded script snippets.
When merging of embedded script snippets, the script name/language is displayed, and the "Detail" pane contains the script source with the highlighted differences:
Merging of the default snippet and tabulation size.
The "Detail" pane is absent.
Merging of the registered custom data types and formats.
The "Detail" pane is absent.
Merging of assembler level enums (enum_t). Ghost enums are skipped in this phase, they will be merged when handling local types.
To calculate diffpos, IDA Teams matches enum members by name and maps all enums with common member names into one diffpos.
An example of enum merging:
In both idbs, enum constant "B" is present. However, in the remote idb "B" has a different parent enum, "enum_2". Therefore enum_1 in the local idb corresponds to enum_1 and enum_2 in the remote idb. The user can select either enum_1 from the local idb or enum_1 and enum_2 from the remote idb.
In other words, IDA will display both enum_1 and enum_2 in the Remote pane, indicating that the difference between the Local and Remote databases corresponds to two separate enums, but they are treated as a single difference location. The "Detail" pane will display the full enum definitions, with the differences highlighted:
Merging of assembler level structures (struc_t).
To calculate diffpos, IDA Teams matches structs by the following attributes, in this order:
the structure name
the structure tid and size
If we fail to match a structure, then it will stay unmatched. Such an unmatched structure will have it own diffpos, allowing the user to copy it to the other idb or to delete it altogether.
This merge phase deals with the entire structure types and their attributes. Entire structure types may be added or deleted, and/or conflicts in the structure attributes are resolved.
If members of matched structures (at the same diffpos) differ, the conflict will be resolved later, during the Types/Struct members/… merge phase.
In the UI, IDA will display the list of structure names, with the "Detail" pane showing the structure attributes:
Merging of the loaded type libraries.
This merge phase uses the standard "Type libraries" widget.
The "Detail" pane is absent.
Merging of local types.
To calculate diffpos, IDA Teams matches local types by the following attributes, in this order:
the type name
the ordinal number and base type
If we fail to match a type, then it will stay unmatched. Such an unmatched type will have it own diffpos, allowing the user to copy it to the other idb or to delete it altogether.
This merge phase deals with entire types and their attributes. Entire local types may be added or deleted, and/or conflicts in their attributes are resolved. Differences in type members (e.g., struct members) will be resolved in a separate phase: Types/Local type members
This merge phase uses the standard "Local types" widget. The "Detail" pane displays the type definition and its attributes.
For example:
Types/Struct members/struct_t
Types/Local type members/struct conflict_t
These merge phases merges the conflicting members of a structure or a local type.
The "Detail" pane displays full information about the current member along with its attributes.
Ghost structs may have comments attached to them.
This merge phase handles these comments:
We need a separate phase for these comments in order not to lose them during merging because by default ghost types are considered secondary to the corresponding non-ghost type. Normally during merge ghost types may be overwritten. However, local types cannot have comments at all. This is why ghost structure comments, if created, are valuable.
Similarly to comments attached to entire structures, each structure member may have a comment.
The same logic applies to ghost struct member comments:
Merging of selectors.
This merge phase uses the standard widget "Selectors".
The "Detail" pane is absent.
IDA Pro allocates so-called flags for each program address. These flags describe how to display the corresponding bytes in the disassembly listing: as instruction or data.
There are two different storage methods for flags: virtual array (VA) and sparse storage (MM). The virtual array method is the default one, it allocates 32 bits for each program address. However, for huge segments this method is not efficient and may lead to unnecessarily huge databases. Therefore for huge segments IDA Pro uses sparse storage.
This merge phase handles the defined program ranges and their storage types.
The "Detail" pane is absent.
This merge phase handles the program segmentation.
When merging segments, IDA combines them into non-overlapping groups. Each group will have its own diffpos. For example, the following segmentations:
will result in a single diffpos:
The "Detail" pane displays segments in the combined group with their attributes.
When merging segment, IDA tries to move the segment boundaries in a way that preserves the segment contents. If it fails to do so, the conflicting segments are deleted and new ones are created.
Merging of segment groups. Segment groups are used only in OMF files. They correspond to the group keyword in assembler.
The "Detail" pane is absent.
Some processor have so-called segment registers. IDA Pro knows about them and can remember their value (one value per address range).
For example, the x86 processor has ds, ss, and many other registers. IDA Pro can remember that, say, ds has the value of 1000 at the range 401000..402000.
This merge phase handles segment registers. For each register, a separate merge phase is created. It contains address ranges: inside each address range the value of the segment register stays the same.
To prepare diffpos, IDA Teams combines segment register ranges into non-overlapping ranges. diffpos is a range number.
The "Detail" pane displays segment register ranges in diffpos with the value and the suffix that denotes the range type (u-user defined, a-automatically inherited from the previous range)
The database may have bytes that do not belong to any segment.
To prepare diffpos, IDA Teams groups orphan bytes in the databases into nonintersecting ranges. diffpos is a range number.
The "Detail" pane is absent.
Merging of the patched bytes.
The "Detail" pane is absent.
Byte values in segments may differ even for non-patched addresses, for example if a snapshot of the process memory was taken during a debugger session.
IDA Teams combines the sequential bytes in one diffpos.
This merge phase uses the standard "IDA-View" widget.
The "Detail" pane displays the conflicting byte values.
Merging of fixup records.
The "Detail" pane is absent.
Merging of memory mappings.
The "Detail" pane is absent.
Merging of exported symbols.
Merge phase uses the standard "Exports" widget.
The "Detail" pane is absent.
Merging of imported symbols.
Merge phase uses the standard "Imports" widget.
The "Detail" pane is absent.
When merging, IDA Teams compares disassembly items (instructions and data). IDA Teams compares disassembly items by length, flags, opinfo, name, comment, and netnode information (NALT_* and NSUP_* flags).
This merge step uses the standard "IDA-View" widget so that items can be viewed in their context. For example:
Merging of extra comments.
This merge phase uses the standard "IDA-View" widget.
The "Detail" pane displays comment content.
Merging of additional flags aflags_t.
Each disassembly item may have additional flags that further describe it.
This merge phase uses the standard "IDA-View" widget.
The "Detail" pane displays additional flags.
To prepare diffpos, IDA Teams groups hidden ranges into nonintersecting ranges. diffpos is a range number.
The "Detail" pane displays the hidden range description.
To prepare diffpos, IDA Teams groups source file ranges into nonintersecting ranges. diffpos is a range number.
The "Detail" pane displays source file definition.
Function definitions (func_t) are merged using the standard "Functions" widget, while the "Detail" pane displays function attributes:
Merging of instruction kinds.
To simplify decompilation, IDA has the notion of the instruction kind:
PROLOG instruction
EPILOG instruction
SWITCH instruction
This merge phase uses the standard "IDA-View" widget.
The "Detail" pane displays instruction kind.
This merge phase deals with the entire function frames. Function frame may be added or deleted.
If members of the matched function frame differ, the conflict will be resolved later during the Functions/Frame/… merge phase. Each differing frame will be assigned its own merge step.
The "Detail" pane is absent.
Merging of function frame details.
A separate phase is created for each function. For example:
Functions/Frames/sub_401200 at 401200
Functions/Frames/_main at 4014E0
Every of these phases merges the conflicting members of the function frame.
The "Detail" pane displays the detailed information about the current function frame member.
Merging of function SP change points.
This merge phase uses the standard "IDA-View" widget.
The "Detail" pane displays the SP change point details.
Merging of regular execution flow from the previous instruction. IDA stores cross-references that correspond to regular execution flow in a special format, different from other cross-reference types.
This merge phase uses the standard "IDA-View" widget.
The "Detail" pane is absent.
Merging of code cross-references.
This merge phase uses the standard "IDA-View" widget.
The "Detail" pane displays code references to address (diffpos).
Merging of data cross-references.
This merge phase uses the standard "IDA-View" widget.
The "Detail" pane displays data references to address (diffpos).
The following merge phases exist:
Marked positions/structplace_t
Marked positions/enumplace_t
Marked position/idaplace_t
They deal with merging of bookmarks for:
structures
enums
addresses
The "Detail" pane is absent.
The following merge phases exist:
Breakpoints/Absolute bpts
Breakpoints/Relative bpts
Breakpoints/Symbolic bpts
Breakpoints/Source level bpts
They deal with merging of various debugger breakpoints.
The "Detail" pane is absent.
Merging of watch points.
The "Detail" pane is absent.
The following merge phases exist:
Dirtree/$ dirtree/tinfos
Dirtree/$ dirtree/structs
Dirtree/$ dirtree/enums
Dirtree/$ dirtree/funcs
Dirtree/$ dirtree/names
Dirtree/$ dirtree/imports
Dirtree/$ dirtree/bookmarks_idaplace_t
Dirtree/$ dirtree/bookmarks_structplace_t
Dirtree/$ dirtree/bookmarks_enumplace_t
Dirtree/$ dirtree/bpts
They deal with merging of the standard dirtrees.
The "Detail" pane is absent.
Merging of try and catch block info.
The "Detail" pane describes try block.
Merging of virtual function tables.
The "Detail" pane is absent.
Merging of database notepads. Each line of text is a diffpos.
The "Detail" pane is absent.
Each processor plugin creates its own merge steps to handle the processor plugin’s specific data.
For example, the PC processor module adds the following merge steps:
Processor specific/Analyze ea for a possible offset
Processor specific/Frame pointer info
Processor specific/Pushinfo
Processor specific/VXD info 2
Processor specific/Callee EA|AH value
…
Merging of the decompiler data starts with the global configuration parameters from hexrays.cfg:
To handle decompilation of specific functions, IDA stores the decompilation data in a database netnode named Hexrays node.
The merge step Plugins/Decompiler/Hexrays nodes adds or deletes netnodes, indicating which functions have or haven’t been decompiled in each databases:
The decompilation data for matching functions is compared using the following attributes:
Plugins/Decompiler/…/Numforms
Plugins/Decompiler/…/mflags
Plugins/Decompiler/…/User-defined funcargs
Plugins/Decompiler/…/User-defined variable mapping
Plugins/Decompiler/…/User-defined lvar info
Plugins/Decompiler/…/lvar settings
Plugins/Decompiler/…/IFLAGS
Plugins/Decompiler/…/User labels
Plugins/Decompiler/…/User unions
Plugins/Decompiler/…/User comments
Plugins/Decompiler/…/User-defined call
If there is a difference, each comparison criteria will be assigned its own merge step. Each step will use the standard "Pseudocode" widget so that differences can be viewed in-context with the full pseudocode:
The file loader that was used to create the database may have stored some data in the database that is specific to the loader itself.
There are merge phases for each loader, for example:
Loader/PE file/…
Loader/NE file/…
Loader/ELF file/…
Loader/TLS/…
Loader/ARM segment flags/…
To handle the differences in debugger data the following merge steps may be created:
Debugger/pin
Debugger/gdb
Debugger/xnu
Debugger/ios
Debugger/bochs
Debugger/windbg
Debugger/rmac_arm
Debugger/lmac_arm
Debugger/rmac
Debugger/lmac
As can be deduced by their names, they handle debugger-specific data in the database.
There are a number of IDA plugins that need to merge their data.
For example:
Plugins/PDB
Plugins/golang
Plugins/EH_PARSE
Plugins/Callgraph
Plugins/swift
Any third party plugin may add merge phases using the IDA SDK. We provide sample plugins that illustrate how to add support for merging into third party plugins.
Any plugin that stores its data in the database must implement the logic for merging its data. For that, the plugin must provide the description of its data and ask the kernel to create merge handlers based on these descriptions.
The kernel will use the created handlers to perform merging and to display merged data to the users. The plugin can implement callback functions to modify some aspects of merging, if necessary.
The plugin may have two kinds of data with permanent storage:
Data that applies to entire database (e.g. the options). To describe this data, the idbattr_info_t type is used.
Data that is tied to a particular address. To describe this data, the merge_node_info_t type is used.
The kernel will notify the plugin using the processor_t::ev_create_merge_handlers event. On receiving it, the plugin should create the merge handlers, usually by calling the create_merge_handlers() function.
The IDA SDK provides several sample plugins to demonstrate how to add merge functionality to third party plugins:
mex1/
mex2/
mex3/
mex4/
The sample plugin without the merge functionality consists of two files:
mex.hpp
mex_impl.cpp
It is a regular implementation of a plugin that stores some data in the database. Please check the source files for more info.
We demonstrate several approaches to add the merge functionality. They are implemented in different directories mex1/, mex2/, and so on.
The MEX_N macros that are defined in makefile are used to parameterize the plugin implementation, so that all plugin examples may be used simultaneously.
You may check the merge results for the plugins in one session of IDA Teams. Naturally, you should prepare databases by running plugins before launching of IDA Teams session.
The merge functionality is implemented in the merge.cpp file. It contains create_merge_handlers(), which is responsible for the creation of the merge handlers.
Variants:
mex1/ Merge values are stored in netnodes. The kernel will read the values directly from netnodes, merge them, and write back. No further actions are required from the plugin. If the data is stored in a simple way using altvals or supvals, this simple approach is recommended.
mex2/ Merge values are stored in variables (in the memory). For more complex data that is not stored in a simple way in netnodes, (for example, data that uses database blobs), the previous approach cannot be used. This example shows how to merge the data that is stored in variables, like fields of the plugin context structure. The plugin provides the field descriptions to the kernel, which will use them to merge the data in the memory. After merging, the plugin must save the merged data to the database.
mex3/ Uses mex1 example and illustrates how to improve the UI look.
mex4/ Merge data that is stored in a netnode blob. Usually blob data is displayed as a sequence of hexadecimal digits in a merge chooser column. We show how to display blob contents in detail pane.
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:
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.
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
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
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.
Select the local database, ignoring all changes in the remote database.
No IDA process is run.
Select the remote database, ignoring all changes in the local database.
No IDA process is run.
Represents the current in the diff process.
Move to the next in the diffing process.
IDA Teams provides
If the option that was chosen (e.g., ) requires user interaction due to conflicts, IDA will show in 3-pane "merge" mode.
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.
Passing credentials on the command line will always take precedence over environment variables and registry+keychain.
Credentials can also be passed through environment variables. They will take precedence over those possibly found in the 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.
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.
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:
Special file revision symbols
Directories and wildcards
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 in this section manipulate sites.
A user must be using a site in order for most commands to work correctly.
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.
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 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.
Parameters
Example:
Delete the site, forcing deletion of the site’s worklists
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.
Parameters
Examples:
Change the root directory of a site:
Transfer ownership of site "local_on_shared_machine" to Bob:
sitessites [SITENAME]
Lists all sites.
Show a list of sites, and their associated information.
Parameters
Example:
filt get
filt get [-s SITENAME]
Displays the filter table associated with the site.
Only admins can see filter tables of other users.
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.
Parameters
Examples:
Make everything in the current site hidden, but .bak files
Set site filters, from a file
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.
Parameters
Examples:
add files to worklist 2
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.
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:
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.
Parameters
Example:
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.
Parameters
Example:
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.
Parameters
Example:
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 -a is provided)
deleted files (if -d is provided)
modified files (if -e is 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.
Parameters
Example:
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
Parameters
Example:
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.
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).
Parameters
Examples:
Show the worklist contents of another user
worklist edit
worklist edit WORKLIST_ID DESCRIPTION
Edits a worklist description.
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.
Parameters
Example:
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.
Parameters
Example:
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.
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.
Parameters
Example:
revert
revert [-a] [-p] [-s] PATH_PATTERN…
Reverts opened files to their current revisions.
Parameters
Example:
migrate
migrate [-s] PATH_PATTERN… WORKLIST_ID
Moves opened files between worklists.
Parameters
Example:
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
Parameters
Examples:
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
Parameters
Examples:
showWrites the contents of a file on the vault to the command line.
Parameters
Example:
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.
Parameters
Examples:
with interfaces.i64 opened for edit and changed, this will open IDA and show the differences with the current revision on vault
md5Prints the md5 checksum of a file on the vault.
Parameters
Example:
infoinfo
Displays info about the vault and current session.
Example:
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 -l is enabled
Parameters
Examples:
find all commits made by john
show last 2 commits on a file with full descriptions
usersusers
Shows users.
Example:
groupsgroups
Displays all the existing groups and their users.
Example:
group showgroup show GROUP_NAME
Displays the list of users in a group.
Parameters
Example:
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 privileges
the license id of the user
the full name of the user
the email address of the user
notes about the user
Parameters
Example:
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
Parameters
Example:
passwdpasswd PASS [USER]
Sets a new password for a user.
Parameters
Examples:
commit editcommit edit COMMIT_ID DESCRIPTION
Edits a commit description.
Regular users may modify only their own commits. Admins may modify any commit.
Parameters
Example:
licenseslicenses
Shows active licenses
Example:
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.
Parameters
Example:
returnreturn PRODUCT
Return a borrowed license
A returned license becomes available to other vault users.
Parameters
Example:
These commands require that the user executing them has admin privileges.
user add
user add USERNAME REALNAME EMAIL IS_ADMIN NOTES
Adds a user.
Parameters
Example:
user edit
user edit USERNAME REALNAME EMAIL IS_ADMIN NOTES
Edits a user definition.
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.
Parameters
Example:
group add
group add GROUP_NAME
Adds a new group.
An empty group with the specified name is created.
Parameters
Example:
group edit
group edit GROUP_NAME USER ADD_OR_DELETE
Edits a group by adding or deleting users.
Parameters
Example:
group del
group del GROUP_NAME
Deletes a group.
Parameters
Example:
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.
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'.
Parameters
Example:
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 //
Parameters
Example:
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)
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.
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
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:
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.
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
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
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.
Select the local database, ignoring all changes in the remote database.
No IDA process is run.
Select the remote database, ignoring all changes in the local database.
No IDA process is run.
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.
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.
.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.
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.
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)
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
The lc executable provides a command-line interface to interact with a Lumina server and its contents.
virtually all the commands described in this document, require administrator rights; "regular" users will typically not have the necessary privileges.
-h, --host HOSTNAME[:PORT] Lumina host name and port (if port is omitted, it defaults to 443)
-u USERNAME specify username
-p PASSWORD specify password
-v, --verbose verbose output
In order to connect to a Lumina server, lc must at least be provided with a hostname and a valid user-password pair.
In order to keep the various commands' syntax as clear as possible, we will omit the login options from commands for the rest of this manual.
Other options exists, specific to each lc command (see Commands).
The following commands are accepted by lc:
Commands in this section let users view metadata stored in the Lumina server and their history.
hist showhist show [OPTION]
Queries history of changes for function(s).
The following informations will be displayed for each change:
The ID of the change
The timestamp of the change
The ID of the push that contains the change
The name of the function at that change (+ (*) if it has been modified past this change)
optional: The username of the user that pushed this change
optional: The name of the license associated with the push for this change
optional: The email of the license associated with the push for this change
optional: The ID of the license associated with the push for this change
optional: The ID of the function
optional: The effective address (EA) of the function in the input file for the change
optional: The hash of the function
optional: The path of the idb file where the change came from
optional: The hash of the file where the change came from
optional: The path of the file where the change came from
Wildcards can be used to facilitate the usage of options that take strings as input. See the appendix.
-a, --additional-fields LIST
Comma-delimited list of additional info to display (username, license_name, license_email, license_id, func_id, func_ea, calcrel_hash, idb_path, input_hash, input_path, all)
-d, --details Show details (diff-like) for each change
--chronological Display entries in chronological order (defaults to reverse-chronological).
-m, --max-entries NUMBER maximum number of entries to fetch (defaults to 100)
-l, --license-id LICENSE license ID (XX-XXXX-XXXX-XX format) to operate on
-r, --history-id-range RANGE
history ID range(s) to operate on (start0..end0 […])
-t, --time-range RANGE
time range to operate on (start..end) see the appendix
-i, --idb IDB IDB name(s) to operate on
-f, --input FILE input file(s) to operate on
-u, --username USERNAME username(s) to operate on
-n, --func NAME function name(s) to operate on
-h, --input-hash HASH input file hash(es) to operate on
-p, --pushes-id-range RANGE
Pushes ID range(s) to operate on (start0..end0 […])
-c, --calcrel-hash HASH function hash(es) to operate on
--last-change Select only the last change for a function (which speeds up execution)
Examples:
List the last 8 changes ("-m 8" specifies the number of changes to show; the default order is reverse-chronological)
List changes from id 9 up to (but excluding) id 14
List changes using multiple ranges (9..14,505..515; in this case, there were no changes after 507 in the database)
Find changes from a specific idb file ("-i"), showing the function hash and ea ("-a" adds additional columns to the output)
Show the first 4 changes ("-m4") with their input file(s) (in "--chronological" order; "-a" adds an additional column)
Show the last change by a user ("-u" indicates the user, "-m1" means show 1 change only, "-a" adds an additional column)
Show up to 4 changes ("-m4") between two dates ("-t" indicates a range of "YYYY-MM-DD" dates)
Show up to 4 changes ("-m4") between two "now"-relative dates ("-t", from 2 weeks ago to 5 minutes ago) ("-a" adds an additional column)
Show up to 4 changes ("-m4") between two "now"-relative dates ("-t", from 2 weeks ago to 5 minutes ago) ("-a" adds an additional column), only select the last change for each function
Show up to 4 changes ("-m4"), occurring after a "now"-relative date ("-t", from 6 hours ago up to now)
Show changes about a specific function name ("-n")
Show changes about a function name ("-n") searched by wildcard ("like:…")
Show metadata details ("--details") in changes for a function ("-n"); this particular change added a new function
hist pusheshist pushes [OPTION]
Shows pushes to the Lumina server.
-a, --additional-fields LIST
Comma-delimited list of additional info to display (license_name, license_email, license_id, all)
-t, --time-range TIMESTAMP timestamp
-u, --username USERNAME username(s) to operate on
-l, --license-id LICENSE license ID (XX-XXXX-XXXX-XX format) to operate on
-m, --max-entries NUMBER maximum number of entries to operate on (defaults to 100)
--chronological Display entries in chronological order (defaults to reverse-chronological).
Examples:
List all pushes from a specific license ID
List all pushes from licenses with IDs matching a pattern ("-a" adds an additional column)
Show the first push
List all pushes between two timestamps
List all pushes from two users ("-a" adds an additional column)
hist delhist del [OPTION]
Deletes history and metadata for functions.
-s, --silent Do not ask for confirmation before deleting history
-l, --license-id LICENSE license ID (XX-XXXX-XXXX-XX format) to operate on
-r, --history-id-range RANGE
history ID range(s) to operate on (start0..end0 […])
-t, --time-range RANGE
time range to operate on (start..end) see the appendix
-i, --idb IDB IDB name(s) to operate on
-f, --input FILE input file(s) to operate on
-u, --username USERNAME username(s) to operate on
-n, --func NAME function name(s) to operate on
-h, --input-hash HASH input file hash(es) to operate on
-p, --pushes-id-range RANGE
Pushes ID range(s) to operate on (start0..end0 […])
-c, --calcrel-hash HASH function hash(es) to operate on
--last-change Select only the last change for a function (which speeds up execution)
Examples:
Display the last 10 changes, with their input file(s) and function ID(s)
Delete all changes for functions matching a pattern
Delete all changes stemming from a specific file
List the changes from pushes 1 to 5 (not included), showing their input file(s)
Delete one single change
Delete all the changes from push 1
Delete all changes by a user
Delete the last change for a function
Delete all remaining changes for a function by name
infoinfo
Shows lumina connection information.
Example:
usersusers
Shows users.
Example:
statsstats [OPTION]
Shows the numbers of functions, pushes, history records, IDBs and input files stored in the Lumina server database.
-u, --username USERNAME username(s) to operate on
Examples:
Retrieve the statistics for a list of users
These commands require that the user executing them has admin privileges.
Users management is delegated to the Hex-Rays Vault server; the administrator will be in charge of performing the adding/editing/deleting of users on the Hex-Rays Vault server itself.
Whenever a user connects to the Lumina server, it will turn to the Hex-Rays Vault server to ask it to perform authentication.
A "shadow" of the user data is nonetheless kept in the Lumina server’s database, in order to be able to attribute contributions.
The host name (and port) of the Hex-Rays Vault server need to be present in the lumina.conf file.
session list
session list
Lists the current connections to the Lumina server. For each connection, the currently executed query (if any) is shown.
Example:
session kill
session kill ID
Kills an existing connection to the Lumina server.
Parameters
Example:
The Lumina server is a "functions metadata" repository.
It is a place where IDA users can push, and pull such metadata, to ease their reverse-engineering work: metadata can be extracted from existing projects, and re-applied effortlessly to new projects, thereby reducing (sometimes dramatically) the amount of time needed to analyze binaries.
While the workflow with the Hex-Rays Vault server and associated tools (hv, hvui and IDA’s diff/merge modes) are extremely powerful for working on multiple revisions of the same binaries, the Lumina server in turn eases the replication of past efforts to new projects.
In effect, the Lumina server offers another "dimension" to collaborative reverse-engineering efforts.
The Lumina server associates "function metadata" to functions, by means of a (md5) hash of those functions: whenever it wants to push information to, or pull information from the server, IDA will first have to compute hashes of the functions it wants to retrieve metadata for, and send those hashes to the Lumina server.
Similarly, when IDA pushes information to the Lumina server, it will first compute hashes for the corresponding functions, extract the metadata corresponding to those from the .idb file, and send those hash+metadata pairs to the server.
Metadata about functions can include:
function name
function address
function size
function prototype
function [repeatable] comments
instruction-specific [repeatable] comments
anterior/posterior (i.e., "extra") comments
user-defined "stack points" in the function’s frame
the function frame description and stack variables
instructions operands representations
When a user pushes metadata about a function whose md5 hash isn’t present in the database, the Lumina server will simply create a new record for it.
However, when a user pushes metadata about a function whose md5 hash (and associated metadata) is already present in the database, the Lumina server will attempt to "score" the quality of the old metadata and the quality of the new metadata. If the score of the new metadata is higher, the new function metadata will override the previous one.
When a user asks IDA to push all functions to the Lumina server, IDA will automatically skip some functions: those that still have a "dummy" name (e.g., sub_XXXX), or that are below a certain size threshold (i.e., 32 bytes) will be ignored.
The Lumina server retains a history of the metadata associated to functions. Using the lc utility, it is possible to dig into that history, and view changes (detailed diffs, too.)
It’s worth pointing out that when pushing metadata to the Lumina server, IDA will not push the binary file itself. Only the following metadata about the file itself will be sent:
the name of the input file
the name of the IDB file
a md5 hash of the input file
The Lumina server cannot therefore be used as a backup/repository for binary files & IDBs (that would be the role of the Hex-Rays Vault server)
Options that take strings as inputs can be enhanced through wildcards. The following wildcards are available:
%
represents zero, one or multiple characters.
_
represents one character.
To use wildcards in a string, it must be prefixed with like: e.g. -n like:%main%.
For timeranges, the following syntaxes are supported:
<ts>..<ts> (from timestamp to (but not including) timestamp)
<ts> (only one timestamp)
Where <ts> can be of the form:
yyyy-mm-dd HH:MM:SS: e.g., 2022-09-12 11:38:22
yyyy-mm-dd: e.g., 2020-03-12
+|-<count><unit>: this is a "now-relative" timestamp, where <unit> must be one of w, d, H, M, S for weeks, days, hours, minutes or seconds respectively. E.g., -4d, +5w, -8H, +1H, …
when using the <ts> syntax (i.e., only 1 timestamp is provided, not an actual range), the final range will be either "from now to <ts>", or "from <ts> to now", depending on whether <ts> is before, or after, the present time.
Although it may seem like a simple operation, lc hist show is actually a very demanding one: by default it will have to fetch bits of information from multiple tables (e.g., in order to provide information about which change was superseded by a later one.)
This can be significantly sped up through the use of --last-change: this option lets the server issue a much simpler query, resulting in significantly reduced processing time.
This user guide provides information about HVUI, the Hex-Rays Vault visual client.
HVUI is provided in addition to the command-line client, HV.
This manual assumes that the reader has an understanding of the IDA Teams general concepts.
Although Hex-Rays Vault will host any file you want, its primary use-case is to allow users to keep a history, and allow collaborative work on, IDA databases (i.e., .idb and .i64 files.) Throughout this manual, we will be using the terms "idbs" and "files" interchangeably.
In order to function, HVUI will need to connect to a Hex-Rays Vault server.
This guide assumes that such a server is running, accessible, and an account is available:
| Connection attributes | |
|---|---|
The first time the user starts the application, credentials will need to be input:
Checking the checkbox at the bottom of the form, will cause HVUI to store credentials in the registry, password(s) will be stored in the OS’s keychain.
If this is the first time a login is performed from this machine, the user will have to specify a directory where files will be locally stored:
This will create a site (that is, a mapping of the server files on the local disk) for use on this computer.
After accepting the dialog, you will be presented with the main view:
The widget now shows what files are available.
Notice the #0/1 suffixes: it means we currently have revision number 0 (i.e., no revision at all) of those files.
Let’s sync those files to their latest revision, from the server:
And the files are now up-to-date:
In the previous chapter, we have introduced the notion of "syncing to the latest revision".
This chapter will go a bit further, and introduce the most common, day-to-day operations users will want to perform on their files.
Any work done in HVUI will involve worklists, and commits.
A worklist holds files that have been
modified,
marked for addition or
deletion,
…
Those modifications are local to the user’s site. They will only be made available for everyone after the user commits the worklist.
Once a worklist is committed, it becomes a commit, and makes its modifications available for everyone.
In comparison to a worklist, a commit holds "published" modifications, and any user syncing to that commit will benefit from those.
Let’s look at a concrete example illustrating worklists and commits: adding a file to the Hex-Rays Vault!
From the "Local files" widget, I can add a file that is not yet present in the Hex-Rays Vault server:
That file will now be added to the current worklist (one will be created if needed):
For this new file to become available for everyone, the user will need to "commit" the worklist:
Once the worklist is committed, it becomes a commit, and the modifications are then available for everyone:
Notice how our commit isn’t the first one in the system: another user submitted a commit before us — it’s that commit that added the files we’ve seen in the getting-started portion of this guide.
When working on a file, a user must first check it out for modification:
Just like with the adding, the file will now show in a worklist:
…and just like with the adding, whatever modification you make to the file, will only be visible to coworkers after committing that worklist.
Files that have been checked out (e.g. for modification) or opened for adding will go into a worklist until they are committed, which then turns the worklist into a commit. A worklist can be committed to make its changes available to other users: right-click, commit
The worklist becomes a commit:
…and the worklist is gone:
To fetch the latest set of the changes (changes/additions/deletions), use "Get latest revision".
To get an overview of all of the changes made to a file: right-click, File history
From the "History of …" widget, you can view any revision of a file.
It’s also possible to synchronize files to older revisions, from this widget.
When asked to do that, HVUI will retrieve that older revision of the file from the server. This is what will now be present on your filesystem.
Notice how the file now shows as 'outdated':
On many widgets, it’s possible to view/open a file. If the file extension has a corresponding association it will be used to open the file.
Out-of-the-box, HVUI associates .idb and .i64 files with IDA. In addition to that, it provides a default "fallback" "*" association that will cause matching files to be opened in IDA.
Users can specify their file extension associations via a form available from the View menu.
Files can be removed from the server (if they have become unnecessary for example): right-click, delete.
Just like other file actions, the change (deletion) needs to be committed for its effects to be visible on the server.
To revert unwanted changes to a file: right-click, Revert
It is also possible to use "Revert if unchanged" to only revert files that were checked out without actual changes. This is especially useful when used on a selection of files or a directory.
One may wish to rename and/or move around files/folders in their workspace, for that "Checkout for move/rename…" can be used.
HVUI provides an action to copy files or directories easily. Use "Checkout for copy…".
When a vault contains a lot of files, manually searching for a file in the directory tree becomes inefficient. To help you locate files easily, you can use the Find in vault… action.
You can navigate between the search results by using Next search result and Previous search result, located next to Find in vault… both in the toolbar, and in the "Search" menu.
As you may have noticed by now, files are shown with different font styles in different circumstances.
A gray font denotes a file that is not in the vault. It has been added or renamed and not yet commited.
A bold font means that this file is being worked on, or has been changed.
An italic font means that it’s not the latest version of this file.
Some combinations are possible, for example a file being resolved (not latest version and being worked on) will have a bold and italic font style. The combination gray (not in vault) and italic (not latest version) is for example not possible.
After having done some reverse-engineering work on an IDA database, it is possible to view those changes in a special mode in IDA: right-click, and choose the diff action:
Here a new instance of IDA will be launched in a special "diff" mode:
This new IDA mode lets the user compare two databases, in a traditional "diff" fashion: essentially a two-panel window, showing the unmodified file on the left and the version with your changes on the right.
Represents the current step in the diff process.
Shows the "untouched" version of the database (i.e., the one without your changes)
Shows your version of the database (i.e., featuring your changes)
Notice how both panels have a little area at the bottom, that is labeled "Details".
Details are available on certain steps of the diffing process, and provide additional information about the change that is currently displayed.
The actions in the toolbar are:
Using actions in the toolbar, you can now iterate through the differences between the two databases, with each change shown in context as if viewed through a normal IDA window.
The ability to view changes in context was a major factor in the decision to use IDA itself as the diffing/merging tool for IDA Teams.
Move to the previous change
Re-center the panels to show the current chunk (useful if you navigated around to get more context)
Move to the next change
Move to the next step in the diffing process.
Toggle the visibility of the "Details" widgets in the various panels (note that some steps do not provide details, so even if the "Details" are requested, they might not be currently visible.)
It is important to note the difference between the terms "diff" and "merge".
This document will sometimes use the two terms interchangeably. This is because to IDA, a diff is just a specialized merge. Both diffing and merging are handled by IDA’s "merge mode", which involves up to 3 databases, one of which can be modified to contain the result of the merge.
A diff is simply a merge operation that involves only 2 databases, neither of which are modified.
This is why often times you will see the term "merge" used in the context of a diff. In this case "merge" is referring to IDA’s "merge mode", rather than the process of merging multiple databases together into a combined database.
We must stress the fact that performing a merge between two IDA databases is quite different than performing a merge between, say, two text files. A change in a chunk of text file will not have an impact over another chunk.
IDA databases are not so simple. A change in one place in an idb will often have an impact on another place. For example, if a structure mystruct changed between two databases, it will have an impact not only on the name of the structure, but on cross-references to structure members, function prototypes, etc.
This is why IDA’s merge mode is split into a strict series of "steps":
Within a single step it is possible to go forward & backward between different chunks. But because of possible inter-dependencies between steps, it is not possible to move backwards between steps, you can only go forward:
Since IDA’s diff mode is just a variation of its merge mode, diffing databases is also subject to this sequential application of steps in order to view certain bits of information. That is why, in some steps (e.g., the "Disassembly/Items") IDA might not report some changes that were performed at another level.
For instance, if a user marked a function as noret, the listings that will be shown in "Disassembly/Items" step, will not advertise that there was a change at that place (even though the "Attributes: noreturn" is visible in the left-hand listing), only the changes to the instructions (and data, …) are visible in the current step:
The change will, however, be visible at a later step (i.e., "Functions/Registry"):
The changes applied during the "diff" process are only temporary. Exiting IDA (at any moment) will not alter the files being compared.
As with any collaborative tool, it may happen that two coworkers work on the same dataset (e.g., IDA database), and make modifications to the same areas, resulting in "conflicts". Conflicts must be "resolved" prior to committing.
To do that, right-click and pick one of the "resolve" options:
IDA Teams provides the following merge strategies.
If the option that was chosen (e.g., Interactive merge mode) requires user interaction due to conflicts, IDA will show in 3-pane "merge" mode.
When a conflict is encountered, you’ll have the ability to pick, for all conflicts, which change should be kept (yours, or the other). Every time you pick a change (and thus resolve a conflict), IDA will proceed with the merging, applying all the non-conflicting changes it can, until the next conflict - if any. When all conflicts are resolved, you can leave IDA, and the new resulting file is ready to be submitted.
Over the years, a trend has been emerging in the field of reverse-engineering: a need to enable collaboration between different (teams of) individuals and share their work with one another.
In order to achieve that, different groups of people have come up with different strategies, the most common ones being:
"live" propagation of changes from one IDA session, to other sessions (this requires all IDA instances are either directly connected, or talk to a server, at all time)
extracting some of the important bits of work done on an .idb, and applying those to another one — in fact, we at Hex-Rays have also been providing a tool that enables this type of workflow: the lumina server.
While those solutions have interesting properties, they also typically suffer from significant drawbacks as well:
they might require a live connection at all times in order to work,
there is no way to make sure many supposedly-synced IDA sessions are indeed working with exactly the same data,
the information that’s extracted isn’t complete enough,
…
So we took a step back and looked at how things are done in other places, and in particular in the field of software engineering, where collaboration over a piece of software is typically achieved by using revision control.
That is why one of the key features of IDA Teams, is software engineering-inspired revision control, applied to reverse-engineering
Plans for IDA Teams span well beyond just revision control, but this was our first, significant milestone.
The general concepts behind IDA Teams revision control, are essentially the same as those behind many other revision control systems, and uses a client-server architecture.
On the server-side, we will find a new component: the The Hex-Rays Vault server
On the client side, we will find that an IDA Teams installation now install a few additional binaries: a pair of clients to connect to the server
The server, called Hex-Rays Vault server, maintains a ledger of operations that were performed on the files that it hosts: modifications, added files, deleted files, …
It should be made available to all members of a team destined to work on common projects.
The server comes with its own installer, and an "admin guide" explaining how to tune the installation & perform common tasks.
On the client-side, IDA Teams will consist of an IDA installer, to be installed on each user’s computer.
In addition to the regular IDA binaries, that new installer will alse place two clients to connect to the Hex-Rays Vault server:
hv: a command-line interface client
hvui: a visual client
Users interact with the server using those tools, which lets them get a good view over who contributed what, and offer functionality for organizing their work in the most efficient way possible.
Online vs Offline
Users have all the freedom to organize their work the way they see fit: they don’t have to be connected at all times, and will only need to be able to connect to the server when it is time to publish their changes so they are available for others to benefit from.
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:
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.
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
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
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.
Select the local database, ignoring all changes in the remote database.
No IDA process is run.
Select the remote database, ignoring all changes in the local database.
No IDA process is run.
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)
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.
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
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.
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.
.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.
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.
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)
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.
The "Vault files" widget represents the data that’s available on the server.
Since its contents can be very similar to what is shown in the "Local files" (depending on whether user’s site is using site filters or not), it has been given differentiating background color, in the hope of not confusing it with that other widget.
The "Local files" widget represents the data that’s available on the local disk.
The root of the tree starts at the site’s workdir.
Note that this widget honors the hvignore file that’s placed in the installation directory next to hvui, and also any .hvignore file found in the directory structure.
Open the containing folder // local only
The "Worklists" widget groups all the modifications that are still pending (and are thus not yet visible to other users)
Those changes are grouped by "Worklist" (i.e., topic). A typical worklist will hold files that are related, and will be made available to all once a worklist is committed.
It is possible to move file(s) from a worklist to another, by "drag & drop"'ing them, "cut & paste"'ing them, or using the Migrate to another worklist… action.
By default, this widget will only show the current user’s worklists, but can be made to show everyone’s worklists, in read-only mode: the current user will still only be able to modify (or commit) his/her own worklists.
The "commits" widget shows a list of previous commits made to the server, in a concise and condensed way.
It is possible to request a detailed view for any entry in that list.
The amount of entries displayed by this widget can be configured through the "Options" dialog.
Using the "commits" widget, it is possible to inspect what changes were previously submitted to the vault in a particular commit.
Actions
The "Sites" widget provides the ability for a user (or an admin) to administrate users' sites.
Non-admin users will only be able to modify their own site(s), while an admin will have the ability to do so for all users' sites.
If you find yourself using more than one site on any specific machine, you will likely have to resort to the Use this site… to switch between them.
The "Users" widget lists all knows users of the Hex-Rays Vault server.
Non-admin users have the possibility to change their password.
Users with administrator rights will, in addition, be able to add, remove, modify users - and modify anyone’s password.
The logging area is helpful in providing feedback about different types of events:
Details of successful operations
Connection state (logins, logout’s, network issues, …)
…other various bits of information that the program deems relevant for the user to know
The logging area provides typical text-manipulating functions (copying, searching, …) as well as the ability to turn timestamps on/off.
The "File history" widget shows all changes ever commited to a single file.
The following is a list of actions, available in hvui. Note that most actions are "contextualized" in the sense that they require certain conditions to be met, in order to work:
the widget being operated on,
whether or not a selection is available,
the state of the selected file(s),
…
All actions are available from the toplevel menubar’s submenus. Those whose operating conditions are not met, will appear disabled.
Contrary to the toplevel menubar’s submenus, context menus (AKA: popup menus, right-click menus, …) will not feature actions that are disabled. Those menus are created on-the-fly, and it’s best not to pollute them with unnecessary noise.
Sync the selected file(s) (or the entire server contents), to the latest revision.
This effectively updates all local copies of the files, except for those that are currently opened for edition, addition or deletion: those will be left untouched in order to not risk losing user modifications made to them.
Prompts the user for a commit description, and submits the files that are part of the current worklist, to the server.
Once successfully committed, a worklist will disappear and a new entry will be added to the list of commits.
Committed changes (modifications, additions and deletions) are available for all users that can access those files.
Scan the selected files/folders (or the entire root directory), and create a worklist with all changes that were found: files that have been added, removed, modified, …
Unless you explicitly tell it not to (by checking the "Do not show this dialog anymore" checkbox), this action will first offer the possibility to refine what exactly the scan should be looking for:
Spotting new or deleted files is fairly straightforward, but when it comes to existing files, hvui will also perform a md5 checksum comparison.
If differences are found, hvui will prepare a new worklist with those.
This is especially useful if one had to work on some files while no connection to the server was available (e.g., on a plane).
The files found will be filtered by hvignore.
Opens a detailed view of the commit details, including a list of the files that were modified:
Retrieve the specified revision from the server, and replace the local file with it.
For each selected file, perform a diff of the selected file, against its previous revision.
If a file is opened and has been modified, those yet-unsubmitted modifications will not be part of the diff: only those between the two recorded revisions, will be visible.
A more powerful version of Diff against previous revision, that lets the user pick for each "side" of the diff:
either the current revision, any revision number, or to the local file on disk
the path to the file (it is therefore possible to diff entirely unrelated files together)
Informs the server that we will be working on those files in the near future.
They will be added to the worklist number 1 (which will be created if it doesn’t exist), and will turn bold, to draw attention to them.
Informs the server that we wish to add the selected file(s) to the list of files managed by the server.
They will be added to the worklist number 1 (which will be created if it doesn’t exist), and will turn bold, to draw attention to them.
The files selected will be filtered by hvignore.
Informs the server that we wish to delete the selected file(s) from the list of files managed by the server.
They will be added to the worklist number 1 (which will be created if it doesn’t exist), and will turn bold, to draw attention to them.
For each selected file (or directory), prompt the user for a new name to rename to.
This is the equivalent of executing Checkout for copy…, followed by Checkout for delete.
For each selected file or directory, prompt the user for a new name to create a copy into.
The copied files will be added to the worklist number 1 (which will be created if it doesn’t exist).
For each selected file, launch the associated application.
The file is retrieved from the server, and downloaded into a temporary location. It is cleaned after the application exits.
For each selected file, open a File history widget showing the list of modifications that were made to the file.
Reverts the selection - that is: remove from the worklist(s), and restore the current revision from the server.
This action will lose all changes made to the selected file(s), and thus will first prompt for confirmation.
See also Revert if unchanged
A "safe" version of Revert…, that will first verify if files have been modified, before reverting them.
Files that have not been modified, will be reverted. Those that have been, will remain untouched.
Since this is a safe operation (in the sense that no data can be lost), this action will not ask for confirmation.
See also Revert…
For each entry in the selection, launch the associated "View" application.
If no association is present for a specific file extension (or if the file does not have an extension), the default * association will be used.
For each folder in the selection, asks the OS to open a file browser at the corresponding place.
What file browser is opened, depends on the OS’s settings.
hvui comes with many strategies to resolve files:
However, hvui only knows how to handle a successful merge operation when IDA is used. Consequently, only the last 2 operations will be available for non-.idb/.i64 files.
The first thing that happens is that the last revision of the file is retrieved from the server (and stored in a temporary location).
Then (for all but Use local, discard remote… and Use remote, discard local…) IDA will be launched in a special mode, and with different set of parameters that depend on the exact nature of the operation.
Perform the "resolve actions" prolog, then launch IDA non-interactively: IDA will attempt merging the changes made to the local file with those that were made to the last revision of the file, and succeed if no conflicting changes were found.
This is a safe operation in the sense that, should there be any conflict, it will not touch the local file.
Perform the "resolve actions" prolog, then launch IDA non-interactively: IDA will merge the changes made to the local file with those that were made to the last revision of the file. Each time a conflict is found, automatically pick the local change.
Perform the "resolve actions" prolog, then launch IDA non-interactively: IDA will merge the changes made to the local file with those that were made to the last revision of the file. Each time a conflict is found, automatically pick the other change.
Perform the "resolve actions" prolog, then launch IDA interactively: the user will be presented with a 3-panel IDA instance, where it will be possible to manually pick either the local, or the remote change, for each conflict.
Once the user is done and exits IDA saving the resulting database, the file will be considered resolved.
Perform the "resolve actions" prolog, then just consider that our local version of the file is the correct one.
Perform the "resolve actions" prolog, then replace the local version of the file with the other one.
Retrieve the specified file(s) from the server (and store them in a temporary location), then launch the associated "Diff" application to compare them against their local versions.
Prompt the user for a pattern/substring to be looking for, and queries the server.
If a match is found, it will be selected in the Vault files widget. It is then possible to move forward/backward in the search results.
Move forward in the result set of a Find in vault… operation.
Move backward in the result set of a Find in vault… operation.
Clears the local caches of all the data that was retrieved from the local filesystem & the Hex-Rays Vault server, and force a refresh of all widgets.
Find the corresponding selection in the other view, select it, and give focus to that view.
This is helpful to navigate between Vault files and Local files
Toggle the visibility of files that have been deleted.
When a file is deleted in revision #N, its revisions up to #N-1 are still kept on the server (but not visible by default.)
This offers the opportunity to view (and possibly resurrect) such deleted files.
Create a new site.
While logged in as a non-administrator, you won’t have the choice but to associate the site to the current user. However, when logged in as an administrator, it is necessary to provide the user’s name as well.
Offers the ability to modify the following properties of a site:
Its root directory
The client’s host
Optional site filters
Delete the selected site (after prompting for confirmation.)
Naturally, deleting a site will also delete the worklists that were associated with that site. The commits that were made from that site will not be deleted.
Have hvui switch to the selected site.
This can be useful if you have more than one site on your machine.
Switching to a site requires that the client host matches that of the current machine, and that the site belongs to the user who’s currently logged-in.
Prompts the administrator for various bits of information about the user: login, real name, license ID, password, … and registers that information on the server.
Lets an administrator change all information about a particular user, with the exception of their login (immutable) and password (use the dedicated action to do that.)
Asks the administrator for confirmation, then deletes the user from the server.
Deleting a user also deletes the worklists that belonged to the user. The commits made by that user won’t be impacted.
Prompts for a new password (and its confirmation), and applies the changes on the server.
Prompts the user for a brief worklist description (which can remain empty at this point), and create a new, empty worklist.
Shows worklist details, and offers to edit its description.
This action can only be performed on worklists that belong to the current user.
Shows other users' worklists details, in read-only mode.
Prompts for confirmation, and deletes the worklist.
All modifications (including additions & deletions of files), will be abandoned/reverted.
Lets the user pick another one of his pending worklists (or, alternatively, create a new one), then moves the files to that worklist.
Toggle between the two following states:
show this user’s worklists on this site,
show all worklists (from all users, and on all sites)
In order to do any meaningful work in hvui, a user must be using a site.
To make it easier to get started using hvui, the first time a user connects to the Hex-Rays Vault server, the application will propose a a simplified site creation dialog, that will query only the "root directory".
The rest of the site attributes will be guessed (or generated):
the host name will be retrieved automatically from the system
the user name is known since the user just logged in
the site name will be generated from the user name + host name
It is of course still possible to alter that site later, through the "Sites" widget.
HVUI stores certain bits of information in the registry:
On Windows, this will be located under \HKEY_CURRENT_USER\Software\Hex-Rays\HVUI
On Unix systems, HVUI will use a file-backed registry, located at $HOME/.idapro/hvui.reg
-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
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)
^
last revision available on the vault
=
current revision, that is synced on the site
*
all revisions
subdir/
means all files in all subdirectories
subdir
means all files in all subdirectories (same as subdir/)
subdir/*
means all files in the directory
-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.
-f
Force the deletion even if the site still has worklists.
SITENAME
Name of the site to delete.
-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.
SITENAME
Name of the site to show.
-s SITENAME
The sitename whose filter table should be displayed. If omitted, defaults to the current site.
-s SITENAME
The sitename whose filter table should be set. If omitted, defaults to current site.
@file
File containing the new table.
-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.
-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.
-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.
-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.
-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.
-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.
WORKLIST_ID
Restrict to the provided worklist, defaults to showing all worklists.
USER
Restrict to user USER, defaults to the current user.
DESCRIPTION
The description of the new worklist.
-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.
WORKLIST_ID
The worklist to modify.
DESCRIPTION
The new description for the worklist.
WORKLIST_ID
The worklist to delete.
-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.
-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 (#^).
METHOD
One of "auto", "lmerge", "rmerge", "manual", "local" or "remote".
PATH_PATTERN
Vault path of file(s) to resolve.
-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.
-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.
-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.
-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.
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.
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 (#=).
PATH_PATTERN[=REVISION]
Vault path of file(s) to process, if no revision is specified, defaults to the current revision (#=).
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.
GROUP_NAME
A group name.
USERNAME
The username of the user to display.
COMMIT_ID
The id of the commit to display.
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.
COMMIT_ID
The id of the commit to amend.
DESCRIPTION
New description of the commit.
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.
PRODUCT
The product code or license id.
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.
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.
-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.
GROUP_NAME
the name of the new group.
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.
GROUP_NAME
the name of the group to delete.
@FILE
The file from which to set the new permissions table.
USERNAME
The USERNAME of the user whose permissions that will be tested.
PATH_PATTERN
Vault path of file(s) that will be tested.
-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.
ID
The connection to kill, as shown by thecommand
Host
vaultserver
Port
65433
User name
joe
User password
secret
