# Shellcrafter
Shellcrafter is a comprehensive toolkit designed for shellcode development and gadget finding. It integrates several utilities to assist in the generation of shellcode from assembly instructions, conversion of ASCII text to hexadecimal stack push instructions, loading of DLLs, finding ROP gadgets, and more.
## Installation
To install Shellcrafter, you can either install it directly using pip if it's available in the Python Package Index or by cloning the repository and installing it locally:
```bash
$ pip3 install shellcrafter
```
Or clone the repository and install using:
```bash
$ git clone https://github.com/totekuh/shellcrafter.git
$ cd shellcrafter
$ pip3 install .
```
## Usage
Shellcrafter is structured around multiple command-line utilities grouped under a Typer application.
Here's how to use the various utilities:
### Keystone API - Shellcode Compiler
Compile shellcode from assembly instructions:
```bash
$ shellcrafter shellcode compile --instructions "mov ax, 1"
[+] 1 instructions have been encoded
shellcode = b""
shellcode += b"\x66\xb8\x01\x00"
shellcode_len = 4
```
Also for x64:
```bash
$ shellcrafter shellcode compile --instructions "mov ax, 1" --arch x64
```
Supports compiling shellcode from a file:
```bash
$ cat hash.asm
compute_hash:
xor eax, eax ;# NULL EAX
cdq ;# NULL EDX
cld ;# clear direction (clears the direction flag DF in the EFLAGS register)
compute_hash_again:
lodsb ;# load the next byte from ESI into AL
test al, al ;# check if AL contains the NULL terminator
jz compute_hash_finished ;# if the ZF is set, we've hit the NULL terminator
ror edx, 0x0d ;# rotate EDX 13 bits to the right
add edx, eax ;# add the new hashed byte to the accumulator
jmp compute_hash_again ;# next iteration
compute_hash_finished:
$ shellcrafter shellcode compile -if hash.asm
[+] 24 instructions have been encoded
shellcode = b""
shellcode += b"\x31\xc0\x99\xfc\xac\x84\xc0\x74\x07\xc1\xca\x0d\x01\xc2\xeb\xf4"
shellcode_len = 16
```
For more help:
```bash
shellcrafter shellcode compile --help
```
### Shellcode Generator
This tool can generate various types of shellcode operations:
#### Generate Stack Push Instructions for an ASCII String
Generate instructions for pushing the `example.dll` string on the stack:
```bash
shellcrafter codegen push-ascii --ascii-string "example.dll"
push_str: ;# push the 'example.dll' onto the stack
push 0x006c6c64 ;# Push the part "lld." of the string "example.dll" onto the stack
push 0x2e656c70 ;# Push the part "elpm" of the string "example.dll" onto the stack
push 0x6d617865 ;# Push the part "axe" of the string "example.dll" onto the stack
```
Use the negate operation to avoid NULL byte if necessary:
```bash
shellcrafter codegen push-ascii --ascii-string "example.dll" --null-free
push_str: ;# push the 'example.dll' onto the stack
mov eax, 0xff93939c ;# Move the negated value of the part "lld." of the string "example.dll" to EAX to avoid NULL bytes
neg eax ;# Negate EAX to get the original value
push eax ;# Push EAX onto the stack
push 0x2e656c70 ;# Push the part "elpm" of the string "example.dll" onto the stack
push 0x6d617865 ;# Push the part "axe" of the string "example.dll" onto the stack
```
#### Load a DLL
Generate code for loading a DLL into the target process.
The DLL's name and the address of the LoadLibraryA function have to be provided.
```bash
shellcrafter codegen load-library --dll-name "example.dll" --load-library-addr "[ebp-0x04]"
load_lib: ;# load the example.dll DLL
xor eax, eax ;# NULL EAX
push eax ;# Push NULL terminator for the string
push 0x006c6c64 ;# Push the part "lld." of the string "example.dll" onto the stack
push 0x2e656c70 ;# Push the part "elpm" of the string "example.dll" onto the stack
push 0x6d617865 ;# Push the part "axe" of the string "example.dll" onto the stack
push esp ;# Push ESP to have a pointer to the string that is currently located on the stack
call dword ptr [ebp-0x04] ;# Call LoadLibraryA
```
#### Write ASCII String to Memory
Generate code for writing an ASCII string to the given memory address:
```bash
$ shellcrafter codegen write --ascii-string "http://example.com" --write-addr "[eax]"
write_str: ;# write http://example.com to [eax]
xor eax, eax ;# NULL EAX
xor ecx, ecx ;# NULL ECX
lea eax, [eax] ;# Load the address to write to into EAX
mov ecx, 0x70747468 ;# Move the part "http" of the string "http://example.com" to ECX
mov [eax], ecx ;# Write the part "http" of the string "http://example.com" to memory
mov ecx, 0x652f2f3a ;# Move the part "://e" of the string "http://example.com" to ECX
mov [eax+0x04], ecx ;# Write the part "://e" of the string "http://example.com" to memory
mov ecx, 0x706d6178 ;# Move the part "xamp" of the string "http://example.com" to ECX
mov [eax+0x08], ecx ;# Write the part "xamp" of the string "http://example.com" to memory
mov ecx, 0x632e656c ;# Move the part "le.c" of the string "http://example.com" to ECX
mov [eax+0x0c], ecx ;# Write the part "le.c" of the string "http://example.com" to memory
mov ecx, 0x00006d6f ;# Move the part "om" of the string "http://example.com" to ECX
mov [eax+0x10], ecx ;# Write the part "om" of the string "http://example.com" to memory
```
### Gadget Finder
Search for gadgets in binary files:
```bash
$ shellcrafter gadgets find-gadgets "wsock32.dll"
```
### Compute Hash of a Function Name
Get ROR13 hash of the given string:
```bash
$ shellcrafter codegen hash "CreateProcess"
Hash: 0x7fc622d6
```
Raw data
{
"_id": null,
"home_page": "https://github.com/totekuh/shellcrafter",
"name": "shellcrafter",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "totekuh",
"author_email": "totekuh@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/21/e5/e3d938a80684f6995f276ac6b82ae70381bef3a51512dd69fb6d626f386d/shellcrafter-1.1.3.tar.gz",
"platform": null,
"description": "# Shellcrafter\n\nShellcrafter is a comprehensive toolkit designed for shellcode development and gadget finding. It integrates several utilities to assist in the generation of shellcode from assembly instructions, conversion of ASCII text to hexadecimal stack push instructions, loading of DLLs, finding ROP gadgets, and more.\n\n## Installation\n\nTo install Shellcrafter, you can either install it directly using pip if it's available in the Python Package Index or by cloning the repository and installing it locally:\n\n```bash\n$ pip3 install shellcrafter\n```\n\nOr clone the repository and install using:\n\n```bash\n$ git clone https://github.com/totekuh/shellcrafter.git\n$ cd shellcrafter\n$ pip3 install .\n```\n\n## Usage\n\nShellcrafter is structured around multiple command-line utilities grouped under a Typer application. \n\nHere's how to use the various utilities:\n\n### Keystone API - Shellcode Compiler\n\nCompile shellcode from assembly instructions:\n\n```bash\n$ shellcrafter shellcode compile --instructions \"mov ax, 1\"\n[+] 1 instructions have been encoded\nshellcode = b\"\"\nshellcode += b\"\\x66\\xb8\\x01\\x00\"\nshellcode_len = 4\n```\n\nAlso for x64:\n\n```bash\n$ shellcrafter shellcode compile --instructions \"mov ax, 1\" --arch x64\n```\n\nSupports compiling shellcode from a file:\n\n```bash\n$ cat hash.asm\n\ncompute_hash:\n xor eax, eax ;# NULL EAX\n cdq ;# NULL EDX\n cld ;# clear direction (clears the direction flag DF in the EFLAGS register)\n\ncompute_hash_again:\n lodsb ;# load the next byte from ESI into AL\n test al, al ;# check if AL contains the NULL terminator\n jz compute_hash_finished ;# if the ZF is set, we've hit the NULL terminator\n ror edx, 0x0d ;# rotate EDX 13 bits to the right\n add edx, eax ;# add the new hashed byte to the accumulator\n jmp compute_hash_again ;# next iteration\n\ncompute_hash_finished:\n$ shellcrafter shellcode compile -if hash.asm \n[+] 24 instructions have been encoded\nshellcode = b\"\"\nshellcode += b\"\\x31\\xc0\\x99\\xfc\\xac\\x84\\xc0\\x74\\x07\\xc1\\xca\\x0d\\x01\\xc2\\xeb\\xf4\"\nshellcode_len = 16\n```\n\nFor more help:\n\n```bash\nshellcrafter shellcode compile --help\n```\n\n### Shellcode Generator\n\nThis tool can generate various types of shellcode operations:\n\n#### Generate Stack Push Instructions for an ASCII String\n\nGenerate instructions for pushing the `example.dll` string on the stack:\n```bash\nshellcrafter codegen push-ascii --ascii-string \"example.dll\"\npush_str: ;# push the 'example.dll' onto the stack\n push 0x006c6c64 ;# Push the part \"lld.\" of the string \"example.dll\" onto the stack\n push 0x2e656c70 ;# Push the part \"elpm\" of the string \"example.dll\" onto the stack\n push 0x6d617865 ;# Push the part \"axe\" of the string \"example.dll\" onto the stack\n```\n\nUse the negate operation to avoid NULL byte if necessary:\n\n```bash\nshellcrafter codegen push-ascii --ascii-string \"example.dll\" --null-free\npush_str: ;# push the 'example.dll' onto the stack\n mov eax, 0xff93939c ;# Move the negated value of the part \"lld.\" of the string \"example.dll\" to EAX to avoid NULL bytes\n neg eax ;# Negate EAX to get the original value\n push eax ;# Push EAX onto the stack\n push 0x2e656c70 ;# Push the part \"elpm\" of the string \"example.dll\" onto the stack\n push 0x6d617865 ;# Push the part \"axe\" of the string \"example.dll\" onto the stack\n```\n\n#### Load a DLL\n\nGenerate code for loading a DLL into the target process. \nThe DLL's name and the address of the LoadLibraryA function have to be provided.\n```bash\nshellcrafter codegen load-library --dll-name \"example.dll\" --load-library-addr \"[ebp-0x04]\"\nload_lib: ;# load the example.dll DLL\n xor eax, eax ;# NULL EAX\n push eax ;# Push NULL terminator for the string\n push 0x006c6c64 ;# Push the part \"lld.\" of the string \"example.dll\" onto the stack\n push 0x2e656c70 ;# Push the part \"elpm\" of the string \"example.dll\" onto the stack\n push 0x6d617865 ;# Push the part \"axe\" of the string \"example.dll\" onto the stack\n push esp ;# Push ESP to have a pointer to the string that is currently located on the stack\n call dword ptr [ebp-0x04] ;# Call LoadLibraryA\n```\n\n#### Write ASCII String to Memory\n\nGenerate code for writing an ASCII string to the given memory address:\n\n```bash\n$ shellcrafter codegen write --ascii-string \"http://example.com\" --write-addr \"[eax]\"\nwrite_str: ;# write http://example.com to [eax]\n xor eax, eax ;# NULL EAX\n xor ecx, ecx ;# NULL ECX\n lea eax, [eax] ;# Load the address to write to into EAX\n mov ecx, 0x70747468 ;# Move the part \"http\" of the string \"http://example.com\" to ECX\n mov [eax], ecx ;# Write the part \"http\" of the string \"http://example.com\" to memory\n mov ecx, 0x652f2f3a ;# Move the part \"://e\" of the string \"http://example.com\" to ECX\n mov [eax+0x04], ecx ;# Write the part \"://e\" of the string \"http://example.com\" to memory\n mov ecx, 0x706d6178 ;# Move the part \"xamp\" of the string \"http://example.com\" to ECX\n mov [eax+0x08], ecx ;# Write the part \"xamp\" of the string \"http://example.com\" to memory\n mov ecx, 0x632e656c ;# Move the part \"le.c\" of the string \"http://example.com\" to ECX\n mov [eax+0x0c], ecx ;# Write the part \"le.c\" of the string \"http://example.com\" to memory\n mov ecx, 0x00006d6f ;# Move the part \"om\" of the string \"http://example.com\" to ECX\n mov [eax+0x10], ecx ;# Write the part \"om\" of the string \"http://example.com\" to memory\n```\n\n### Gadget Finder\n\nSearch for gadgets in binary files:\n\n```bash\n$ shellcrafter gadgets find-gadgets \"wsock32.dll\"\n```\n\n### Compute Hash of a Function Name\n\nGet ROR13 hash of the given string:\n\n```bash\n$ shellcrafter codegen hash \"CreateProcess\"\nHash: 0x7fc622d6\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A package containing scripts for developing and generating shellcode",
"version": "1.1.3",
"project_urls": {
"Bug Reports": "https://github.com/totekuh/shellcrafter/issues",
"Homepage": "https://github.com/totekuh/shellcrafter",
"Source": "https://github.com/totekuh/shellcrafter"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9335cfd7bbafb3448fb0f7f53c47e8c65b810890667a927d10fcc17fdb7916d4",
"md5": "6e2e665459545ce650f04cc10b2e9a40",
"sha256": "ae6250153b090d9d54dc6aefafaaab66621d97abb71c460c3ba6d4ca309c7c7e"
},
"downloads": -1,
"filename": "shellcrafter-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e2e665459545ce650f04cc10b2e9a40",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19749,
"upload_time": "2024-05-05T01:32:48",
"upload_time_iso_8601": "2024-05-05T01:32:48.800690Z",
"url": "https://files.pythonhosted.org/packages/93/35/cfd7bbafb3448fb0f7f53c47e8c65b810890667a927d10fcc17fdb7916d4/shellcrafter-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "21e5e3d938a80684f6995f276ac6b82ae70381bef3a51512dd69fb6d626f386d",
"md5": "c45ece33553a6383fb42cf3f3e6f0671",
"sha256": "eb419d599811c28b2b7604e31b75ef226774d271b6e72af3c4f7b5712e15cc6e"
},
"downloads": -1,
"filename": "shellcrafter-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "c45ece33553a6383fb42cf3f3e6f0671",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19309,
"upload_time": "2024-05-05T01:32:49",
"upload_time_iso_8601": "2024-05-05T01:32:49.908834Z",
"url": "https://files.pythonhosted.org/packages/21/e5/e3d938a80684f6995f276ac6b82ae70381bef3a51512dd69fb6d626f386d/shellcrafter-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-05 01:32:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "totekuh",
"github_project": "shellcrafter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "shellcrafter"
}
JSON
