diff --git a/.readthedocs.yml b/.readthedocs.yml index 1d1677be..671a1ecb 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -17,3 +17,6 @@ python: path: . extra_requirements: - docs + +sphinx: + fail_on_warning: true diff --git a/README.md b/README.md index 58dc58fa..8112c378 100644 --- a/README.md +++ b/README.md @@ -95,9 +95,8 @@ There are several backends that can be used to load a single file: - PE is a backend to load Microsoft's Portable Executable format, effectively Windows binaries. It uses the (optional) `pefile` module. - - Mach-O is a backend to load, you guessed it, Mach-O binaries. It is - subject to several limitations, which you can read about in the - [readme in the macho directory](backends/macho/README.md) + - Mach-O is a backend to load, you guessed it, Mach-O binaries. Support is + limited for this backend. - Blob is a backend to load unknown data. It requires that you specify the architecture it would be run on, in the form of a class from diff --git a/cle/backends/macho/README.md b/cle/backends/macho/README.md deleted file mode 100644 index ec4c0730..00000000 --- a/cle/backends/macho/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Mach-O Support Notes and Caveats - -The Mach-O support provided by this contribution is considered experimental but stable. -It has been mainly tested with ARM64 Mach-O binaries and a few ARMv7 binaries. - -As of 14.12.2016 the system can be used to load both Mach-O executables as well as libraries. -However some caveats apply: - - -## CAVEATS -The following list of caveats may be incomplete, you have been warned: - -* Currently this system can load only ONE binary, i.e. loading a binary with all its dependencies is not possible. - * Consequently the relocation support is missing completely -* No rebasing support - * Mach-O rebasing requires involvement of the entire binary in order to interpret a linker script embedded in said binary. - * Currently the interface for binaries an CLE does not provide the required capabilities (turn `rebase_addr` into a property?) -* Not all fields are filled in accordance with Angr's expectations. - * Overall integration into Angr/CLE could be better -* PAGEZERO is not mapped to conserve memory - diff --git a/cle/backends/macho/macho.py b/cle/backends/macho/macho.py index f86ae762..3224ad58 100644 --- a/cle/backends/macho/macho.py +++ b/cle/backends/macho/macho.py @@ -71,20 +71,19 @@ def get_by_name_and_ordinal(self, name: str, ordinal: int, include_stab=False) - # pylint: enable =abstract-method - class MachO(Backend): """ Mach-O binaries for CLE + ----------------------- - The Mach-O format is notably different from other formats, as such: - * Sections are always part of a segment, self.sections will thus be empty - * Symbols cannot be categorized like in ELF - * Symbol resolution must be handled by the binary - * Rebasing in dyld is implemented via adding a small slide to addresses inside the binary, instead of - changing the base address of the binary and the addresses being relative. CLE needs relative addresses, - so there are a lot of AT.from_lva().to_rva() calls in this backend. + The Mach-O format is notably different from other formats. Specifically: - * ... + - Sections are always part of a segment, so `self.sections` will be empty. + - Symbols cannot be categorized like in ELF. + - Symbol resolution must be handled by the binary. + - Rebasing in dyld is implemented by adding a small slide to addresses inside the binary, instead of + changing the base address of the binary. Consequently, the addresses are absolute rather than relative. + CLE requires relative addresses, leading to numerous `AT.from_lva().to_rva()` calls in this backend. """ is_default = True # Tell CLE to automatically consider using the MachO backend diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/api/backend.rst b/docs/api/backend.rst index 1dfa8643..93b3aa77 100644 --- a/docs/api/backend.rst +++ b/docs/api/backend.rst @@ -1,3 +1,6 @@ +Backend Interface +================= + .. automodule:: cle.backends.backend .. automodule:: cle.backends.symbol .. automodule:: cle.backends.regions diff --git a/docs/api/backends/binja.rst b/docs/api/backends/binja.rst index 2a966906..f6c5dca5 100644 --- a/docs/api/backends/binja.rst +++ b/docs/api/backends/binja.rst @@ -1 +1,4 @@ +Binary Ninja +============ + .. automodule:: cle.backends.binja diff --git a/docs/api/backends/blob.rst b/docs/api/backends/blob.rst index 2b55d6a7..cec64ad9 100644 --- a/docs/api/backends/blob.rst +++ b/docs/api/backends/blob.rst @@ -1 +1,4 @@ +Blob +==== + .. automodule:: cle.backends.blob diff --git a/docs/api/backends/cgc.rst b/docs/api/backends/cgc.rst index c8644008..72e81ba7 100644 --- a/docs/api/backends/cgc.rst +++ b/docs/api/backends/cgc.rst @@ -1,3 +1,6 @@ +CGC +=== + .. automodule:: cle.backends.cgc .. automodule:: cle.backends.cgc.cgc .. automodule:: cle.backends.cgc.backedcgc diff --git a/docs/api/backends/elf.rst b/docs/api/backends/elf.rst index 8e3c1f70..2cd40455 100644 --- a/docs/api/backends/elf.rst +++ b/docs/api/backends/elf.rst @@ -2,7 +2,6 @@ ELF Backend =========== .. autoclass:: cle.backends.ELF -.. autoclass:: cle.backends.ELFSymbol .. autoclass:: cle.backends.elf.ELFCore diff --git a/docs/api/backends/ihex.rst b/docs/api/backends/ihex.rst index 0c72349c..631e4950 100644 --- a/docs/api/backends/ihex.rst +++ b/docs/api/backends/ihex.rst @@ -1 +1,4 @@ +IHex +==== + .. automodule:: cle.backends.ihex diff --git a/docs/api/backends/index.rst b/docs/api/backends/index.rst index 30090913..dd442f5b 100644 --- a/docs/api/backends/index.rst +++ b/docs/api/backends/index.rst @@ -4,12 +4,10 @@ Backends .. toctree:: :maxdepth: 1 - .. Most common backends ELF PE Mach-O - .. Other backends in alphabetical order Binary Ninja Blob CGC diff --git a/docs/api/backends/java.rst b/docs/api/backends/java.rst index 5183a67d..ea274210 100644 --- a/docs/api/backends/java.rst +++ b/docs/api/backends/java.rst @@ -1,3 +1,6 @@ +Java +==== + .. automodule:: cle.backends.java.android_lifecycle .. automodule:: cle.backends.java.apk .. automodule:: cle.backends.java.jar diff --git a/docs/api/backends/macho.rst b/docs/api/backends/macho.rst index 553c6c0d..a796b5df 100644 --- a/docs/api/backends/macho.rst +++ b/docs/api/backends/macho.rst @@ -1,5 +1,5 @@ -Mach-O Backend -============== +Mach-O +====== .. autoclass:: cle.backends.macho.macho.MachO .. autoclass:: cle.backends.macho.macho.SymbolList @@ -8,5 +8,4 @@ Mach-O Backend .. automodule:: cle.backends.macho.section .. automodule:: cle.backends.macho.segment .. automodule:: cle.backends.macho.binding -.. automodule:: cle.backends.macho.macho_load_commands .. automodule:: cle.backends.macho.structs diff --git a/docs/api/backends/minidump.rst b/docs/api/backends/minidump.rst index d088d5c5..bc44ae2f 100644 --- a/docs/api/backends/minidump.rst +++ b/docs/api/backends/minidump.rst @@ -1 +1,4 @@ +Minidump +======== + .. automodule:: cle.backends.minidump diff --git a/docs/api/backends/pe.rst b/docs/api/backends/pe.rst index 87a1d9b6..2bda72ef 100644 --- a/docs/api/backends/pe.rst +++ b/docs/api/backends/pe.rst @@ -1,5 +1,5 @@ -PE Backend -========== +PE +== .. autoclass:: cle.backends.PE diff --git a/docs/api/backends/static_archive.rst b/docs/api/backends/static_archive.rst index 9ed9755c..a747ff54 100644 --- a/docs/api/backends/static_archive.rst +++ b/docs/api/backends/static_archive.rst @@ -1 +1,4 @@ +Static Archive +============== + .. automodule:: cle.backends.static_archive diff --git a/docs/api/backends/uefi_firmware.rst b/docs/api/backends/uefi_firmware.rst index 59763a9d..a9e2ff70 100644 --- a/docs/api/backends/uefi_firmware.rst +++ b/docs/api/backends/uefi_firmware.rst @@ -1,2 +1,5 @@ +UEFI Firmware +============= + .. automodule:: cle.backends.uefi_firmware .. automodule:: cle.backends.te diff --git a/docs/api/backends/xbe.rst b/docs/api/backends/xbe.rst index 06cf9f64..55773002 100644 --- a/docs/api/backends/xbe.rst +++ b/docs/api/backends/xbe.rst @@ -1 +1,4 @@ +Xbox Executable +=============== + .. automodule:: cle.backends.xbe diff --git a/docs/api/index.rst b/docs/api/index.rst index c3121fe5..b39fd401 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -2,7 +2,7 @@ API Documentation ================= .. toctree:: - :maxdepth: 1 + :maxdepth: 0 Loader Interface Backend Interface diff --git a/docs/api/relocations.rst b/docs/api/relocations.rst index 9cf2899f..a5f47948 100644 --- a/docs/api/relocations.rst +++ b/docs/api/relocations.rst @@ -12,7 +12,6 @@ Look at the existing versions for details. .. automodule:: cle.backends.elf.relocation.elfreloc .. automodule:: cle.backends.elf.relocation.mips64 .. automodule:: cle.backends.elf.relocation.generic -.. automodule:: cle.backends.elf.relocation.armel .. automodule:: cle.backends.elf.relocation.ppc .. automodule:: cle.backends.elf.relocation.armhf .. automodule:: cle.backends.elf.relocation.pcc64 diff --git a/docs/conf.py b/docs/conf.py index c90a3def..58f463e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,7 @@ "sphinx.ext.intersphinx", "sphinx.ext.napoleon", "sphinx.ext.todo", - "sphinx.ext.viewcode", + # "sphinx.ext.viewcode", "sphinx_autodoc_typehints", "myst_parser", ] diff --git a/docs/index.rst b/docs/index.rst index afd205c4..aff2bb8c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ The first shows basic usage of CLE, and the second shows the API reference. .. toctree:: - :maxdepth: 5 + :maxdepth: 1 :caption: Contents: Quickstart