Skip to content

Commit

Permalink
Added reference to InfinityHook + fixed a bunch of broken links
Browse files Browse the repository at this point in the history
  • Loading branch information
MarioVilas committed Aug 28, 2019
1 parent 0841211 commit 673ace8
Show file tree
Hide file tree
Showing 10 changed files with 18 additions and 33 deletions.
14 changes: 5 additions & 9 deletions doc/source/Debugging.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ Example #1: starting a new process and waiting for it to finish

.. literalinclude:: ../../examples/debugging/01_start.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

Example #2: attaching to a process and waiting for it to finish
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Expand All @@ -35,7 +34,6 @@ Example #2: attaching to a process and waiting for it to finish

.. literalinclude:: ../../examples/debugging/02_attach.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

Example #3: attaching to a process by filename
++++++++++++++++++++++++++++++++++++++++++++++
Expand All @@ -44,7 +42,6 @@ Example #3: attaching to a process by filename

.. literalinclude:: ../../examples/debugging/03_find_and_attach.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

Example #4: killing the debugged process when the debugger is closed
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Expand All @@ -53,7 +50,6 @@ Example #4: killing the debugged process when the debugger is closed

.. literalinclude:: ../../examples/debugging/04_kill_on_exit.py
:start-after: from __future__ import with_statement
:end-before: # When invoked from the command line,

.. _the-interactive-debugger:

Expand Down Expand Up @@ -222,7 +218,7 @@ Crashes are exceptions a program can't recover from (also known as second-chance

Now, the next step would be storing the crash dump somewhere for later examination. The most crude way to do this is using the standard `pickle <https://docs.python.org/2/library/pickle.html>`_ module, or similar modules like `cerealizer <https://pypi.org/project/Cerealizer/>`_. This is easy and guaranteed to work, but not very comfortable! Crash dumps stored that way are hard to read outside Python.

A more flexible way to store crash dumps is using the *CrashDAO* class. It uses `SQLAlchemy <http://www.sqlalchemy.org/>`_ to connect to any supported SQL database, create the required tables if needed, and store multiple crash dumps in it. This is the preferred method, since it's easier to access and manipulate the information outside Python, and you can store crashes from multiple machines into the same database.
A more flexible way to store crash dumps is using the *CrashDAO* class. It uses `SQLAlchemy <https://www.sqlalchemy.org/>`_ to connect to any supported SQL database, create the required tables if needed, and store multiple crash dumps in it. This is the preferred method, since it's easier to access and manipulate the information outside Python, and you can store crashes from multiple machines into the same database.

Old versions of **WinAppDbg** (1.4 and older) supported DBM databases through the *CrashContainer* class, SQLite databases with the *CrashTable* class, and SQL Server databases with the *CrashTableMSSQL* class. They are now deprecated and, while still present for backwards compatibility (for the time being) its use is not recommended.

Expand Down Expand Up @@ -331,11 +327,11 @@ These are the most important exception notification methods:
+----------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **ms_vc_exception** | A C++ exception was raised by the debugee. | When the debuggee calls RaiseException() with a custom exception code. This is what the implementation of throw() of the Visual Studio runtime does. |
+----------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **breakpoint** | A breakpoint exception was raised by the debugee. | When a hardware fault is triggered by the `int3 opcode <http://en.wikipedia.org/wiki/INT_(x86_instruction)#INT_3>`_, when the process calls `DebugBreak() <http://msdn.microsoft.com/en-us/library/ms679297(VS.85).aspx>`_, or when a code breakpoint set by your program is triggered. |
| **breakpoint** | A breakpoint exception was raised by the debugee. | When a hardware fault is triggered by the `int3 opcode <https://en.wikipedia.org/wiki/INT_(x86_instruction)#INT3>`_, when the process calls `DebugBreak() <http://msdn.microsoft.com/en-us/library/ms679297(VS.85).aspx>`_, or when a code breakpoint set by your program is triggered. |
+----------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **single_step** | A single step exception was raised by the debugee. | When a hardware fault is triggered by the `trap flag <http://maven.smith.edu/~thiebaut/ArtOfAssembly/CH17/CH17-2.html#HEADING2-10>`_ or the `icebp opcode <http://www.rcollins.org/secrets/opcodes/ICEBP.html>`_, or when a hardware breakpoint set by your program is triggered. |
+----------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **guard_page** | A guard page exception was raised by the debugee. | When a `guard page <http://msdn.microsoft.com/en-us/library/aa366549(VS.85).aspx>`_ is hit or when a page breakpoint set by your program is triggered. |
| **guard_page** | A guard page exception was raised by the debugee. | When a `guard page <https://docs.microsoft.com/es-es/windows/win32/memory/creating-guard-pages>`_ is hit or when a page breakpoint set by your program is triggered. |
+----------------------+----------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. only:: latex
Expand All @@ -356,7 +352,7 @@ These are the most important exception notification methods:

