-------------------------------------------------------------------------------------------------------

*** Agafi: Advanced Gadget Finder ***

A little help for you ...

-------------------------------------------------------------------------------------------------------

First at all, remember to download "distorm3.dll" from "https://code.google.com/p/distorm/downloads/detail?name=distorm3-3-dlls.zip"
Then, copy the 32 bit version at the current Agafi path.

-------------------------------------------------------------------------------------------------------

Finding gadgets:
  Write the type of gadgets that you want in "objective.txt"
You can read all supported options at the end of this document.

Here, some finding examples:

E.g.1 finding EAX=EBX gadgets:
  eax==ebx

E.g.2 finding EAX=ANY REG32 gadgets:
  eax==reg32

E.g.3 finding ANY REG32=EAX gadgets:
  reg32==eax

E.g.4 finding ANY REG32=ANY REG32 gadgets:
  reg32==reg32

E.g.5 finding ESP=ANY REG32 gadgets ( Stack Pivoting ):
  esp==reg32

E.g.6 finding ESP=THE CONTENT OF ESP+0x0c gadgets ( Stack Pivoting to an argument ):
  esp==[esp+0x0c]

E.g.7 finding PUSHAD/RET gadgets ( ohhh yeah ... ):
  [esp+0x00]==esi and [esp+0x04]==ebp and eip==edi

E.g.8 finding EAX+=1 ( You can use the same way to any operation )
  eax=0x33333333
  eax==0x33333334
  
-------------------------------------------------------------------------------------------------------

Use example:
  line in "objective.txt": "[esp+0x00]==esi and [esp+0x04]==ebp and eip==edi"
  cmd: "agafi -f program.exe objective.txt"

Output:
  [x] Valid gadget at: 00239890
  --> matches: [esp+0x0]=esi, [esp+0x4]=ebp, eip=edi
  --> stack used: -0x1c
  --> preserved registers: eax ecx edx ebx ebp esi edi
  --> conditional jumps used: 0
  *** 00239890: pusha
  *** 00239891: ret

-------------------------------------------------------------------------------------------------------

Options supported:

Use: agafi option objective.txt [output_file]

Options:
 -p pid
 -rp pid
 -f module
 -rf module
 -s snapshot.bin

'r' means reuse snapshot (not to take this again).

-------------------------------------------------------------------------------------------------------

Complete objectives supported:

Assignations supported in objective.txt:
 -EFLAGS=VALUE
 -REG=VALUE
 -modules=MODULE1, MODULE2, ...
 -test_range=BASE,LIMIT

Objectives supported in objective.txt:
 -<REG|REG32>==<REG|REG32>
 -REG==VALUE
 -REG==MIN_VALUE,MAX_VALUE
 -REG==REG<+|->0xMM,REG<+|->0xNN
 -<REG|REG32>==[<REG|REG32>+0xNN]
 -[REG+0xNN]==<REG|REG32>

Notes:
 * REG32 = All general purpose registers
 * Many objectives can be concatenated using 'and' with some restrictions

Warnings:
 1. The assignation ESP=VALUE is not supported
 2. The objective 'REG32==REG32' doesn't include Stack Pivotings
 3. The objective '<REG|REG32>==[REG32+0xNN]' doesn't include [ESP+0xNN]

-------------------------------------------------------------------------------------------------------
