Minor fix and linux guest agent

.gitignore

@@ -14,4 +14,8 @@ docs/build
 /win_agent_32.exe.conf
 /win_agent_64.exe.conf
 guest/win/*.exe
+guest/linux/linux_agent_32
+guest/linux/linux_agent_64
+guest/linux/test_64
+guest/linux/test_32
 *.a

README.rst

@@ -34,19 +34,18 @@ What's new
 Remember to pull the latest version of PyREBox in order to enjoy its latest features. PyREBox is under
 active development and new cool features are yet to come!
 
-- [Oct 23, 2017] Added guest agent for Windows 32 and 64 bit !!!
+- [Nov 02, 2017] Added guest agent for linux 32 and 64 bits.
+- [Oct 23, 2017] Added guest agent for Windows 32 and 64 bits.
 - [Oct 11, 2017] Added linux module symbol parsing.
 - [Sep 22, 2017] Added support for module reloading.
 - [Sep 20, 2017] Added custom function callback to BP class.
 - [Sep 20, 2017] Upgraded to Qemu v2.10.0.
-- [Aug 31, 2017] Partial support for linux guests
+- [Aug 31, 2017] Partial support for linux guests.
 
-Roadmap
+Install
 =======
 
-- VM image configuration and management console.
-- Support for ARM, MIPS, and other architectures.
-- Finish support for GNU/Linux guest systems (see issues).
+A build script is provided. For specific details about dependencies, please see BUILD_. We also provide a Dockerfile.
 
 Documentation
 =============
@@ -69,10 +68,13 @@ us solve your issues, please include as much information as possible in order to
 - Any information about the error such as error messages, Python (or IPython) stack trace, or QEMU stack trace.
 - Any other relevant information
 
-Install
+Roadmap
 =======
 
-A build script is provided. For specific details about dependencies, please see BUILD_. We also provide a Dockerfile.
+- VM image configuration and management console.
+- Support for ARM, MIPS, and other architectures.
+- Finish support for GNU/Linux guest systems (see issues).
+
 
 Starting a VM
 =============

docs/guest_agent.rst

@@ -31,7 +31,28 @@ In order to compile the test files, just use the provided Makefile as follows:
 Linux
 -----
 
-The linux guest agent has not been implemented yet but will be available soon.
+.. _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
 -------------

guest/win/include/host_opcodes.h → guest/include/host_opcodes.h

@@ -39,6 +39,8 @@
  "\x20\x00": self.handle_host_request_exec_path,
  "\x20\x01": self.handle_host_request_exec_args,
  "\x20\x02": self.handle_host_request_exec_env
+ "\x20\x03": self.handle_host_request_exec_args_linux,
+ "\x20\x04": self.handle_host_request_exec_env_linux
 */
 
 #define HOST_INSTRUCTION(v1, v2) \
@@ -201,5 +203,39 @@ static inline int host_request_exec_env(char* buffer, int max_buffer_size){
 
     return ret;
 }
+
+/**
+ * Copies the argument list for a file execution operation into a buffer.
+ * :arg buffer: The output buffer in which the argument list will be copied.
+ * :arg max_buffer_size: The size of the output buffer.
+ * :returns: The length of the copied data.
+ */
+static inline int host_request_exec_args_linux(char* buffer, int max_buffer_size){
+    int ret;
+    memset(buffer, 0, max_buffer_size);
+    __asm__ __volatile__(
+        HOST_INSTRUCTION(0x20, 0x03) : "=a" (ret) : 
+            "a" (buffer), "b" (max_buffer_size));
+
+    return ret;
+}
+
+/**
+ * Copies the env variable list for a file execution operation into a buffer.
+ * :arg buffer: The output buffer in which the env variable list will be copied.
+ * :arg max_buffer_size: The size of the output buffer.
+ * :returns: The length of the copied data.
+ */
+static inline int host_request_exec_env_linux(char* buffer, int max_buffer_size){
+
+    int ret;
+    memset(buffer, 0, max_buffer_size);
+    __asm__ __volatile__(
+        HOST_INSTRUCTION(0x20, 0x04) : "=a" (ret) : 
+            "a" (buffer), "b" (max_buffer_size));
+
+    return ret;
+}
+
 
 #endif

guest/linux/Makefile