*What does it mean?*: A breakpoint exception was raised by the debugee.

*When is it received?*: When a hardware fault is triggered by the `int3 opcode <http://en.wikipedia.org/wiki/INT_(x86_instruction)#INT_3>`_, when the process calls `DebugBreak() <http://msdn.microsoft.com/en-us/library/ms679297(VS.85).aspx>`_, or when a code breakpoint set by your program is triggered.
*When is it received?*: When a hardware fault is triggered by the `int3 opcode <https://en.wikipedia.org/wiki/INT_(x86_instruction)#INT3>`_, when the process calls `DebugBreak() <http://msdn.microsoft.com/en-us/library/ms679297(VS.85).aspx>`_, or when a code breakpoint set by your program is triggered.

**single_step**:

Expand All @@ -368,7 +364,7 @@ These are the most important exception notification methods:

*What does it mean?*: A guard page exception was raised by the debugee.

*When is it received?*: When a `guard page <http://msdn.microsoft.com/en-us/library/aa366549(VS.85).aspx>`_ is hit or when a page breakpoint set by your program is triggered.
*When is it received?*: When a `guard page <https://docs.microsoft.com/es-es/windows/win32/memory/creating-guard-pages>`_ is hit or when a page breakpoint set by your program is triggered.

In addition to all this, the *EventHandler* class provides a simple method for API hooking: the **apiHooks** class property. This property is a dictionary of tuples, specifying which API calls to hook on what DLL libraries, and what parameters does each call take (using ctypes definitions). That's it! The *EventHandler* class will automatically hooks this APIs for you when the corresponding library is loaded, and a method of your subclass will be called when entering and leaving the API function.

Expand Down
8 changes: 4 additions & 4 deletions doc/source/Downloads.rst
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Debugging Symbols
Database storage
++++++++++++++++

The `SQL Alchemy <http://www.sqlalchemy.org/>`_ ORM module gives *WinAppDbg* the ability to use a SQL database to store and find crash dumps. Most major database engines are supported.
The `SQL Alchemy <https://www.sqlalchemy.org/>`_ ORM module gives *WinAppDbg* the ability to use a SQL database to store and find crash dumps. Most major database engines are supported.

Other goodies
+++++++++++++
Expand All @@ -95,7 +95,7 @@ You can also install WinAppDbg (stable versions only) from the `Cheese Shop <htt

pip install winappdbg

* `PyPM <https://code.activestate.com/pypm/search%3Awinappdbg/>`_ (only when using `ActivePython <https://www.activestate.com/activepython>`_)
* `PyPM <https://code.activestate.com/pypm/search%3Awinappdbg/>`_ (only when using `ActivePython <https://www.activestate.com/products/activepython/>`_)

* Easy Install (formerly from `Setuptools <https://pypi.org/project/setuptools>`_, now from `Distribute <https://pypi.org/project/distribute/>`_) ::

Expand All @@ -122,7 +122,7 @@ It might work, but was not tested, under *Windows 2000*, *Wine* and *ReactOS*, a

Python 3 support was experimental up to *WinAppDbg 1.4*, and was dropped with *WinAppDbg 1.5*. There are currently no plans to support Python 3 in the near future - backwards compatibility would be broken and plenty of code would need to be refactored just to port it.

