From 80596afdd3cd9337f44648e1a26da00356c69ba6 Mon Sep 17 00:00:00 2001 From: Loic Jaquemet Date: Sun, 25 Jun 2017 17:33:27 -0600 Subject: [PATCH] a bit better readme --- README.rst | 58 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/README.rst b/README.rst index b299dd3..975acf0 100644 --- a/README.rst +++ b/README.rst @@ -14,7 +14,7 @@ Introduction: python-haystack-reverse is extension of `python-haystack `_ focused on reversing memory structure in allocated memory. - - It aims at helping an analyst in reverse engineering the memory records types present in a process heap. +It aims at helping an analyst in reverse engineering the memory records types present in a process heap. It focuses on reconstruction, classification of classic C structures from memory. It attempts to recreate types definition. @@ -23,19 +23,19 @@ Scripts & Entry Points: A few entry points exists to handle the format your memory dump. -Memory dump folder produced by `haystack-live-dump` from the haystack package ------------------------------------------------------------------------------ - - `haystack-reverse` reverse CLI - reverse all allocation chunks - - `haystack-reverse-show` show the reversed record at a specific address - - `haystack-reverse-hex` show a specific record hex bytes at a specific address - - `haystack-reverse-parents` show the records pointing to the allocated record at a specific address +Memory dump folder produced by ``haystack-live-dump`` from the haystack package +------------------------------------------------------------------------------- + - ``haystack-reverse`` reverse CLI - reverse all allocation chunks + - ``haystack-reverse-show`` show the reversed record at a specific address + - ``haystack-reverse-hex`` show a specific record hex bytes at a specific address + - ``haystack-reverse-parents`` show the records pointing to the allocated record at a specific address Memory dump file produced by a Minidump tool -------------------------------------------- - - `haystack-minidump-reverse` reverse CLI - reverse all allocation chunks - - `haystack-minidump-reverse-show` show the reversed record at a specific address - - `haystack-minidump-reverse-hex` show a specific record hex bytes at a specific address - - `haystack-minidump-reverse-parents` show the records pointing to the allocated record at a specific address + - ``haystack-minidump-reverse`` reverse CLI - reverse all allocation chunks + - ``haystack-minidump-reverse-show`` show the reversed record at a specific address + - ``haystack-minidump-reverse-hex`` show a specific record hex bytes at a specific address + - ``haystack-minidump-reverse-parents`` show the records pointing to the allocated record at a specific address How to get a memory dump: ========================= @@ -46,42 +46,44 @@ Heap analysis / forensics: ========================== Quick info: - - The `haystack-xxx-reverse` family of entry points parse the heap for - allocator structures, pointers values, small integers and text (ascii/utf). - Given all the previous information, it can extract instances and helps you - in classifying and defining structures types. + - The ``haystack-xxx-reverse`` family of entry points parse the heap for allocator structures, +pointers values, small integers and text (ascii/utf). +Given all the previous information, it can extract instances and helps you +in classifying and defining structures types. IPython notebook usage guide: - - [Haystack-reverse CLI](docs/Haystack reverse CLI.ipynb) in the docs/ folder. + - `Haystack-reverse CLI `_ in the docs/ folder. Command line example: --------------------_ -The first step is to launch the analysis process with the `haystack-xxx-reverse` entry point. -This will create several files in the `cache/` folder in the memory dump folder: +The first step is to launch the analysis process with the ``haystack-xxx-reverse`` entry point. +This will create several files in the ``cache/`` folder in the memory dump folder: + +.. code-block:: bash $ haystack-reverse haystack/test/src/test-ctypes6.64.dump $ ls -l haystack/test/src/test-ctypes6.64.dump/cache $ ls -l haystack/test/src/test-ctypes6.64.dump/cache/structs -This will create a few files. The most interesting one being the `/cache/xxxxx.headers_values.py` that +This will create a few files. The most interesting one being the ``/cache/xxxxx.headers_values.py`` that gives you an ctypes listing of all found structures, with guesstimates on fields types. -A `/cache/graph.gexf` file is also produced to help you visualize +A ``/cache/graph.gexf`` file is also produced to help you visualize instances links. It gets messy for any kind of serious application. -- `*.headers_values.py` contains the list of heuristicly reversed record types. -- `*.strings` contains the list of heuristicly typed strings field in reversed record. +- ``*.headers_values.py`` contains the list of heuristicly reversed record types. +- ``*.strings`` contains the list of heuristicly typed strings field in reversed record. Other Entry points for reversing: --------------------------------- - - `haystack-reverse-show` show a specific record at a specific address - - `haystack-reverse-hex` show a specific record hex bytes at a specific address - - `haystack-reverse-parents` show the records pointing to the allocated record at a specific address - - `haystack-minidump-reverse-show` show a specific record at a specific address - - `haystack-minidump-reverse-hex` show a specific record hex bytes at a specific address - - `haystack-minidump-reverse-parents` show the records pointing to the allocated record at a specific address + - ``haystack-reverse-show`` show a specific record at a specific address + - ``haystack-reverse-hex`` show a specific record hex bytes at a specific address + - ``haystack-reverse-parents`` show the records pointing to the allocated record at a specific address + - ``haystack-minidump-reverse-show`` show a specific record at a specific address + - ``haystack-minidump-reverse-hex`` show a specific record hex bytes at a specific address + - ``haystack-minidump-reverse-parents`` show the records pointing to the allocated record at a specific address Dependencies: