peforge

peforge is a small C++17 library for inspecting and modifying Portable Executable (PE) files on Windows.

The library parses bounded byte buffers into validated views before exposing headers, directories, sections, or address mappings. Views are non-owning, so the source buffer must outlive them. Read-only inspection and mutation are separate APIs so callers can reason about whether an operation changes a file.

Status

peforge is an early-stage library. The current API supports:

• PE32 and PE32+ validation
• DOS, NT, file, optional, section, and data-directory inspection
• Import library and symbol inspection
• Export name, ordinal, RVA, and forwarder inspection
• Raw file offset to RVA conversion and RVA to raw file offset conversion
• Read-only code-cave discovery for 0x00 and 0xCC regions
• Explicit entry-point updates through mutable views
• Bounded byte patches, file-characteristic updates, and directory-entry updates through mutable views
• Windows module resource lookup
• Optional Clang libFuzzer harness for parser hardening

The library does not yet resize sections, patch cave contents, recalculate checksums, or parse every directory structure.

Build

cmake -S . -B build
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure

The build also produces peforge_inspect, a minimal example that prints basic metadata and the smallest discovered code cave:

.\build\examples\Release\peforge_inspect.exe C:\Windows\System32\notepad.exe

Install the package into a local prefix:

cmake --install build --config Release --prefix C:\path\to\stage

Consumers can then use:

find_package(peforge CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE peforge::peforge)

Example

#include <peforge.hpp>

#include <vector>

std::vector<BYTE> file_bytes = load_file();
auto result = peforge::pe_view::parse({file_bytes.data(), file_bytes.size()});
if (!result) {
    report_error(peforge::to_string(result.error()));
    return 1;
}

const auto& pe = result.value();
const DWORD entry_point = pe.entry_point();
const auto cave = peforge::find_minimum_cave(pe, 32, IMAGE_SCN_MEM_EXECUTE);

Safety Model

pe_view::parse() validates the header layout, optional-header format, section table, section file ranges, and arithmetic boundaries before constructing a view. Parse failures include a pe_error value for diagnostics. Other APIs return std::optional, nullptr, or false when a requested value is unavailable or cannot be mapped.

Treat successful parsing as structural validation, not as proof that a file is trustworthy or safe to execute.

Roadmap

• Explicit section resizing and cave patching
• Additional PE directory parsers beyond imports and exports
• Checksum updates
• Fuzzing and sanitizer jobs
• Package-manager manifests

Reference

• PE Format

License

MIT