While there are still some issues that need ironing out, it may be worth trying out faster Python interpreters such as `PyPy <https://bitbucket.org/pypy/pypy/downloads/>`_ and `IronPython <http://ironpython.net/download/>`_.
While there are still some issues that need ironing out, it may be worth trying out faster Python interpreters such as `PyPy <https://bitbucket.org/pypy/pypy/downloads/>`_ and `IronPython <https://ironpython.net/download/>`_.

If you find a bug or have a feature suggestion, don't hesitate to `open a new issue <https://github.com/MarioVilas/winappdbg/issues>`_. Both comments and complaints are welcome! :)

Expand Down Expand Up @@ -150,7 +150,7 @@ Python interpreters
| IronPython 2.0 and newer | *experimental* | Some compatibility issues need fixing. |
+--------------------------+-----------------+----------------------------------------------------------------+
| Jython 2.5 and earlier | *not supported* | Support for ctypes is |
| | | `incomplete <http://bugs.jython.org/issue1328>`_ |
| | | `incomplete <https://bugs.jython.org/issue2148>`_ |
| | | in this platform. |
+--------------------------+-----------------+----------------------------------------------------------------+

Expand Down
2 changes: 1 addition & 1 deletion doc/source/Helpers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -386,4 +386,4 @@ Example #5: pathname and filename handling

.. literalinclude:: ../../examples/helpers/05_path.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

6 changes: 3 additions & 3 deletions doc/source/HowBreakpointsWork.rst
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Similarly, page breakpoints are defined by **define_page_breakpoint**, hardware
Code breakpoints
++++++++++++++++

*Code* breakpoints are implemented by inserting an `int3 instruction <https://en.wikipedia.org/wiki/INT_(x86_instruction)#INT_3>`_ (\xCC) at the address specified. When a thread tries to execute this instruction, a breakpoint exception is generated. It's global to the process because it overwrites the code to break at.
*Code* breakpoints are implemented by inserting an `int3 instruction <https://en.wikipedia.org/wiki/INT_(x86_instruction)#INT3>`_ (\xCC) at the address specified. When a thread tries to execute this instruction, a breakpoint exception is generated. It's global to the process because it overwrites the code to break at.

When hit, code breakpoints trigger a **breakpoint** event at your :ref:`event handler <the-eventhandler-class>`.

Expand All @@ -38,7 +38,7 @@ Where **dwProcessId** is the Id of the process where we want to set the breakpoi
Page breakpoints
++++++++++++++++

*Page* breakpoints are implemented by changing the `access permissions <https://msdn.microsoft.com/en-us/library/aa366899(VS.85).aspx>`_ of a given memory page. This causes a guard page exception to be generated when the given page is accessed anywhere in the code of the process.
*Page* breakpoints are implemented by changing the `access permissions <https://docs.microsoft.com/en-us/windows/win32/api/memoryapi/nf-memoryapi-virtualprotectex>`_ of a given memory page. This causes a guard page exception to be generated when the given page is accessed anywhere in the code of the process.

When hit, page breakpoints trigger a **guard_page** event at your :ref:`event handler <the-eventhandler-class>`.

