.. _guest_agent:

Guest Agent
===========

Windows
-------

.. _directory: https://github.com/Cisco-Talos/pyrebox/tree/master/guest/win

You can find the windows guest agent under the guest/win directory_.

Compiling guest agent
*********************

You may need to install mingw-w64 packages. For example, on Ubuntu, or Debian:
::
  apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686 mingw-w64-i686-dev mingw-w64-tools gcc-mingw-w64-x86-64 mingw-w64-x86-64-dev g++-mingw-w64-x86-64

Just compile with ``make``. It will produce 2 files: win_agent_32.exe and win_agent_64.exe, for 
32 and 64 bit windows guests respectively.

Compiling test files
********************

In order to compile the test files, just use the provided Makefile as follows:
::
  make test_32
  make test_64

Linux
-----

.. _path: https://github.com/Cisco-Talos/pyrebox/tree/master/guest/linux

You can find the linux guest agent under the guest/linux path_.

Compiling guest agent
*********************

You may need to install the following packages. For example, on Ubuntu, or Debian:
::
  apt-get install libc6-dev-i386

Just compile with ``make``. It will produce 2 files: linux_agent_32 and linux_agent_64.exe, for 
32 and 64 bit linux guests respectively.

Compiling test files
********************

In order to compile the test files, just use the provided Makefile as follows:
::
  make 32bit_test 
  make 64bit_test


General usage
-------------

Configuring guest agent
***********************

- Add `plugins.guest_agent: True` to your pyrebox.conf
- (Optionally) modify your guest agent file name.
- Add the agent configuration to your pyrebox.conf
- Adjust the configuration appropriately (if you changed the agent file name).
- Make sure the agent conf file exists and is up to date. This file is automatically
  generated by the compilation process.
- Copy the corresponding guest agent (32 or 64 bit version) to the guest VM, and make 
  sure it follows the same name as declared in the configuration name.
- Start the agent (you can configure the VM to start the agent on every system start-up).
- Once the agent is started, you can take a snapshot.

Example agent configuration in pyrebox.conf:
::
  [AGENT]
  name: win_agent_64.exe
  conf: win_agent_64.exe.conf

Using the guest agent
*********************

.. _API: https://pyrebox.readthedocs.io/en/latest/api.html 

In scripts:

- Add ``plugins.guest_agent: True`` to your pyrebox.conf, or:
- Add a member to your module named "requirements" containing a 
  list of required plugins/scripts. E.g.: ``requirements = ["plugins.guest_agent"]``
- Import the plugin in your script: ``from plugins.guest_agent import guest_agent``.
- Interact with the guest agent using the public interface of this class (``guest_agent`` is 
  a singleton instance of GuestAgentPlugin). See API_.

In the IPython shell:

- If no script loads the guest_agent plugin, you will need to make sure it 
  gets loaded by adding ``plugins.guest_agent: True`` to your pyrebox.conf.
- Interact with the guest agent using the global member ``agent`` that is a singleton
  instance of GuestAgentPlugin. See API_.

Examples
********

.. _script: https://github.com/Cisco-Talos/pyrebox/blob/master/scripts/script_example.py#L171

The example script_ provides a custom command that documents how to use the agent
in a PyREBox script. The ``requirements: ["plugins.guest_agent"]`` member allows 
you specificy that the scripts needs the guest agent plugin to be loaded 
in order to work.