Skip to content

Commit ecb4cc1

Browse files
NytroRSTNytroRST
committed
Initial support for Windows x64 shellcodes
Alpha version
1 parent 84dcc47 commit ecb4cc1

37 files changed

Lines changed: 1161 additions & 31 deletions

‎Keystone/docs/COMPILE-NIX.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
This documentation explains how to build & install Keystone on all kind of nix OS.
2+
For Windows, see [COMPILE-WINDOWS.md](COMPILE-WINDOWS.md)
3+
4+
5+
1. Dependency
6+
7+
CMake is required to build keystone.
8+
9+
- On Mac OS X, you can install "cmake" with "brew".
10+
11+
$ brew install cmake
12+
13+
- On Ubuntu Linux, install "cmake" with:
14+
15+
$ sudo apt-get install cmake
16+
17+
18+
2. From the root directory of Keystone source, compile its dynamic library
19+
with the following commands.
20+
21+
$ mkdir build
22+
$ cd build
23+
$ ../make-share.sh
24+
25+
In the case you want to compile with all the debug information, replace the
26+
last line with:
27+
28+
$ ../make-share.sh debug
29+
30+
For Linux distributions following the "Filesystem Hierarchy Standard" and
31+
put x64 libraries under $PREFIX/lib64, such as Fedora, Redhat & Suse,
32+
add "fhs" option at the end of make-share.sh script, like below.
33+
34+
$ ../make-share.sh fhs
35+
36+
By default, this builds all architectures, which is: AArch64, ARM, Hexagon,
37+
Mips, PowerPC, Sparc, SystemZ & X86. To compile just some selected ones,
38+
pass a semicolon-separated list of targets to LLVM_TARGETS_TO_BUILD,
39+
like follows if we only want AArch64 & X86.
40+
41+
$ cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON -DLLVM_TARGETS_TO_BUILD="AArch64, X86" -G "Unix Makefiles" ..
42+
$ make -j8
43+
44+
You can also compile static a library with:
45+
46+
$ mkdir build
47+
$ cd build
48+
$ ../make-lib.sh
49+
50+
In the case you want to compile with all the debug information, replace the
51+
last line with:
52+
53+
$ ../make-lib.sh debug
54+
55+
For Linux distributions following the "Filesystem Hierarchy Standard" and
56+
put x64 libraries under $PREFIX/lib64, such as Fedora, Redhat & Suse,
57+
add "fhs" option at the end of make-share.sh script, like below.
58+
59+
$ ../make-lib.sh fhs
60+
61+
Like above, this builds all architectures. To compile just some selected ones,
62+
pass a semicolon-separated list of targets to LLVM_TARGETS_TO_BUILD,
63+
like follows if we only want AArch64 & X86.
64+
65+
$ cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DLLVM_TARGETS_TO_BUILD="AArch64, X86" -G "Unix Makefiles" ..
66+
$ make -j8
67+
68+
To customize your build by specifying PREFIX or other installation directories,
69+
pass one of the variables at https://cmake.org/cmake/help/v3.0/module/GNUInstallDirs.html
70+
to cmake. For example:
71+
72+
$ cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DLLVM_TARGETS_TO_BUILD="AArch64, X86" -G "Unix Makefiles" ..
73+
$ make -j8
74+
75+
76+
3. Right after building, install Keystone.
77+
78+
$ sudo make install
79+
80+
Keystone is installed in '/usr/local', depending on your distribution (eg. Ubuntu) you might
81+
need to add '/usr/local/lib' to '/etc/ld.so.conf'. Then update the dynamic linker
82+
with:
83+
84+
$ sudo ldconfig
85+
86+
Besides the libraries & C header files under thedirectory "include/keystone",
87+
this step also installs a tool named "kstool" on the system.
88+
(The source of "kstool" is in the directory "kstool/kstool")
89+
90+
91+
4. Test Keystone with "kstool" like below.
92+
93+
$ kstool x32 "add eax, ebx"
94+
95+
Run "kstool" without any option to find out how to use this handy tool.
96+
97+
98+
5. Learn more on how to code your own tools with our samples.
99+
100+
For C sample code, see code in directory samples/
101+
102+
For Python sample code, see code in directory bindings/python/

‎Keystone/docs/COMPILE-WINDOWS.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
This documentation explains how to build Keystone on Windows.
2+
For *nix OS, see [COMPILE-NIX.md](COMPILE-NIX.md)
3+
4+
5+
1. Dependency
6+
7+
CMake is required as dependency.
8+
Download & install cmake from http://www.cmake.org
9+
10+
Microsoft Visual Studio 2013 or older is required for compiling.
11+
Download & install it from https://www.visualstudio.com
12+
13+
Python is another dependency. Download & install it from
14+
https://www.python.org
15+
16+
17+
2. Open the Visual Studio Command Promplt, and from the root directory
18+
of Keystone source, do:
19+
20+
$ mkdir build
21+
$ cd build
22+
23+
To build DLL file, run:
24+
25+
$ ..\nmake-dll.bat
26+
27+
By default, this builds all architectures, which is: AArch64, ARM, Hexagon,
28+
Mips, PowerPC, Sparc, SystemZ & X86. To compile just some selected ones,
29+
pass a semicolon-separated list of targets to LLVM_TARGETS_TO_BUILD,
30+
like follows if we only want AArch64 & X86.
31+
32+
$ cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON -DLLVM_TARGETS_TO_BUILD="AArch64, X86" -G "NMake Makefiles" ..
33+
$ nmake
34+
35+
To build LIB file, run:
36+
37+
$ ..\nmake-lib.bat
38+
39+
Like above, this builds all architectures. To compile just some selected ones,
40+
pass a semicolon-separated list of targets to LLVM_TARGETS_TO_BUILD,
41+
like follows if we only want AArch64 & X86.
42+
43+
$ cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DLLVM_TARGETS_TO_BUILD="AArch64, X86" -G "NMake Makefiles" ..
44+
$ nmake
45+
46+
Find the generated libraries in build\llvm\lib\keystone.{dll,lib}
47+
48+
In the case you build LIB file, a tool named "kstool.exe" is also
49+
compiled & available under directory "build\kstool".
50+
(Find source of "kstool" in directory "kstool/kstool")
51+
52+
53+
3. Test Keystone with "kstool" like below.
54+
55+
$ kstool.exe x32 "add eax, ebx"
56+
57+
Run "kstool.exe" without any option to find out how to use this handy tool.
58+
59+
60+
4. Learn more on how to code your own tools with our samples.
61+
62+
For C sample code, see code in directory samples/
63+
64+
For Python sample code, see code in directory bindings/python/

