smallworld-re 1.0.2__tar.gz → 2.0.0__tar.gz

{smallworld_re-1.0.2 → smallworld_re-2.0.0}/PKG-INFO

@@ -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

smallworld_re-1.0.2/smallworld_re.egg-info/PKG-INFO → smallworld_re-2.0.0/README.md

@@ -1,40 +1,3 @@
-Metadata-Version: 2.2
-Name: smallworld-re
-Version: 1.0.2
-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
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE.txt
-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
-Provides-Extra: development
-Requires-Dist: black; extra == "development"
-Requires-Dist: isort; extra == "development"
-Requires-Dist: flake8; extra == "development"
-Requires-Dist: mypy; extra == "development"
-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
-
 # SmallWorld
 
 [![commit-style-image]][conventional]
@@ -56,19 +19,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 +47,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 +93,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 +108,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 +123,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

smallworld_re-2.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smallworld-re"
+version = "2.0.0"
+description = "An emulation stack tracking library"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = { file = "LICENSE.txt" }
+authors = [
+  { name = "MIT Lincoln Laboratory" }, 
+  { email = "smallworld@ll.mit.edu" },
+]
+
+dependencies = [
+  "angr",
+  "capstone",
+  "jsons",
+  "lief",
+  "pyhidra==1.3.0", # pip-compile does not pin pyhidra in constraints.txt for some reason
+  "pypcode",
+  "unicorn",
+]
+
+[project.urls]
+Homepage = "https://github.com/smallworld-re/smallworld"
+Issues = "https://github.com/smallworld-re/smallworld/issues"
+
+[project.optional-dependencies]
+development = [
+  "black",
+  "isort",
+  "flake8",
+  "mypy",
+  "pip-tools",
+  "pre-commit",
+  "sphinx",
+  "sphinxcontrib-programoutput",
+  "jupyterlab",
+  "notebook",
+  "timeout-decorator",
+]
+
+[project.scripts]
+smallworld = "smallworld.__main__:main"
+
+[tool.setuptools]
+include-package-data = true
+zip-safe = false
+license-files = ["LICENSE.txt"]
+
+[tool.setuptools.packages.find]
+include = ["smallworld*"]
+

{smallworld_re-1.0.2 → smallworld_re-2.0.0}/smallworld/analyses/__init__.py

@@ -1,14 +1,22 @@
 from .analysis import *  # noqa: F401, F403
 from .analysis import __all__ as __analysis__
 from .colorizer import Colorizer
+from .colorizer_def_use import ColorizerDefUse
 from .colorizer_summary import ColorizerSummary
 from .field_detection import FieldDetectionAnalysis, ForcedFieldDetectionAnalysis
 from .forced_exec import ForcedExecution
+from .trace_execution import TraceExecution
+from .trace_execution_types import CmpInfo, TraceElement, TraceRes
 
 __all__ = __analysis__ + [
     "Colorizer",
     "ColorizerSummary",
+    "ColorizerDefUse",
     "FieldDetectionAnalysis",
     "ForcedFieldDetectionAnalysis",
     "ForcedExecution",
+    "TraceExecution",
+    "TraceElement",
+    "TraceRes",
+    "CmpInfo",
 ]

smallworld_re-2.0.0/smallworld/analyses/analysis.py

@@ -0,0 +1,29 @@
+import abc
+
+from smallworld.hinting.hinting import Hinter
+
+from .. import state, utils
+
+
+class Analysis(utils.MetadataMixin):
+    """An analysis that emits some information about some code, possibly to help with harnessing."""
+
+    def __init__(self, hinter: Hinter, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.hinter = hinter
+
+    @abc.abstractmethod
+    def run(self, machine: state.Machine) -> None:
+        """Run the analysis.
+
+        This function **should not** modify the provided Machine. Instead, it
+        should be coppied before modification.
+
+        Arguments:
+            machine: A machine state object on which this analysis should run.
+        """
+
+        pass
+
+
+__all__ = ["Analysis"]

{smallworld_re-1.0.2 → smallworld_re-2.0.0}/smallworld/analyses/code_coverage.py

@@ -5,7 +5,6 @@ from .. import emulators, hinting
 from . import analysis
 
 logger = logging.getLogger(__name__)
-hinter = hinting.get_hinter(__name__)
 
 
 class CodeCoverage(analysis.Analysis):
@@ -28,4 +27,4 @@ class CodeCoverage(analysis.Analysis):
                 coverage[pc] = 1
 
         hint = hinting.CoverageHint(message="Coverage for execution", coverage=coverage)
-        hinter.info(hint)
+        self.hinter.send(hint)