Hypervisor Memory Introspection Core Library
HVI stands for Hypervisor Introspection. The term is used interchangeably with HVMI, which is a bit more specific, and stands for Hypervisor Memory Introspection.
Virtual Machine Introspection is defined as the technique of analyzing the state and behavior of a guest virtual machine from outside of it. In addition, Introspection can also leverage virtualization extensions to provide security.
The main purpose of this project is to provide unmatched security from outside the virtual machine, by leveraging the hardware isolation provided by Intel VT-x. The main categories of attacks HVI prevents are:
For more details check out the HVMI specification and the HVMI blog.
HVMI can work on any hypervisor, as long the proper API is provided (which is documented here). Currently, it has been integrated and tested with the following hypervisors:
Get Introcore and all the dependencies by running:
git clone --recurse-submodules https://github.com/bitdefender/hvmi.git
This will clone the HVMI repository and the bddisasm submodule.
Introcore can be built both as a Windows DLL, and as a Linux library. Only the 64-bit configuration is supported.
To build the project on Linux you need:
To integrate the library (libintrocore.so
) you can use the pkg-config
file (introcore.pc
) that is generated by cmake
.
Building Introcore is done by running cmake from the root of the repository:
# generate configuration
cmake -H. -G<generator> -B<build directory> -DCMAKE_BUILD_TYPE=<build type> -DCMAKE_INSTALL_PREFIX=<install prefix directory> -DCMAKE_LIBRARY_OUTPUT_DIRECTORY=<binary output directory> -DCMAKE_TOOLCHAIN_FILE=<toolchain>
The default value of CMAKE_INSTALL_PREFIX
is /usr/local/
.
The default value of CMAKE_LIBRARY_OUTPUT_DIRECTORY
is $project_dir/bin
.
cmake -B_build -DCMAKE_BUILD_TYPE=Debug
cd _build
make
cmake -B_build -DCMAKE_BUILD_TYPE=Release
cd _build
make
# install the introcore library (debug)
cd _build
make install
This builds the bddisasm dependency and then libintrocore, the exception and the guest support mechanism files. Use make introcore
to build just libintrocore. The resulting binaries will be in bin/x64/Debug
or bin/x64/Release
.
Generating an SDK that will contain libintrocore Debug and Release versions, and the public header files is done with:
mkdir _build
cd _build
cmake .. -B. -DCMAKE_BUILD_TYPE=Debug
make
cmake .. -B. -DCMAKE_BUILD_TYPE=Release
make
make package
This creates a ZIP file in the root of the repo that contains the latest libintrocore you’ve built, together with the header files from the include/public
directory.
To build the project on Windows you need:
When you first open the hvmi.sln
file, Visual Studio should prompt you to install any missing components. Building the introcore can be done directly from Visual Studio or with the build.cmd
script:
# build for Debug
build.cmd Debug
# build for Release
build.cmd Release
This will create introcore.dll and introcore.pdb in bin/x64/Debug
or bin/x64/Release
.
CMake is not supported for Windows builds.
Introcore comes with Doxygen code documentation, and a specification built with Sphinx.
For generating the Doxygen documentation on Linux, use:
cmake -B_build
cd _build
make doxy
For Windows, use:
make_doxy.cmd
Or invoke Doxygen directly:
doxygen Doxygen/Doxyfile
This assumes that you have Doxygen installed and in your path.
The Doxygen documentation will then be found in docs/_static/Doxygen/html
.
To build the specification you need:
To generate the HTML version of the documentation:
cd docs
make html
This will also build the Doxygen documentation. The result will be in docs/_build/html
.
Introcore has an exception mechanism, which is used to whitelist legitimate accesses to protected structures.
Sample exception files that should work for out-of-box installations of Windows 7 (SP1 and SP2) and Windows 10 1809 (RS5) are included in the exceptions
directory.
To generate the exceptions binary, use:
cmake -B_build
cd _build
make exceptions
For more information see exceptions.
Introcore needs to know certain information in order to properly hook and protect an operating system (for example, the layout of certain kernel structures, patterns for finding functions inside the guest memory, etc). These information are included in a CAMI data base file. Sample files that offer support for Windows 7 (SP1 and SP2), Windows 10 1809 (RS5), Ubuntu 18.04, and CentOS 8 can be found in the cami
directory.
To generating the cami binary, use:
cmake -B_build
cd _build
make cami
For more information see CAMI.
There are several ways to contact us: