Release 1.0 prep work (#113)

Co-authored-by: Eric Kilmer <[email protected]>

Author: woodruffw

.github/workflows/ci.yml

@@ -10,10 +10,11 @@ on:
     - cron:  '0 12 * * *'
 
 jobs:
-  test:
+  pe-parse:
     strategy:
       matrix:
         platform: ["ubuntu-latest", "macos-latest"]
+        build-type: ["Debug", "Release"]
         compiler:
         - { CC: "clang", CXX: "clang++" }
         - { CC: "gcc", CXX: "g++" }
@@ -23,27 +24,80 @@ jobs:
     runs-on: ${{ matrix.platform }}
     steps:
     - uses: actions/checkout@v2
-    - name: Build C
+    - name: build
       env:
         CC: ${{ matrix.compiler.CC }}
         CXX: ${{ matrix.compiler.CXX }}
       run: |
         mkdir build
         cd build
-        cmake ..
-        make
-    - name: Build Python
+        cmake -DCMAKE_BUILD_TYPE=${{ matrix.build-type }} ..
+        cmake --build .
+    - name: test
+      run: |
+        ./build/dump-pe/dump-pe ./test/assets/example.exe
+
+  pepy:
+    strategy:
+      matrix:
+        platform: ["ubuntu-latest", "macos-latest"]
+        python:
+          - "3.6"
+          - "3.7"
+          - "3.8"
+    runs-on: ${{ matrix.platform }}
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python }}
+    - name: build
       run: |
-        cd python
-        python2 setup.py build
         python3 setup.py build
