pe-parse/README.md

50 lines
2.5 KiB
Markdown
Raw Normal View History

2013-11-22 19:25:24 -05:00
pe-parse
2013-11-19 20:13:37 -05:00
=========================================
2014-08-08 17:44:43 -04:00
[![Build Status](https://travis-ci.org/trailofbits/pe-parse.svg?branch=master)](https://travis-ci.org/trailofbits/pe-parse)
2014-12-10 20:29:57 -05:00
[![Coverity Scan Build Status](https://scan.coverity.com/projects/3671/badge.svg)](https://scan.coverity.com/projects/3671)
2014-08-08 17:44:43 -04:00
2013-11-22 16:40:21 -08:00
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.
2013-11-22 19:19:18 -05:00
pe-parse supports these use cases via a minimal API that provides methods for
* Opening and closing a PE file
* Iterating over the imported functions
* Iterating over the relocations
* Iterating over the exported functions
* Iterating over sections
* Iterating over resources
2013-11-22 19:19:18 -05:00
* Reading bytes from specified virtual addresses
* Retrieving the program entry point
2013-11-22 19:25:24 -05:00
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.
2013-11-22 19:19:18 -05:00
2013-11-22 19:25:24 -05:00
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.
2013-11-22 19:28:04 -05:00
Building
========
2017-04-12 17:54:54 -04:00
pe-parse is built using `cmake` and has no major dependencies.
2017-03-11 19:25:58 -05:00
1. Install cmake:
* Debian/Ubuntu: `sudo apt-get install cmake`
* RedHat/Fedora: `sudo yum install cmake`
* OSX: `brew install cmake`
2. `cmake .`
3. `make`
2013-11-22 19:31:11 -05:00
Using the library
=======
Once the library is installed, linking to it is easy! Add the following lines in your CMake project:
```
find_package(peparse REQUIRED)
target_link_libraries(your_target_name ${PEPARSE_LIBRARIES})
target_include_directories(your_target_name PRIVATE ${PEPARSE_INCLUDE_DIRS})
```
You can see a full example in the examples/peaddrconv folder.
2013-11-22 19:31:11 -05:00
Authors
=======
2014-01-22 17:26:06 -05:00
pe-parse was designed and implemented by Andrew Ruef (andrew@trailofbits.com), with significant contributions from [Wesley Shields](https://github.com/wxsBSD).