Document Register API (#6)

* Document all the functions in register api

* Fix examples in Zelos

* Update gitignore with copied README in docs

* Update syscall limiter plugin

Author: archived-c

.gitignore

@@ -59,6 +59,7 @@ __pycache__/
 /docs/_build/
 /docs/api/
 /docs/log.txt
+/docs/README.md
 
 # PyBuilder
 /target/

docs/README.md

@@ -55,21 +55,54 @@ def __setattr__(self, attr, value):
         self._current_thread.set_reg(attr, value)
 
     def getIP(self) -> int:
+        """
+        Returns the platform-agnostic instruction pointer. On x86, this
+        returns the value of the EIP register. On ARM, this returns the
+        value of register R15. On MIPS, this returns the value of the
+        PC register.
+        """
         return self._current_thread.getIP()
 
     def setIP(self, new_ip: int) -> None:
+        """
+        Sets the instruction pointer. On x86, this sets the value of the
+        EIP register. On ARM, this sets the value of register R15. On
+        MIPS this sets the value of the PC register.
+        """
         self._current_thread.setIP(new_ip)
 
     def getSP(self) -> int:
+        """
+        Returns the platform-agnostic stack pointer. On x86, this
+        returns the value of the ESP register. On ARM, this returns the
+        value of register R13. On MIPS, this returns the value of the
+        SP register.
+        """
         return self._current_thread.getSP()
 
     def setSP(self, new_sp: int) -> None:
+        """
+        Sets the stack pointer. On x86, this sets the value of the
+        ESP register. On ARM, this sets the value of register R13. On
+        MIPS this sets the value of the SP register.
+        """
         self._current_thread.setSP(new_sp)
 
     def getFP(self) -> int:
+        """
+        Returns the platform-agnostic frame pointer. On x86, this
+        returns the value of the EBP register. On ARM, this returns the
+        value of register R11. On MIPS, this returns the value of
+        register $30.
+        """
         return self._current_thread.getFP()
 
     def setFP(self, new_fp: int) -> None:
+        """
+        Sets the frame pointer. On x86, this sets the value of the
+        EBP register. On ARM, this sets the value of register R11. On
+        MIPS this sets the value of register $30.
+        """
         return self._current_thread.setFP(new_fp)
 
     def getstack(self, offset: int) -> int:
@@ -87,7 +120,13 @@ def setstack(self, offset: int, val: int) -> None:
         self._current_thread.setstack(offset, val)
 
     def popstack(self) -> int:
+        """
+        Pop an item from the top of the stack.
+        """
         return self._current_thread.popstack()
 
     def pushstack(self, data: int) -> None:
+        """
+        Push an item to the top of the stack.
+        """
         return self._current_thread.pushstack(data)

src/zelos/api/regs_api.py

@@ -185,7 +185,7 @@ def hook_execution(
                 def exec_hook(zelos, address, size):
                     print(address)
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
                 z.hook_execution(
                     HookType.EXEC.BLOCK, exec_hook
                 )
@@ -219,7 +219,7 @@ def hook_close(self, closure: Callable[[], Any]) -> HookInfo:
                 def close_cleanup():
                     file.close()
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
                 z.hook_close(close_cleanup)
                 z.start()
 
@@ -258,7 +258,7 @@ def hook_syscalls(
                 def syscall_hook(zelos, sys_name, args, ret_val):
                     syscall_return_values.append((sys_name, ret_val))
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
                 z.hook_syscalls(
                     HookType.SYSCALL.AFTER, syscall_hook
                 )
@@ -289,7 +289,7 @@ def start(self, timeout: float = 0) -> None:
 
                 from zelos import Zelos
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
 
                 # Start execution from the entry point
                 z.start()
@@ -365,7 +365,7 @@ def set_breakpoint(self, address: int, temporary: bool = False):
 
                 from zelos import Zelos
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
 
                 z.set_breakpoint(0xdeadbeef)
 
@@ -401,7 +401,7 @@ def remove_breakpoint(self, address: int):
 
                 from zelos import Zelos
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
 
                 z.set_breakpoint(0xdeadbeef)
 
@@ -425,7 +425,7 @@ def set_syscall_breakpoint(self, syscall_name: str):
 
                 from zelos import Zelos
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
 
                 z.set_syscall_breakpoint("write")
 
@@ -446,7 +446,7 @@ def remove_syscall_breakpoint(self, syscall_name: str):
 
                 from zelos import Zelos
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
 
                 z.set_syscall_breakpoint("write")
 
@@ -477,7 +477,7 @@ def set_watchpoint(
 
                 from zelos import Zelos
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
 
                 # Break at any read or write to memory address 0xdeadbeef
                 z.set_watchpoint(0xdeadbeef, True, True)
@@ -530,7 +530,7 @@ def remove_watchpoint(self, address: int):
 
                 from zelos import Zelos
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
 
                 z.set_watchpoint(0xdeadbeef, True, True)
 
@@ -574,7 +574,7 @@ def date(self, date_str: str):
 
                 from zelos import Zelos
 
-                z = ("binary_to_emulate")
+                z = Zelos("binary_to_emulate")
 
                 z.date = "2020-03-04"
 

src/zelos/api/zelos_api.py

@@ -62,7 +62,7 @@ def _syscall_callback(self, zelos, sysname, args, retval):
         if zelos.thread is None:
             return
 
-        thread_name = zelos.internal_engine.current_thread.name
+        thread_name = zelos.thread.name
 
         self.syscall_cnt += 1
         self.syscall_thread_cnt[thread_name] += 1