Metadata-Version: 2.4
Name: divination
Version: 2.2.0
Summary: Python hardware inspection: PCI configuration, MSRs, MMIO, and Linux physical memory
Home-page: https://github.com/depletionmode/divination
Author: David Kaplan <@depletionmode>
Project-URL: Documentation, https://github.com/depletionmode/divination/blob/master/docs/usage.rst
Project-URL: Source, https://github.com/depletionmode/divination
Project-URL: Issues, https://github.com/depletionmode/divination/issues
Keywords: hardware-inspection,pci,msr,mmio,physical-memory,linux,windows,x86-64
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Hardware
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: pywin32; sys_platform == "win32"
Provides-Extra: examples
Requires-Dist: tqdm; extra == "examples"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

===============================================================
divination - platform, iospace and physmem inspection framework
===============================================================

.. image:: https://img.shields.io/pypi/v/divination.svg
        :target: https://pypi.python.org/pypi/divination

Overview
--------

*divination* is a python package that exposes a simple interface for transacting 
with physical memory and IO space - cross platform (currently Windows10 and Linux).

IO and physical memory regions are mapped into the python usermode process and are 
transacted directly using mmap on Linux and pywin32 on Windows.

Hardware operations require a resident kernel-mode driver; importing the module does not.
The driver is opened on first use, and errors propagate as Python exceptions.

Features
--------

* Reading PCI configuration space
* Reading and writing MSRs
* Mapping and RW from/to IO regions
* Mapping and RW from/to physical memory regions (Linux-only; Windows raises NotImplementedError)

Dependencies
------------

* Python 3.9+ on 64-bit x86 Linux or Windows, with 64-bit Python
* (Windows) pywin32
* (Linux) <none>

Installation
------------

Python module
^^^^^^^^^^^^^

The python module is available off PyPI:

    pip3 install divination

For the changes in this checkout, use ``pip3 install .`` and rebuild the matching
kernel driver; MSR writes require the updated driver.

Kernel module (Windows)
^^^^^^^^^^^^^^^^^^^^^^^

The WDM driver can be built by installing VS, SDK + WDK and
running msbuild under the `driver/win <driver/win>`_ directory from within the VS Developer 
Command Prompt.

Please **do not (non-test-)sign** this kernel module; we do not want to further enable attackers!
The driver must be test-signed because its process-exit cleanup requires ``/INTEGRITYCHECK``.
Enable testsigning to load the test-signed driver, subject to system signing policy:

    bcdedit /set testsigning on ; shutdown -f -t 0 -r

Kernel module (Linux)
^^^^^^^^^^^^^^^^^^^^^

The Linux kernel module can be built by running make under the `driver/linux <driver/linux>`_ directory.
The usual prerequisite dependencies (kernel headers, gcc, etc.) will need to be installed.

Usage
-----

There are currently 3 classes available: PciDevice, Msr and MemoryObject. 
Examples follow for usage of each.

See the `usage guide <docs/usage.rst>`_ for CLI commands, Python examples, setup and troubleshooting.

* PciDevice(bus, device, function)

    >>> amd_lpc = PciDevice(0, 0x14, 3)     # LPC Bridge @ D14F3
    >>> hexdump.hexdump(amd_lpc.read_cfg()) 
    00000000: 22 10 0E 79 0F 00 20 02  51 00 01 06 00 00 80 00  "..y.. .Q.......
    00000010: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    00000020: 00 00 00 00 00 00 00 00  00 00 00 00 62 14 37 7C  ............b.7|
    00000030: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    00000040: 04 00 00 00 40 C0 03 20  07 FF 20 03 00 00 00 00  ....@.. .. .....
    00000050: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    00000060: 00 00 00 00 40 16 00 0A  00 00 0F 00 00 FF FF FF  ....@...........
    00000070: 67 45 23 00 08 00 00 00  90 02 00 00 07 0A 00 00  gE#.............
    00000080: 08 00 03 A8 00 00 00 00  00 00 00 00 00 00 00 00  ................
    00000090: E0 03 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    000000A0: 02 00 C1 FE 2F 01 00 00  00 00 00 00 00 00 00 00  ..../...........
    000000B0: 00 00 00 00 00 00 00 00  04 00 E9 3F 00 00 00 00  ...........?....
    000000C0: 00 00 00 00 00 00 00 00  00 00 00 80 00 00 F7 FF  ................
    000000D0: 86 FF FD 08 42 00 00 00  00 00 00 00 00 00 00 00  ....B...........
    000000E0: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    000000F0: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................

* Msr(register)

  Use ``write(value)`` to write a 64-bit value. Reads and writes affect the CPU
  executing the driver request.

    >>> amd_hwcr = Msr(0xc0010015)
    >>> hex(amd_hwcr.read())   
    '0x89000111'

* MemoryObject(base_address, range, mem_type, alloc=False)

  Reads and writes must stay within the mapped range; slice assignment cannot
  resize it. Use ``close()`` or a ``with`` block to release the mapping.
  Physical memory allocation (``alloc=True``) is not supported.

    >>> spi_bar = MemoryObject(0xfec10000, 0x100, MemoryType.IoSpace)
    >>> hexdump.hexdump(spi_bar[0:])  # MemoryObjects are sliceable and can be read from + written to
    00000000: 05 21 CC 4F 00 00 00 00  00 00 00 00 6A 00 00 02  .!.O........j...
    00000010: 06 20 04 04 06 04 9F 05  03 0B 0A 02 FF 98 06 02  . ..............
    00000020: 13 07 33 10 08 20 20 20  0C 14 06 0E C0 54 C0 14  ..3..   .....T..
    00000030: C0 14 08 46 03 00 00 00  FC FC FC FC FC 88 00 00  ...F............
    00000040: 3B 6B BB EB 00 05 00 00  01 00 00 02 02 00 06 00  ;k..............
    00000050: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    00000060: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    00000070: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    00000080: 00 40 40 69 24 6A 4A 16  CA C5 EB 7B E2 95 09 4C  .@@i$jJ....{...L
    00000090: C8 AD 4A FC CB 1D 83 A9  C4 82 C1 D9 7E 35 F9 27  ..J.........~5.'
    000000A0: 92 8A 43 4B 78 D3 6B 04  9C B8 AF 79 8C 68 C6 E8  ..CKx.k....y.h..
    000000B0: 2E 24 04 68 F4 97 2A CC  83 74 C9 E2 17 C0 5A C7  .$.h..*..t....Z.
    000000C0: C7 C7 C7 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    000000D0: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    000000E0: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
    000000F0: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
