{"id":17383767,"url":"https://github.com/totekuh/shellcrafter","last_synced_at":"2025-04-15T10:05:31.802Z","repository":{"id":159054100,"uuid":"626508342","full_name":"totekuh/shellcrafter","owner":"totekuh","description":"Scripts, tools and code snippets for exploit development/assembly/shellcoding","archived":false,"fork":false,"pushed_at":"2024-05-13T17:59:02.000Z","size":82,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-15T10:04:53.876Z","etag":null,"topics":["assembly","exploit","exploit-development","keystone","pip","python3","shellcode"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/totekuh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-04-11T15:53:19.000Z","updated_at":"2024-10-03T06:30:20.000Z","dependencies_parsed_at":"2024-04-14T02:54:17.353Z","dependency_job_id":"38a6c762-b173-41c5-a788-27127df750b8","html_url":"https://github.com/totekuh/shellcrafter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totekuh%2Fshellcrafter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totekuh%2Fshellcrafter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totekuh%2Fshellcrafter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/totekuh%2Fshellcrafter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/totekuh","download_url":"https://codeload.github.com/totekuh/shellcrafter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249048730,"owners_count":21204306,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly","exploit","exploit-development","keystone","pip","python3","shellcode"],"created_at":"2024-10-16T07:43:43.387Z","updated_at":"2025-04-15T10:05:31.783Z","avatar_url":"https://github.com/totekuh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftotekuh%2Fshellcrafter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftotekuh%2Fshellcrafter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftotekuh%2Fshellcrafter/lists"}