Expand All @@ -48,7 +48,7 @@ Let's see the signature of *define_page_breakpoint*:
:start-after: # Page breakpoints.
:end-before: """

Where **dwProcessId** is the same. But now **address** needs to be page-aligned and **pages** is the number of pages covered by the breakpoint. This is because `VirtualProtectEx() <https://msdn.microsoft.com/en-us/library/aa366899(VS.85).aspx>`_ works only with entire pages, you can't change the access permissions on individual bytes.
Where **dwProcessId** is the same. But now **address** needs to be page-aligned and **pages** is the number of pages covered by the breakpoint. This is because `VirtualProtectEx() <https://docs.microsoft.com/en-us/windows/win32/api/memoryapi/nf-memoryapi-virtualprotectex>`_ works only with entire pages, you can't change the access permissions on individual bytes.

.. _hardware-breakpoints:

Expand Down
2 changes: 1 addition & 1 deletion doc/source/HowLabelsWork.rst
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Where all components are optional and blank spaces are ignored.
* The **ordinal** is an integer with an exported function ordinal.
* The **offset** is an integer number. It may be an offset from the module base address, or the function address. If not specified, the default is *0*.

If debugging symbols are available, they are used automatically in addition to exported functions. To get the debugging symbols you need to first install the `Microsoft Debugging Tools <https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/>`_, and then either install the debugging symbols for your version of Windows or set up your system to connect to the `Microsoft Symbol Server <https://msdn.microsoft.com/en-us/library/windows/desktop/ee416588(v=vs.85).aspx#using_the_microsoft_symbol_server>`_.
If debugging symbols are available, they are used automatically in addition to exported functions. To get the debugging symbols you need to first install the `Microsoft Debugging Tools <https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/>`_, and then either install the debugging symbols for your version of Windows or set up your system to connect to the `Microsoft Symbol Server <https://docs.microsoft.com/es-es/windows/win32/dxtecharts/debugging-with-symbols#using-the-microsoft-symbol-server>`_.

Integer numbers in labels may be expressed in any format supported by HexInput.integer(), but by default they are in hexadecimal format (for example *0x1234*).

Expand Down
3 changes: 0 additions & 3 deletions doc/source/Instrumentation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,6 @@ Example #1: knowing on which platform we're running

.. literalinclude:: ../../examples/instrumentation/01_platform.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

Example #2: enumerating running processes
+++++++++++++++++++++++++++++++++++++++++
Expand All @@ -36,7 +35,6 @@ Example #2: enumerating running processes

.. literalinclude:: ../../examples/instrumentation/02_show_processes.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

Example #3: starting a new process
++++++++++++++++++++++++++++++++++
Expand All @@ -45,7 +43,6 @@ Example #3: starting a new process

.. literalinclude:: ../../examples/instrumentation/03_start.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

The *System* class has many more features, so we'll be coming back to it later on in the tutorial.

Expand Down
4 changes: 0 additions & 4 deletions doc/source/MoreExamples.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ Sometimes you'll want to set a maximum time to debug your target, especially whe

.. literalinclude:: ../../examples/miscellaneous/01_debug_timeout.py
:start-after: from __future__ import with_statement
:end-before: # When invoked from the command line,

.. _memory-dump:

Expand All @@ -27,7 +26,6 @@ This is an example on how to dump the memory map and contents of a process into

.. literalinclude:: ../../examples/miscellaneous/02_memory_dump.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

.. _find-alnum:

Expand Down Expand Up @@ -57,7 +55,6 @@ This example shows all 32 bits processes the current user has permission to acce

.. literalinclude:: ../../examples/miscellaneous/04_dep.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

.. _disassembler:

Expand All @@ -72,7 +69,6 @@ This example shows you how to list the supported disassembler engines for the de

.. literalinclude:: ../../examples/miscellaneous/05_disasm.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

.. _atoms:

Expand Down
4 changes: 0 additions & 4 deletions doc/source/Tools.rst
Original file line number Diff line number Diff line change
Expand Up @@ -72,10 +72,6 @@ These tools were inspired by the **ptools** suite by `Nicolás Economou <https:/

Terminates a process or a batch of processes.

* :download:`pstrings.py <../../tools/pstrings.py>` :

Dumps all ASCII strings from a live process.

Miscellaneous
+++++++++++++

Expand Down
1 change: 0 additions & 1 deletion doc/source/Win32APIWrappers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,6 @@ Example #1: finding a DLL in the search path

.. literalinclude:: ../../examples/win32_api_wrappers/01_search_path.py
:start-after: # POSSIBILITY OF SUCH DAMAGE.
:end-before: # When invoked from the command line,

Example #2: killing a process by attaching to it
++++++++++++++++++++++++++++++++++++++++++++++++
Expand Down

0 comments on commit 673ace8

Please sign in to comment.