smallworld-re 1.0.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

smallworld/state/unstable/elf.py

@@ -5,11 +5,9 @@ import lief
 
 from ..emulators import Emulator
 from ..exceptions import ConfigurationError
-from ..hinting import Hint, get_hinter
 from .state import Code, Memory
 
 log = logging.getLogger(__name__)
-hinter = get_hinter(__name__)
 
 # Prorgam header types
 PT_NULL = 0  # Empty/unused program header
@@ -89,10 +87,9 @@ class ELFImage(Code):
                 # Progam file does not need a specific base address
                 # Use a default
                 # FIXME: Using a fixed value will not be valid if we load multiple files
-                hint = Hint(
-                    message=f"No base address requested, and ELF is PIC.  Using {hex(self.default_base)}"
+                log.info(
+                    f"No base address requested, and ELF is PIC.  Using {hex(self.default_base)}"
                 )
-                hinter.info(hint)
                 self.base = self.default_base
             else:
                 # Program file needs a specific base address
@@ -111,10 +108,9 @@ class ELFImage(Code):
             else:
                 # Program file needs a specific base address
                 # Not possible to rebase
-                hint = Hint(
-                    message=f"Requested base address {hex(self.user_base)}, but program needs {hex(self.file_base)}"
+                log.error(
+                    f"Requested base address {hex(self.user_base)}, but program needs {hex(self.file_base)}"
                 )
-                hinter.error(hint)
                 raise ConfigurationError("Contradictory base addresses.")
 
     def determine_entry(self):
@@ -219,8 +215,7 @@ class ELFImage(Code):
         # Use lief to check if this is an ELF
         # NOTE: for some reason, this takes list[int], not bytes
         if not lief.is_elf(list(self.image)):
-            hint = Hint(message="File is not an elf.")
-            hinter.error(hint)
+            log.error("File is not an elf.")
             raise ConfigurationError("Input is not an elf")
 
         # Use lief to parse the ELF
@@ -245,14 +240,12 @@ class ELFImage(Code):
         if ehdr.program_header_offset == 0:
             # NULL phoff means no program headers.
             # This file is not loadable; time to use another ELF loader.
-            hint = Hint(message="No program headers; file is not loadable")
-            hinter.error(hint)
+            log.error("No program headers; file is not loadable")
             raise ConfigurationError("File not loadable")
         if ehdr.program_header_offset >= len(self.image):
-            hint = Hint(
-                message=f"Invalid program header offset: {hex(ehdr.program_header_offset)}"
+            log.error(
+                f"Invalid program header offset: {hex(ehdr.program_header_offset)}"
             )
-            hinter.error(hint)
             raise ConfigurationError("Invalid program header offset")
 
         # Determine the file base address,
@@ -272,8 +265,7 @@ class ELFImage(Code):
             elif phdr.type == PT_DYNAMIC:
                 # Dynamic linking metadata.
                 # This ELF needs dynamic linking
-                hint = Hint(message="Program includes dynamic linking metadata")
-                hinter.info(hint)
+                log.info("Program includes dynamic linking metadata")
             elif phdr.type == PT_INTERP:
                 # Program interpreter
                 # This completely changes how program loading works.
@@ -281,8 +273,7 @@ class ELFImage(Code):
                 interp = self.image[
                     phdr.file_offset : phdr.file_offset + phdr.physical_size
                 ]
-                hint = Hint(message=f"Program specifies interpreter {interp!r}")
-                hinter.info(hint)
+                log.info(f"Program specifies interpreter {interp!r}")
             elif phdr.type == PT_NOTE:
                 # Auxiliary information
                 # Possibly useful for comparing machine/OS type.
@@ -294,8 +285,7 @@ class ELFImage(Code):
             elif phdr.type == PT_TLS:
                 # TLS Segment
                 # Your analysis is about to get nasty :(
-                hint = Hint(message="Program includes thread-local storage")
-                hinter.info(hint)
+                log.info("Program includes thread-local storage")
             elif phdr.type == PT_GNU_EH_FRAME:
                 # Exception handler frame.
                 # GCC puts one of these in everything.  Do we care?
@@ -303,13 +293,11 @@ class ELFImage(Code):
             elif phdr.type == PT_GNU_STACK:
                 # Stack executability
                 # If this is missing, assume executable stack
-                hint = Hint(message="Program specifies stack permissions")
-                hinter.info(hint)
+                log.info("Program specifies stack permissions")
             elif phdr.type == PT_GNU_RELRO:
                 # Read-only after relocation
                 # Only the dynamic linker should write this data.
-                hint = Hint(message="Program specifies RELRO data")
-                hinter.info(hint)
+                log.info("Program specifies RELRO data")
             elif phdr.type == PT_GNU_PROPERTY:
                 # GNU property segment
                 # Contains extra metadata which I'm not sure anything uses
@@ -318,19 +306,16 @@ class ELFImage(Code):
                 # Unknown OS-specific program header
                 # Either this is a weird ISA that extends the generic GNU ABI,
                 # or this isn't a Linux ELF.
-                hint = Hint(f"Unknown OS-specific program header: {phdr.type:08x}")
-                hinter.warn(hint)
+                log.warn(f"Unknown OS-specific program header: {phdr.type:08x}")
             elif phdr.type >= PT_LOPROC and phdr.type <= PT_HIPROC:
                 # Unknown machine-specific program header
                 # This is probably a non-Intel ISA.
                 # Most of these are harmless, serving to tell the RTLD
                 # where to find machine-specific metadata
-                hint = Hint(f"Unknown machine-specific program header: {phdr.type:08x}")
-                hinter.warn(hint)
+                log.warn(f"Unknown machine-specific program header: {phdr.type:08x}")
             else:
                 # Unknown program header outside the allowed custom ranges
-                hint = Hint(f"Invalid program header: {phdr.type:08x}")
-                hinter.warn(hint)
+                log.warn(f"Invalid program header: {phdr.type:08x}")
 
     def map_segment(self, phdr):
         """Map a segment into a SmallWorld machine state object

smallworld/utils.py

@@ -541,12 +541,17 @@ class RBTree(Iterable):
         return iter(self.values())
 
 
+def _range_collection_key(x):
+    # Used to be a lambda, but can't pickle lambdas
+    return x[0]
+
+
 class RangeCollection(Iterable):
     """A collection of non-overlapping ranges"""
 
     def __init__(self):
         # Back with an RBTree keyed off the start of the range
-        self._ranges = RBTree(key=lambda x: x[0])
+        self._ranges = RBTree(key=_range_collection_key)
 
     def is_empty(self) -> bool:
         """Check if this collection is empty

{smallworld_re-1.0.2.dist-info → smallworld_re-2.0.0.dist-info}/METADATA

@@ -1,20 +1,43 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: smallworld-re
-Version: 1.0.2
+Version: 2.0.0
 Summary: An emulation stack tracking library
-Home-page: https://github.com/smallworld-re/smallworld
 Author: MIT Lincoln Laboratory
 Author-email: smallworld@ll.mit.edu
-License: MIT
+License: MIT License
+        
+        © 2023 Massachusetts Institute of Technology
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of
+        this software and associated documentation files (the "Software"), to deal in
+        the Software without restriction, including without limitation the rights to
+        use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+        of the Software, and to permit persons to whom the Software is furnished to do
+        so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/smallworld-re/smallworld
+Project-URL: Issues, https://github.com/smallworld-re/smallworld/issues
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
+Requires-Dist: angr
+Requires-Dist: capstone
+Requires-Dist: jsons
+Requires-Dist: lief
 Requires-Dist: pyhidra==1.3.0
-Requires-Dist: angr==9.2.137
-Requires-Dist: capstone==5.0.3
-Requires-Dist: lief==0.14.1
-Requires-Dist: pypcode==3.0
-Requires-Dist: unicorn==2.0.1.post1
+Requires-Dist: pypcode
+Requires-Dist: unicorn
 Provides-Extra: development
 Requires-Dist: black; extra == "development"
 Requires-Dist: isort; extra == "development"
@@ -24,16 +47,10 @@ Requires-Dist: pip-tools; extra == "development"
 Requires-Dist: pre-commit; extra == "development"
 Requires-Dist: sphinx; extra == "development"
 Requires-Dist: sphinxcontrib-programoutput; extra == "development"
-Dynamic: author
-Dynamic: author-email
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
+Requires-Dist: jupyterlab; extra == "development"
+Requires-Dist: notebook; extra == "development"
+Requires-Dist: timeout-decorator; extra == "development"
+Dynamic: license-file
 
 # SmallWorld
 
@@ -56,19 +73,19 @@ There are two fundamental tenets behind SmallWorld
 
 The first of these tenets we hope to support with good software APIs. As a very
 simple example, consider the harnessing script
-[stack.py](https://github.com/smallworld-re/smallworld/blob/main/tests/square.py),
+[square.amd64.py](https://github.com/smallworld-re/smallworld/blob/main/tests/square/square.amd64.py),
 composed using SmallWorld, in which registers are initialized and a stack is
 arranged for running the code in
-[stack.s](https://github.com/smallworld-re/smallworld/blob/main/tests/stack.s).
+[square.amd64.s](https://github.com/smallworld-re/smallworld/blob/main/tests/square/square.amd64.s).
 For a more sophisticated example of SmallWorld's harnessing facitilites,
 consider the code snippet
-[struct.s](https://github.com/smallworld-re/smallworld/blob/main/tests/struct.s),
+[struct.amd64.s](https://github.com/smallworld-re/smallworld/blob/main/tests/struct/struct.amd64.s),
 which assumes a stack and input pointers to a linked list with very specific
 format. The harnessing script in this case is more complicated, including
 specifying type information for the linked list element structures as well as
 use of a simple allocator abstraction provided by SmallWorld to instantiate
 nodes and link them together appropriately:
-[struct.py](https://github.com/smallworld-re/smallworld/blob/main/tests/struct.py).
+[struct.amd64.py](https://github.com/smallworld-re/smallworld/blob/main/tests/struct/struct.amd64.py).
 
 The second tenet we address with purpose-built analyses which leverage a
 (possibly incomplete) harness script and that use techniques such as [Micro
@@ -84,33 +101,40 @@ SmallWorld directly supports yet.
 
 ## Installation
 
-To install SmallWorld from this repo, run:
-
+SmallWorld can be installed [directly from PyPi](https://pypi.org/project/smallworld-re/), just:
 ```bash
-pip install .
+pip install smallworld-re
 ```
 
-## Usage
-
-Print basic usage and help:
+If you'd like to install the latest changes or do development, you can install directly. To install SmallWorld from this repo, [optionally set up a venv](https://docs.python.org/3/library/venv.html) and then run:
 
 ```bash
-smallworld --help
+pip install .
 ```
 
+The result will be a library that can be used for harnessing and analyzing.  See the examples for a walkthrough.
+
 ## Contributing
 
 Pull requests and issues more than welcome.
 
 ### Development
 
-To set up a development environment from this repo, install SmallWorld in
+#### The Easy Way
+To set up a development environment from this repo, the easiest method is to use
+the install script `install.sh`. This has been tested on Ubuntu 22.04 and may be run
+as the root user, or a non-root user with sudo permissions.
+This will both install SmallWorld and build the unit and integration tests.
+Note that installation will not work fully on an ARM and is not supported.
+
+#### The Hard Way
+To manually set up a development environment from this repo, install SmallWorld in
 editable mode with extras for development and testing. Use the include
 constraints to install frozen versions and ensure a consistent development
 environment.
 
 ```bash
-pip install -e .[development] -c constraints.txt
+pip install -e ".[development]" -c constraints.txt
 ```
 
 #### Code Style
@@ -123,17 +147,6 @@ installing development dependencies), run:
 pre-commit install
 ```
 
-### Documentation
-
-To build the full SmallWorld documentation, after installing SmallWorld with
-`development` extras enabled, from the `docs/` directory, run:
-
-```bash
-make html
-```
-
-Or other [supported Sphinx output formats](https://www.sphinx-doc.org/en/master/usage/builders/index.html).
-
 ### Testing
 
 #### Prerequisites
@@ -149,6 +162,9 @@ You can then build the tests by running:
 
 ```bash
 make -C tests
+
+ulimit -c unlimited
+make -C tests/elf_core
 ```
 
 #### Running Tests
@@ -161,6 +177,23 @@ python3 tests/unit.py
 python3 tests/integration.py
 ```
 
+### Documentation
+
+To build the full SmallWorld documentation
+* verify [Sphinx](https://www.sphinx-doc.org/) has been installed
+* install SmallWorld with `development` extras enabled
+* make sure you have built the tests since the documentation generation requires output from those tests
+* from the `docs/` directory, run:
+
+```bash
+make html
+```
+
+The resulting documentation will be in `docs/build/html/`
+
+Other [supported Sphinx output formats](https://www.sphinx-doc.org/en/master/usage/builders/index.html) can also be generated.
+
+
 ## Distribution
 
 DISTRIBUTION STATEMENT A. Approved for public release. Distribution is