Skip to content

EZForever/PEDoll

Repository files navigation

PEDoll

Program behavior analyzer for Win32/Win64

English | 简体中文

Overview

PEDoll is a parody of @matrixcascade's PeDoll (the "original PeDoll"), aimed to support the x64 platform, multiple clients and multi-threaded applications.

PEDoll consists of three parts:

  • The Controller accepts incoming client connections and provide a CLI/GUI for user to manage clients and hooks on them.
  • The Monitor clients runs on a target machine (either the same physical machine the Controller is running on, or a VM), with its main purpose to create Doll clients by either launching a new process, or attaching to existing ones.
  • The Doll clients are processes injected by the libDoll module (libDoll.dll). libDoll communicates with the Controller, installs inline hooks into the process and respond to the Controller's commands in case of a hook has activated.

These parts communicate by the Puppet Protocol, a simple, TCP-based scheme of packets.

PEDoll works by installing hooks on Windows APIs or inner procedures into a Doll process, wait for hooks to activate, then examine the hooks' context (function arguments, memory buffers, etc.) and give out verdicts on whether the process can continue execution.

You can get a prebulit PEDoll package from the "Releases" page, or compile it yourself with instructions below.

Features

Comparing to the original PeDoll:

  • Full x64 support: PEDoll is designed with x64 concepts in mind. You can set up hooks and examine results just like on a x86 client.
  • Arbitrary number of API/pattern-based hooks: Due to the change to hooking mechanisms, PEDoll no longer require the API being hooked to be supported by libDoll. Also applies to pattern-based hooks ("binary hooks" as in original PeDoll).
  • Enhanced context expressions: Examine contexts with C# expressions! Lambda expressions, LINQ extensions, all in one command.
  • Multiple clients: Because one Controller per Doll can be annoying.

System requirements

  • Controller: Windows 7 SP1 or above, with .NET Framework 4.5 installed (pre-installed on Windows 8 or above).
  • Monitor and libDoll: Windows Vista or above.

Usage

The project's wiki provides a simple example.

More & detailed information on commands, expressions, etc. will be available on the project's wiki.

Building

The IDE of choice is Visual Studio Community 2019 with workloads Desktop development with C++ (for building the Monitor and libDoll) and .NET desktop development (for building the Controller).

This project utilizes Detours and includes it as a git submodule. In order to build the Monitor and libDoll, you need to obtain it by either use git clone --recursive https://github.com/EZForever/PEDoll.git while cloning this repo, or run git submodule update --init --recursive afterwards.

Do not expect all features in Controller to work when debugging; important files like Monitor executables and scripts will be missing. The file GenerateRelease.cmd, when run under a Visual Studio Developer Command Prompt, will build the whole solution, place all files accordingly and process all API scripts to support x64. Always use the build generated by GenerateRelease.cmd for normal usage.

More information on implementation details will be available on the project's wiki.

FAQ

See "FAQ" on project wiki.

License

The MIT License.