‎Keystone/docs/COMPILE.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
To compile Keystone on Mac OS X, Linux, BSD, Solaris and all kind of nix OS,
2+
see [COMPILE-NIX.md](COMPILE-NIX.md)
3+
4+
To compile Keystone on Windows, see [COMPILE-WINDOWS.md](COMPILE-WINDOWS.md)
5+
6+
Learn more on how to code your own tools with our samples.
7+
8+
- For C sample code, see code in directory samples/
9+
- For Python sample code, see code in directory bindings/python/

‎Keystone/docs/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Documention of Keystone assembler engine.
2+
3+
* How to compile & install Keystone from source.
4+
5+
COMPILE.md
6+
7+
* How to compile & install Keystone from packages.
8+
9+
http://keystone-engine.org/docs/
10+
11+
* Tutorial on programming with C & Python languages.
12+
13+
http://keystone-engine.org/docs/tutorial.html
14+
15+
* Compare Keystone & LLVM.
16+
17+
http://keystone-engine.org/docs/beyond_qemu.html

‎Keystone/docs/RECON2016-keystone.pdf‎

1.36 MB
Binary file not shown.

‎Keystone/docs/beyond_llvm.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
## Keystone & LLVM
2+
3+
Keystone engine is based on the [MC component](http://blog.llvm.org/2010/04/intro-to-llvm-mc-project.html) of the LLVM compiler infrastructure, which among many stuffs has an assembler engine inside. LLVM even has a tool named *llvm-mc* that can be used to compile input string of assembly instructions.
4+
5+
While Keystone reuses a part of LLVM as its core (with quite a few of changes to adapt to our design), there is a major difference between them. Notably, Keystone can do whatever LLVM does in term of assembling, but beyond that our engine can do more & do better in some aspects.
6+
7+
The section below highlights the areas where Keystone shines.
8+
9+
- **Framework**: *llvm-mc* is a tool, but not a framework. Therefore, it is very tricky to build your own assembler tools on of LLVM, while this is the main purpose of Keystone. Keystone's API makes it easy to handle errors, report internal status of its core or change compilation mode at runtime, etc.
10+
11+
- **Lightweight**: Keystone is much more lightweight than LLVM because we stripped all the subsystems that do not involve in assembler. As a result, Keystone is more than 10 times smaller in size and in memory consumption. Initial verson of Keystone takes only 30 seconds to compile on a laptop, while LLVM needs 15 minutes to build.
12+
13+
- **Flexibility**: LLVM's assembler is much more restricted. For example, it only accepts assembly in LLVM syntax. On the contrary, Keystone is going to support all kind of input, ranging from Nasm, Masm, etc.
14+
15+
- **Capability**: LLVM is for compiling & linking, so (understandably) some of its technical choices are not inline with an independent assembler like Keystone. For example, LLVM always put code and data in separate sections. However, it is very common for assembly to mix code and data in the same section (think about shellcode). Keystone is made to handle this kind of input very well.
16+
17+
- **Binding**: As a framework, Keystone supports multiple bindings on top of the core, starting with Python (more bindings will be added later). This makes it easy to be adopted by developers.
18+
19+
With all that said, LLVM is an awesome project, which Keystone was born from. However, Keystone is not just LLVM, but offering more because it has been designed & implemented to be an independent framework.

Keystone/keystone.lib renamed to Keystone/keystone_win32.lib

4.6 MB
Binary file not shown.

‎Keystone/keystone_win64.lib‎

5.96 MB
Binary file not shown.

‎Keystone/samples/CMakeLists.txt‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Sample for Keystone assembler engine (www.keystone-engine.org).
2+
# By Nguyen Anh Quynh, 2016
3+
4+
# For Linux, be sure to install Keystone before compiling this
5+
# For Windows, be sure to copy keystone.dll or keystone.lib
6+
# to this directory before compiling
7+
8+
cmake_minimum_required(VERSION 2.8)
9+
10+
project(sample)
11+
12+
# For Linux, be sure to install Keystone before compiling this
13+
# For Windows, make sure to point to include dir of Keystone
14+
include_directories("../../include")
15+
16+
add_executable(sample sample.c)
17+
18+
target_link_libraries(sample keystone)

‎Keystone/samples/Makefile‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Sample code for Keystone Assembler Engine (www.keystone-engine.org).
2+
# By Nguyen Anh Quynh, 2016
3+
4+
.PHONY: all clean
5+
6+
KEYSTONE_LDFLAGS = -lkeystone -lstdc++ -lm
7+
8+
all:
9+
${CC} -o sample sample.c ${KEYSTONE_LDFLAGS}
10+
11+
clean:
12+
rm -rf *.o sample

0 commit comments

Comments
 (0)