-  test-windows:
+    - name: sdist and install
+      run: |
+        python3 setup.py sdist
+        python3 -m pip install --user dist/*.tar.gz
+    - name: test
+      run: |
+        python3 test/test_pepy.py test/assets/example.exe
+
+  pe-parse-windows:
+    strategy:
+      matrix:
+        build-type: ["Debug", "Release"]
     runs-on: windows-latest
     steps:
     - uses: actions/checkout@v2
-    - name: Build C
+    - name: build
       run: |
         mkdir build
         cd build
         cmake -G "Visual Studio 16 2019" -A x64 ..
-        cmake --build .
+        cmake --build . --config ${{ matrix.build-type }}
+    - name: test
+      run: |
+        .\build\dump-pe\${{ matrix.build-type }}\dump-pe.exe .\test\assets\example.exe
+
+  pepy-windows:
+    strategy:
+      matrix:
+        python:
+          - "3.6"
+          - "3.7"
+          - "3.8"
+    runs-on: windows-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python }}
+    - name: build
+      run: |
+        python setup.py build
+    - name: install
+      run: |
+        python -m pip install --user .
+    - name: test
+      run: |
+        python test/test_pepy.py test/assets/example.exe

.gitignore

@@ -2,7 +2,7 @@ Makefile
 cmake_install.cmake
 dump-prog/dump-prog
 *.swp
-python/build
+build/
 .idea
 cmake-build-debug
 cmake-build-release
@@ -11,4 +11,7 @@ CMakeSettings.json
 .vs
 .vscode
 examples_build
-
+.DS_Store
+dist/
+MANIFEST
+*.egg-info/

LICENSE.txt LICENSE

@@ -0,0 +1,3 @@
+include VERSION
+include pepy/README.md
+include pe-parser-library/include/parser-library/*.h

MANIFEST.in

@@ -1,9 +1,14 @@
 pe-parse
-=========================================
+========
 
 [![Build Status](https://img.shields.io/github/workflow/status/trailofbits/pe-parse/CI/master)](https://github.com/trailofbits/pe-parse/actions?query=workflow%3ACI)
 
-pe-parse is a principled, lightweight parser for windows portable executable files. It was created to assist in compiled program analysis, potentially of programs of unknown origins. This means that it should be resistant to malformed or maliciously crafted PE files, and it should support questions that analysis software would ask of an executable program container. For example, listing relocations, describing imports and exports, and supporting byte reads from virtual addresses as well as file offsets.
+pe-parse is a principled, lightweight parser for windows portable executable files.
+It was created to assist in compiled program analysis, potentially of programs of unknown origins.
+This means that it should be resistant to malformed or maliciously crafted PE files, and it should
+support questions that analysis software would ask of an executable program container.
+For example, listing relocations, describing imports and exports, and supporting byte reads from
+virtual addresses as well as file offsets.
 
 pe-parse supports these use cases via a minimal API that provides methods for
  * Opening and closing a PE file
@@ -15,20 +20,34 @@ pe-parse supports these use cases via a minimal API that provides methods for
  * Reading bytes from specified virtual addresses
  * Retrieving the program entry point
 
-The interface is defined in `parser-library/parse.h`. The program in `dump-prog/dump.cpp` is an example of using the parser-library API to dump information about a PE file.
+The interface is defined in `parser-library/parse.h`.
 
-Internally, the parser-library uses a bounded buffer abstraction to access information stored in the PE file. This should help in constructing a sane parser that allows for detection of the use of bogus values in the PE that would result in out of bounds accesses of the input buffer. Once data is read from the file it is sanitized and placed in C++ STL containers of internal types.
+The program in `dump-prog/dump.cpp` is an example of using the parser-library API to dump
+information about a PE file.
+
+Internally, the parser-library uses a bounded buffer abstraction to access information stored in
+the PE file. This should help in constructing a sane parser that allows for detection of the use
+of bogus values in the PE that would result in out of bounds accesses of the input buffer.
+Once data is read from the file it is sanitized and placed in C++ STL containers of internal types.
+
+pe-parse includes Python bindings via `pepy`, which can be installed via `pip`:
+
+```bash
+$ pip3 install pepy
+```
+
+More information about `pepy` can be found in its [README](./pepy/README.md).
+
+## Dependencies
 
-Dependencies
-========
 ### CMake
   * Debian/Ubuntu: `sudo apt-get install cmake`
   * RedHat/Fedora: `sudo yum install cmake`
   * OSX: `brew install cmake`
   * Windows: Download the installer from the [CMake page](https://cmake.org/download/)
 
-Building
-========
+## Building
+
 ### Generic instructions
 ```
 git clone https://github.com/trailofbits/pe-parse.git
@@ -38,37 +57,48 @@ mkdir build
 cd build
 
 cmake -DCMAKE_BUILD_TYPE=Release ..
-cmake --build . --config Release
+cmake --build .
 
 # optional
-cmake --build . --config Release --target install
+cmake --build . --target install
 ```
 
-PE files that have a Resource section with strings for the Type are encoded in UTF-16, but that `std::string` expects UTF-8. Some cross-platform solution
-is desired. You can let cmake choose one it finds in your build environment or you can choose one from the following options yourself and specify it with
-the `-DUNICODE_LIBRARY` argument when generating the project files with cmake:
-* `icu` (preferred) - "[ICU](http://site.icu-project.org/) is a mature, widely used set of C/C++ and Java libraries providing Unicode and Globalization support for software applications"
-* `codecvt` - A C++ library header file ([now deprecated](http://open-std.org/JTC1/SC22/WG21/docs/papers/2017/p0618r0.html)) supported by some C++ runtimes
+PE files that have a Resource section with strings for the Type are encoded in UTF-16, but that
+`std::string` expects UTF-8. Some cross-platform solution is desired.
+
+You can let `cmake` choose one it finds in your build environment or you can choose one from the
+following options yourself and specify it with the `-DUNICODE_LIBRARY` argument when generating the
+project files with `cmake`:
+
+* `icu` (preferred) - "[ICU](http://site.icu-project.org/) is a mature, widely used set of C/C++
+and Java libraries providing Unicode and Globalization support for software applications"
+* `codecvt` - A C++ library header file
+([now deprecated](http://open-std.org/JTC1/SC22/WG21/docs/papers/2017/p0618r0.html)) supported
+by some C++ runtimes
 
 ### Notes about Windows
 
-If you are building on Windows with Visual Studio, the generator option can be used to select the compiler version and the output architecture:
+If you are building on Windows with Visual Studio, the generator option can be used to select the
+compiler version and the output architecture:
 
 ```
 # Compile 64-bit binaries with Visual Studio 2017
-cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_BUILD_TYPE=Release ..
+cmake -G "Visual Studio 15 2017 Win64" ..
 
 # Compile 32-bit binaries with Visual Studio 2017
-cmake -G "Visual Studio 15 2017" -DCMAKE_BUILD_TYPE=Release ..
+cmake -G "Visual Studio 15 2017" ..
 ```
 
-Visual Studio 2015 or higher is required to use codecvt, but you also have the option of using [ICU](http://site.icu-project.org/). The easiest way to
-get started with ICU in Windows is with [vcpkg](https://vcpkg.readthedocs.io/): `vcpkg install icu`. Then add the
-`-DCMAKE_TOOLCHAIN_FILE=C:\src\vcpkg\scripts\buildsystems\vcpkg.cmake` argument when generating the project files with cmake to add the appropriate
-library and include directories to the project.
+Visual Studio 2015 or higher is required to use codecvt, but you also have the option of using
+[ICU](http://site.icu-project.org/). The easiest way to get started with ICU in Windows is with
+[vcpkg](https://vcpkg.readthedocs.io/): `vcpkg install icu`.
+
+Then, add the `-DCMAKE_TOOLCHAIN_FILE=C:\src\vcpkg\scripts\buildsystems\vcpkg.cmake` argument when
+generating the project files with cmake to add the appropriate library and include directories to
+the project.
+
+## Using the library
 
-Using the library
-=======
 Once the library is installed, linking to it is easy! Add the following lines in your CMake project:
 
 ```
@@ -80,6 +110,7 @@ target_include_directories(your_target_name PRIVATE ${PEPARSE_INCLUDE_DIRS})
 
 You can see a full example in the examples/peaddrconv folder.
 
-Authors
-=======
-pe-parse was designed and implemented by Andrew Ruef ([email protected]), with significant contributions from [Wesley Shields](https://github.com/wxsBSD).
+## Authors
+
+pe-parse was designed and implemented by Andrew Ruef ([email protected]), with significant
+contributions from [Wesley Shields](https://github.com/wxsBSD).

README.md

@@ -0,0 +1 @@
+1.0.0-rc.2

VERSION

@@ -1,6 +1,12 @@
 cmake_minimum_required(VERSION 3.7)
 project(pe-parser-library)
 
+message(STATUS "VERSION file: ${CMAKE_SOURCE_DIR}/VERSION")
+
+file(READ "${CMAKE_SOURCE_DIR}/VERSION" PEPARSE_VERSION)
+string(STRIP "${PEPARSE_VERSION}" PEPARSE_VERSION)
+add_compile_definitions(PEPARSE_VERSION="${PEPARSE_VERSION}")
+
 set(UNICODE_LIBRARY "any" CACHE STRING "Select a unicode library")
 set_property(CACHE UNICODE_LIBRARY PROPERTY STRINGS "any" "icu" "codecvt")