@@ -0,0 +1,75 @@
+# -------------------------------------------------------------------------------
+#
+#   Copyright (C) 2017 Cisco Talos Security Intelligence and Research Group
+#
+#   PyREBox: Python scriptable Reverse Engineering Sandbox
+#   Author: Jonas Zaddach
+#   Author: Xabier Ugarte-Pedrero
+#
+#   This program is free software; you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License version 2 as
+#   published by the Free Software Foundation.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program; if not, write to the Free Software
+#   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#   MA 02110-1301, USA.
+#
+# -------------------------------------------------------------------------------
+
+# CONFIGURATION PAMATERS
+# ......................
+
+# BUFFER_SIZE: Guest agent buffer size used to copy data back and forth
+# AGENT_NAME: Base of the file name of the generated guest agent binaries
+#             (and their corresponding configuration files.
+
+BUFFER_SIZE := 4096
+
+AGENT_NAME := linux_agent
+
+#--------------------------------------------------------------------------------
+
+CC := gcc
+CC32 := gcc
+CC64 := gcc
+
+CFLAGS_32 := -Iinclude/ -I../include -g -O0 -m32
+CFLAGS_64 := -Iinclude/ -I../include -g -O0
+
+DEFINES := -DMAX_BUFFER_SIZE=$(BUFFER_SIZE)
+
+all: $(AGENT_NAME)_32 $(AGENT_NAME)_64
+
+32bit_test: test.c
+	$(CC32) $(CFLAGS_32) $(DEFINES) -c -o test_32.o $<
+	$(CC32) -m32 test_32.o -o test_32
+
+64bit_test: test.c
+	$(CC64) $(CFLAGS_64) $(DEFINES) -c -o test_64.o $<
+	$(CC64)  test_64.o -o test_64
+
+%_32: guest_agent_32.o
+	$(CC32) -m32  $^ -o $@
+	AGENT_NAME=$@ BUFFER_SIZE=$(BUFFER_SIZE) bash ./configure_offsets.sh
+%_64: guest_agent_64.o 
+	$(CC64)  $^ -o $@
+	AGENT_NAME=$@ BUFFER_SIZE=$(BUFFER_SIZE) bash ./configure_offsets.sh
+
+%_32.o: %.c
+	$(CC32) $(CFLAGS_32) $(DEFINES) -c -o $@ $<
+%_64.o: %.c
+	$(CC64) $(CFLAGS_64) $(DEFINES) -DPYREBOX_GUEST_64 -c -o $@ $<
+
+.PHONY: clean dist-clean 
+clean:
+	rm -f $(AGENT_NAME)_32
+	rm -f $(AGENT_NAME)_64
+	rm -f *.o
+	rm -f test_32
+	rm -f test_64

guest/linux/README.rst

@@ -0,0 +1,56 @@
+Compiling guest agent
+=====================
+
+Just compile with ``make``. 
+
+You may need to install the following packages. For example, on Ubuntu, or Debian:
+::
+  apt-get install libc6-dev-i386
+
+Compiling test files
+====================
+
+In order to compile the test files, just use the provided Makefile as follows:
+::
+  make test_32
+  make test_64
+
+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 configuration of guest agent in pyrebox.conf:
+::
+  [AGENT]
+  name: linux_agent_64
+  conf: linux_agent_64.conf
+
+
+Using guest_agent
+=================
+
+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 with ``from plugins.guest_agent import guest_agent`` in your script.
+- Interact with the guest agent using the public interface of this class (agent is 
+  a singleton instance of GuestAgentPlugin).
+
+In the IPython shell:
+
+- If no script is loading 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.

guest/linux/configure_offsets.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# -------------------------------------------------------------------------------
+#
+#   Copyright (C) 2017 Cisco Talos Security Intelligence and Research Group
+#
+#   PyREBox: Python scriptable Reverse Engineering Sandbox
+#   Author: Jonas Zaddach
+#   Author: Xabier Ugarte-Pedrero
+#
+#   This program is free software; you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License version 2 as
+#   published by the Free Software Foundation.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program; if not, write to the Free Software
+#   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#   MA 02110-1301, USA.
+#
+# -------------------------------------------------------------------------------
+
+#This script extracts the relative position of the global buffer named agent_buffer
+#that is used to copy data back and forth between the host and the guest, as well
+#as its size (that is configured in the Makefile).
+
+#This approach allows the pyrebox guest_agent plugin to check the boundaries of the buffer
+#before each write operation in order to prevent overflows and arbitrary memory writes.
+
+echo "[BUFFER]" > ../../${AGENT_NAME}.conf
+echo "BufferOffset: " $((16#`nm ${AGENT_NAME} | grep "agent_buffer" | awk '{ print $1 }'`)) >> ../../${AGENT_NAME}.conf
+echo "BufferSize: " ${BUFFER_SIZE} >> ../../${AGENT_NAME}.conf