Example tools
=============

Python example tools live under ``pyintrovirt/tools/``. Each tool is marked
with an ``@example`` tag in its module docstring and is listed below with
full source.

Requirements
------------

- IntroVirt built with Python bindings (``-DINTROVIRT_PYTHON_BINDINGS=ON``)
- ``python3-pyintrovirt`` deb installed, or the generated wheel in a venv
- Root/sudo to access the hypervisor
- An IntroVirt-patched hypervisor (e.g. KVM) with kvm-introvirt installed

Running examples
----------------

After installing ``python3-pyintrovirt``, use the console scripts:

.. code-block:: bash

   sudo ivsyscallmon_py --list
   sudo ivsyscallmon_py -d win10 --syscall NtCreateFile
   sudo ivcallmon_py win10 --procname notepad.exe 'ntdll!Nt*'
   sudo ivfilemon_py -d win10 -f "C:\\Windows\\System32\\config\\SAM"

Or run as modules:

.. code-block:: bash

   sudo python3 -m pyintrovirt.tools.ivsyscallmon --list
   sudo python3 -m pyintrovirt.tools.ivcallmon win10 --procname notepad.exe
   sudo python3 -m pyintrovirt.tools.ivfilemon -d win10 -f "C:\\path\\to\\file"

``ivsyscallmon --list`` replaces the old standalone ``list_domains`` example.

System call filtering (Windows)
-------------------------------

For Windows guests, enable the filter at the domain level
(``domain.system_call_filter().enabled(True)``) and set which syscalls to trap
at the guest level via
``WindowsGuest.set_system_call_filter(domain.system_call_filter(), SystemCallIndex_XXX, True)``.
Do not call ``set_64`` or ``set_32`` on the domain filter; the guest converts
``SystemCallIndex`` to native indices. This matches **ivfilemon**, **ivcallmon**,
and **vmcall_interface**.

Examples
--------

.. toctree::
   :maxdepth: 1

   ivcallmon
   ivfilemon
   ivsyscallmon