Merge branch 'master' of https://github.com/memflow/memflow-py

Author: emesare

examples/jupyter_tutorial.ipynb

@@ -71,7 +71,85 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "conn = inventory.connector(\"kvm\", \":win11:\")\n"
+    "connector = inventory.create_connector(name=\"kvm\", args=\":win11:\")"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "bb246aa8",
+   "metadata": {},
+   "source": [
+    "Without the `target` argument the kvm connector will just pick the first virtual machine it finds. It is also possible on some connectors to retrieve a list of all available targets (whereas the resulting `name` is the name of the target):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "760b6687",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "inventory.connector_target_list(\"qemu\")"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "150e13f0",
+   "metadata": {},
+   "source": [
+    "It is also possible to retrieve a Help-Text for Plugins, this is especially useful when writing CLI applications:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 19,
+   "id": "7c2d9f98",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'The `qemu` connector implements a memflow plugin interface\\nfor QEMU on top of the Process Filesystem on Linux.\\n\\nThis connector requires access to the qemu process via the linux procfs.\\nThis means any process which loads this connector requires\\nto have at least ptrace permissions set.\\n\\nThe `target` argument specifies the target qemu virtual machine.\\nThe qemu virtual machine name can be specified when starting qemu with the -name flag.\\n\\nAvailable arguments are:\\nmap_base: override of VM memory base\\nmap_size: override of VM memory size'"
+      ]
+     },
+     "execution_count": 19,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "inventory.connector_help(\"qemu\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "id": "e7f09308",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "ERROR memflow.error 2022-12-18 21:00:09,824 error.rs:31 connector: not supported (Os-Plugin `win32` does not support help text.)\n"
+     ]
+    },
+    {
+     "ename": "Exception",
+     "evalue": "connector: not supported",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mException\u001b[0m                                 Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn[20], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m inventory\u001b[39m.\u001b[39;49mos_help(\u001b[39m\"\u001b[39;49m\u001b[39mwin32\u001b[39;49m\u001b[39m\"\u001b[39;49m)\n",
+      "\u001b[0;31mException\u001b[0m: connector: not supported"
+     ]
+    }
+   ],
+   "source": [
+    "inventory.os_help(\"win32\")"
    ]
   },
   {
@@ -80,7 +158,7 @@
    "id": "2c510e26",
    "metadata": {},
    "source": [
-    "The next step is to utilize the previously created connector to initialize an OS. In the given example we try to find Windows running in memory. "
+    "The previously created connector can now be utilized to initialize an Os. In the given example we try to find Windows running in memory in the KVM Virtual Machine."
    ]
   },
   {
@@ -90,7 +168,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "os = inventory.os(\"win32\", conn)"
+    "os = inventory.create_os(name=\"win32\", input=connector)"
    ]
   },
   {
@@ -112,8 +190,17 @@
     "from pprint import pprint\n",
     "\n",
     "drivers = os.module_info_list()\n",
-    "for driver in drivers: # TODO: implement str for module list\n",
-    "    pprint(driver.name)"
+    "pprint(drivers)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "88aa478d-d24c-46d0-b419-3310663834fd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "kernel = os # TODO:"
    ]
   },
   {
@@ -128,14 +215,22 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "88aa478d-d24c-46d0-b419-3310663834fd",
+   "id": "0dc364fa",
    "metadata": {},
    "outputs": [],
    "source": [
-    "kernel = os # TODO:\n",
     "process = os.process_from_name(\"explorer.exe\")"
    ]
   },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "d0ef57bf",
+   "metadata": {},
+   "source": [
+    "A Process also features the same functions for retrieving modules:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -145,10 +240,17 @@
    "source": [
     "from pprint import pprint\n",
     "\n",
-    "# List all modules in the process:\n",
     "modules = process.module_info_list()\n",
-    "for mod in modules: # TODO: implement str for module list\n",
-    "    pprint(mod.name)"
+    "pprint(modules)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "9194330f",
+   "metadata": {},
+   "source": [
+    "It is also possible to get a module by it's name:"
    ]
   },
   {
@@ -158,10 +260,18 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Load module 'Explorer.EXE':\n",
     "module = process.module_from_name(\"Explorer.EXE\")"
    ]
   },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "b612a8d1",
+   "metadata": {},
+   "source": [
+    "Finally we are able to read Data from the process/module. In the following example we read parts of the COFF Header from the PE Header of the primary module:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -187,7 +297,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },

src/inventory.rs

@@ -165,6 +165,10 @@ impl PyTargetInfo {
     fn __str__(&self) -> String {
         format!("{:?}", self.0)
     }
+
+    fn __repr__(&self) -> String {
+        format!("{:?}", self.0)
+    }
 }
 
 impl From<TargetInfo> for PyTargetInfo {

src/process.rs

@@ -78,6 +78,10 @@ impl PyProcess {
     fn __str__(&self) -> String {
         self.info().__str__()
     }
+
+    fn __repr__(&self) -> String {
+        format!("{:?}", self.0.info())
+    }
 }
 
 #[derive(Clone)]
@@ -166,6 +170,10 @@ impl PyProcessInfo {
     fn __str__(&self) -> String {
         format!("{} ({}) @ {:#04x}", self.name(), self.pid(), self.address())
     }
+
+    fn __repr__(&self) -> String {
+        format!("{:?}", self.0)
+    }
 }
 
 impl From<ProcessInfo> for PyProcessInfo {
@@ -263,6 +271,10 @@ impl PyModuleInfo {
     fn __str__(&self) -> String {
         format!("{} @ {:#04x}", self.name(), self.base())
     }
+
+    fn __repr__(&self) -> String {
+        format!("{:?}", self.0)
+    }
 }
 
 impl From<ModuleInfo> for PyModuleInfo {