{"id":13395922,"url":"https://github.com/sashs/Ropper","last_synced_at":"2025-03-13T22:31:20.672Z","repository":{"id":20243413,"uuid":"23515831","full_name":"sashs/Ropper","owner":"sashs","description":"Display information about files in different file formats and find gadgets to build rop chains for different architectures (x86/x86_64, ARM/ARM64, MIPS, PowerPC, SPARC64). For disassembly ropper uses the awesome Capstone Framework. ","archived":false,"fork":false,"pushed_at":"2024-07-30T20:07:33.000Z","size":2494,"stargazers_count":1853,"open_issues_count":37,"forks_count":207,"subscribers_count":53,"default_branch":"master","last_synced_at":"2024-10-10T13:23:58.912Z","etag":null,"topics":["binary","exploitation","gadget-finder","gadgets","rop","rop-chains"],"latest_commit_sha":null,"homepage":"https://scoding.de/ropper","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sashs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-31T14:53:12.000Z","updated_at":"2024-10-06T02:12:18.000Z","dependencies_parsed_at":"2024-01-11T23:24:38.585Z","dependency_job_id":"57895498-2fe8-4082-9b8c-6eb47c44ebd8","html_url":"https://github.com/sashs/Ropper","commit_stats":null,"previous_names":[],"tags_count":87,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashs%2FRopper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashs%2FRopper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashs%2FRopper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashs%2FRopper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sashs","download_url":"https://codeload.github.com/sashs/Ropper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221417265,"owners_count":16816848,"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":["binary","exploitation","gadget-finder","gadgets","rop","rop-chains"],"created_at":"2024-07-30T18:00:35.662Z","updated_at":"2024-10-25T10:31:04.333Z","avatar_url":"https://github.com/sashs.png","language":"Python","readme":"Ropper\n================\n[![Build Status](https://travis-ci.org/sashs/Ropper.svg?branch=master)](https://travis-ci.org/sashs/Ropper)\n\nYou can use ropper to display information about binary files in different file formats\nand you can search for gadgets to build rop chains for different architectures (x86/X86_64, ARM/ARM64, MIPS/MIPS64, PowerPC/PowerPC64, SPARC64).\nFor disassembly ropper uses the awesome [Capstone Framework](http://www.capstone-engine.org).\n\nInstall\n-------\n\nInstall [Capstone](http://www.capstone-engine.org) with PyPi:\n\n    $ sudo pip install capstone\n\nInstall [filebytes](https://github.com/sashs/filebytes) with PyPi:\n\n    $ sudo pip install filebytes\n\nOptional (not needed to run ropper just to look for gadgets):\n\nInstall [Keystone](http://www.keystone-engine.org):\n\n    $ sudo pip install keystone-engine\n\nInstall and execute Ropper\n\n    $ python setup.py install\n    $ ropper\n\nYou can also install Ropper with pip\n\n    $ pip install ropper\n\nIf you want, you can use Ropper without installation\n\n    $ ./Ropper.py\n\nIf you don't want to install filebytes, filebytes is a submodule of the ropper repository. This means you don't need to install filebytes and ropper.\n\n    $ git clone https://github.com/sashs/ropper.git\n    $ cd ropper\n    $ git submodule init\n    $ git submodule update\n    $ ./Ropper.py\n\nTHIS FEATURE IS STILL UNDER DEVELOPEMENT!\nRopper has a semantic search command, which offers the possiblity to search for gadgets.\n\n    $ ropper --file \u003cafile\u003e --semantic \"\u003cany constraint\u003e\"\n\nThe following optional dependencies are needed to use semantic search:\n\nInstall [pyvex](https://github.com/angr/pyvex)\n\n    $ sudo pip install pyvex\n\nInstall [z3py](https://github.com/Z3Prover/z3)\n    \n    $ python scripts/mk_make.py\n    $ cd build\n    $ make\n    $ sudo make install\n\nCurrently Possible Constraints\n------------------------------\n    reg == reg     -  assign register to another\n    reg == number  -  assign number to register\n    reg == [reg]   -  assign memory to register\n    reg += number/reg/[reg]\n    reg -= number/reg/[reg]\n    reg *= number/reg/[reg]\n    reg /= number/reg/[reg]\n    \nConstraint Example\n------------------\n\n    eax==1 !ebx    - set eax to 1 and look for gadgets which does not clobber ebx\n\n\n\u003cimg src=\"https://scoding.de/uploads/semantic_search.png\" alt=\"semantic_search\"\u003e\u003c/img\u003e\n\nUsage\n-----\n\n    usage: Ropper.py [-h] [--help-examples] [-v] [--console]\n                 [-f \u003cfile\u003e [\u003cfile\u003e ...]] [-r] [-a \u003carch\u003e]\n                 [--section \u003csection\u003e] [--string [\u003cstring\u003e]] [--hex]\n                 [--asm [\u003casm\u003e [H|S|R] ...]] [--disasm \u003copcode\u003e]\n                 [--disassemble-address \u003caddress:length\u003e] [-i] [-e]\n                 [--imagebase] [-c] [-s] [-S] [--imports] [--symbols]\n                 [--set \u003coption\u003e] [--unset \u003coption\u003e] [-I \u003cimagebase\u003e] [-p]\n                 [-j \u003creg\u003e] [--stack-pivot] [--inst-count \u003cn bytes\u003e]\n                 [--search \u003cregex\u003e] [--quality \u003cquality\u003e] [--opcode \u003copcode\u003e]\n                 [--instructions \u003cinstructions\u003e] [--type \u003ctype\u003e] [--detailed]\n                 [--all] [--cfg-only] [--chain \u003cgenerator\u003e] [-b \u003cbadbytes\u003e]\n                 [--nocolor] [--clear-cache] [--no-load] [--analyse \u003cquality\u003e]\n                 [--semantic constraint]\n                 [--count-of-findings \u003ccount of gadgets\u003e] [--single]\n\n    You can use ropper to display information about binary files in different file formats\n        and you can search for gadgets to build rop chains for different architectures\n\n    supported filetypes:\n      ELF\n      PE\n      Mach-O\n      Raw\n\n    supported architectures:\n      x86 [x86]\n      x86_64 [x86_64]\n      MIPS [MIPS, MIPS64]\n      ARM/Thumb [ARM, ARMTHUMB]\n      ARM64 [ARM64]\n      PowerPC [PPC, PPC64]\n      SPARC [SPARC64]\n\n    available rop chain generators:\n      execve (execve[=\u003ccmd\u003e], default /bin/sh) [Linux x86, x86_64]\n      mprotect  (mprotect=\u003caddress\u003e:\u003csize\u003e) [Linux x86, x86_64]\n      virtualprotect (virtualprotect=\u003caddress iat vp\u003e:\u003csize\u003e) [Windows x86]\n\n    options:\n      -h, --help            show this help message and exit\n      --help-examples       Print examples\n      -v, --version         Print version\n      --console             Starts interactive commandline\n      -f \u003cfile\u003e [\u003cfile\u003e ...], --file \u003cfile\u003e [\u003cfile\u003e ...]\n                            The file to load\n      -r, --raw             Loads the file as raw file\n      -a \u003carch\u003e, --arch \u003carch\u003e\n                            The architecture of the loaded file\n      --section \u003csection\u003e   The data of this section should be printed\n      --string [\u003cstring\u003e]   Looks for the string \u003cstring\u003e in all data sections\n      --hex                 Prints the selected sections in a hex format\n      --asm [\u003casm\u003e [H|S|R] ...]\n                            A string to assemble and a format of the output\n                            (H=HEX, S=STRING, R=RAW, default: H)\n      --disasm \u003copcode\u003e     Opcode to disassemble (e.g. ffe4, 89c8c3, ...)\n      --disassemble-address \u003caddress:length\u003e\n                            Disassembles instruction at address \u003caddress\u003e\n                            (0x12345678:L3). The count of instructions to\n                            disassemble can be specified (0x....:L...)\n      -i, --info            Shows file header [ELF/PE/Mach-O]\n      -e                    Shows EntryPoint\n      --imagebase           Shows ImageBase [ELF/PE/Mach-O]\n      -c, --dllcharacteristics\n                            Shows DllCharacteristics [PE]\n      -s, --sections        Shows file sections [ELF/PE/Mach-O]\n      -S, --segments        Shows file segments [ELF/Mach-O]\n      --imports             Shows imports [ELF/PE]\n      --symbols             Shows symbols [ELF]\n      --set \u003coption\u003e        Sets options. Available options: aslr nx\n      --unset \u003coption\u003e      Unsets options. Available options: aslr nx\n      -I \u003cimagebase\u003e        Use this imagebase for gadgets\n      -p, --ppr             Searches for 'pop reg; pop reg; ret' instructions\n                            [only x86/x86_64]\n      -j \u003creg\u003e, --jmp \u003creg\u003e\n                            Searches for 'jmp reg' instructions (-j reg[,reg...])\n                            [only x86/x86_64]\n      --stack-pivot         Prints all stack pivot gadgets\n      --inst-count \u003cn bytes\u003e\n                            Specifies the max count of instructions in a gadget\n                            (default: 6)\n      --search \u003cregex\u003e      Searches for gadgets\n      --quality \u003cquality\u003e   The quality for gadgets which are found by search (1 =\n                            best)\n      --opcode \u003copcode\u003e     Searches for opcodes (e.g. ffe4 or ffe? or ff??)\n      --instructions \u003cinstructions\u003e\n                            Searches for instructions (e.g. \"jmp esp\", \"pop eax;\n                            ret\")\n      --type \u003ctype\u003e         Sets the type of gadgets [rop, jop, sys, all]\n                            (default: all)\n      --detailed            Prints gadgets more detailed\n      --all                 Does not remove duplicate gadgets\n      --cfg-only            Filters out gadgets which fail the Microsoft CFG\n                            check. Only for PE files which are compiled with CFG\n                            check enabled (check DllCharachteristics) [PE]\n      --chain \u003cgenerator\u003e   Generates a ropchain [generator parameter=value[\n                            parameter=value]]\n      -b \u003cbadbytes\u003e, --badbytes \u003cbadbytes\u003e\n                            Set bytes which should not be contained in gadgets\n      --nocolor             Disables colored output\n      --clear-cache         Clears the cache\n      --no-load             Don't load the gadgets automatically when starting the\n                            console (--console)\n      --analyse \u003cquality\u003e   just used for the implementation of semantic search\n      --semantic constraint\n                            semantic search for gadgets\n      --count-of-findings \u003ccount of gadgets\u003e\n                            Max count of gadgets which will be printed with\n                            semantic search (0 = undefined, default: 5)\n      --single              No multiple processes are used for gadget scanning\n\n    example uses:\n      [Generic]\n      ./Ropper.py\n      ./Ropper.py --file /bin/ls --console\n\n      [Informations]\n      ./Ropper.py --file /bin/ls --info\n      ./Ropper.py --file /bin/ls --imports\n      ./Ropper.py --file /bin/ls --sections\n      ./Ropper.py --file /bin/ls --segments\n      ./Ropper.py --file /bin/ls --set nx\n      ./Ropper.py --file /bin/ls --unset nx\n      ./Ropper.py --file /bin/ls --inst-count 5\n      ./Ropper.py --file /bin/ls --search \"sub eax\" --badbytes 000a0d\n      ./Ropper.py --file /bin/ls --search \"sub eax\" --detail\n      ./Ropper.py --file /bin/ls --filter \"sub eax\"\n      ./Ropper.py --file /bin/ls --inst-count 5 --filter \"sub eax\"\n      ./Ropper.py --file /bin/ls --opcode ffe4\n      ./Ropper.py --file /bin/ls --opcode ffe?\n      ./Ropper.py --file /bin/ls --opcode ??e4\n      ./Ropper.py --file /bin/ls --detailed\n      ./Ropper.py --file /bin/ls --ppr --nocolor\n      ./Ropper.py --file /bin/ls --jmp esp,eax\n      ./Ropper.py --file /bin/ls --type jop\n      ./Ropper.py --file /bin/ls --chain execve\n      ./Ropper.py --file /bin/ls --chain \"execve cmd=/bin/sh\" --badbytes 000a0d\n      ./Ropper.py --file /bin/ls --chain \"mprotect address=0xbfdff000 size=0x21000\"\n      ./Ropper.py --file /bin/ls /lib/libc.so.6 --console\n\n      [Assemble/Disassemble]\n      ./Ropper.py --asm \"jmp esp\"\n      ./Ropper.py --asm \"mov eax, ecx; ret\"\n      ./Ropper.py --disasm ffe4\n\n      [Search]\n      ./Ropper.py --file /bin/ls --search \u003csearchstring\u003e\n      ?     any character\n      %     any string\n\n      Example:\n\n      ./Ropper.py --file /bin/ls --search \"mov e?x\"\n      0x000067f1: mov edx, dword ptr [ebp + 0x14]; mov dword ptr [esp], edx; call eax\n      0x00006d03: mov eax, esi; pop ebx; pop esi; pop edi; pop ebp; ret ;\n      0x00006d6f: mov ebx, esi; mov esi, dword ptr [esp + 0x18]; add esp, 0x1c; ret ;\n      0x000076f8: mov eax, dword ptr [eax]; mov byte ptr [eax + edx], 0; add esp, 0x18; pop ebx; ret ;\n\n      ./Ropper.py --file /bin/ls --search \"mov [%], edx\"\n      0x000067ed: mov dword ptr [esp + 4], edx; mov edx, dword ptr [ebp + 0x14]; mov dword ptr [esp], edx; call eax;\n      0x00006f4e: mov dword ptr [ecx + 0x14], edx; add esp, 0x2c; pop ebx; pop esi; pop edi; pop ebp; ret ;\n      0x000084b8: mov dword ptr [eax], edx; ret ;\n      0x00008d9b: mov dword ptr [eax], edx; add esp, 0x18; pop ebx; ret ;\n\n      ./Ropper.py --file /bin/ls --search \"mov [%], edx\" --quality 1\n      0x000084b8: mov dword ptr [eax], edx; ret ;; ret ;\n\n\nUse ropper in Scripts\n---------------------\n```python\n#!/usr/bin/env python\nfrom ropper import RopperService\n\n# not all options need to be given\noptions = {'color' : False,     # if gadgets are printed, use colored output: default: False\n            'badbytes': '00',   # bad bytes which should not be in addresses or ropchains; default: ''\n            'all' : False,      # Show all gadgets, this means to not remove double gadgets; default: False\n            'inst_count' : 6,   # Number of instructions in a gadget; default: 6\n            'type' : 'all',     # rop, jop, sys, all; default: all\n            'detailed' : False} # if gadgets are printed, use detailed output; default: False\n\nrs = RopperService(options)\n\n##### change options ######\nrs.options.color = True\nrs.options.badbytes = '00'\nrs.options.badbytes = ''\nrs.options.all = True\n\n\n##### open binaries ######\n# it is possible to open multiple files\nrs.addFile('test-binaries/ls-x86')\nrs.addFile('ls', bytes=open('test-binaries/ls-x86','rb').read()) # other possiblity\nrs.addFile('ls_raw', bytes=open('test-binaries/ls-x86','rb').read(), raw=True, arch='x86')\n\n##### close binaries ######\nrs.removeFile('ls')\nrs.removeFile('ls_raw')\n\n\n# Set architecture of a binary, so it is possible to look for gadgets for a different architecture\n# It is useful for ARM if you want to look for ARM gadgets or Thumb gadgets\n# Or if you opened a raw file\nls = 'test-binaries/ls-x86'\nrs.setArchitectureFor(name=ls, arch='x86')\nrs.setArchitectureFor(name=ls, arch='x86_64')\nrs.setArchitectureFor(name=ls, arch='ARM')\nrs.setArchitectureFor(name=ls, arch='ARMTHUMB')\nrs.setArchitectureFor(name=ls, arch='ARM64')\nrs.setArchitectureFor(name=ls, arch='MIPS')\nrs.setArchitectureFor(name=ls, arch='MIPS64')\nrs.setArchitectureFor(name=ls, arch='PPC')\nrs.setArchitectureFor(name=ls, arch='PPC64')\nrs.setArchitectureFor(name=ls, arch='SPARC64')\nrs.setArchitectureFor(name=ls, arch='x86')\n\n\n##### load gadgets ######\n\n# load gadgets for all opened files\nrs.loadGadgetsFor() \n\n# load gadgets for only one opened file\nls = 'test-binaries/ls-x86'\nrs.loadGadgetsFor(name=ls)\n\n# change gadget type\nrs.options.type = 'jop'\nrs.loadGadgetsFor() \n\nrs.options.type = 'rop'\nrs.loadGadgetsFor() \n\n# change instruction count\nrs.options.inst_count = 10\nrs.loadGadgetsFor() \n\n##### print gadgets #######\nrs.printGadgetsFor() # print all gadgets\nrs.printGadgetsFor(name=ls)\n\n##### Get gadgets ######\ngadgets = rs.getFileFor(name=ls).gadgets\n\n\n##### search pop pop ret ######\npprs = rs.searchPopPopRet(name=ls) # looks for ppr only in 'test-binaries/ls-x86'\npprs = rs.searchPopPopRet()        # looks for ppr in all opened files\nfor file, ppr in pprs.items():\n    for p in ppr:\n        print p\n\n##### load jmp reg ######\njmp_regs = rs.searchJmpReg(name=ls, regs=['esp', 'eax']) # looks for jmp reg only in 'test-binaries/ls-x86'\njmp_regs = rs.searchJmpReg(regs=['esp', 'eax'])\njmp_regs = rs.searchJmpReg()                             # looks for jmp esp in all opened files\nfor file, jmp_reg in jmp_regs.items():\n    for j in jmp_reg:\n        print j\n\n\n##### search opcode ######\nls = 'test-binaries/ls-x86'\ngadgets_dict = rs.searchOpcode(opcode='ffe4', name=ls)\ngadgets_dict = rs.searchOpcode(opcode='ffe?')\ngadgets_dict = rs.searchOpcode(opcode='??e4')\n\nfor file, gadgets in gadgets_dict.items():\n    for g in gadgets:\n        print g\n\n##### search instructions ######\nls = 'test-binaries/ls-x86'\nfor file, gadget in rs.search(search='mov e?x', name=ls):\n    print file, gadget\n\nfor file, gadget in rs.search(search='mov [e?x%]'):\n    print file, gadget    \n\nresult_dict = rs.searchdict(search='mov eax')\nfor file, gadgets in result_dict.items():\n    print file\n    for gadget in gadgets:\n        print gadget\n\n##### assemble instructions ######\nhex_string = rs.asm('jmp esp')\nprint '\"jmp esp\" assembled to hex string =', hex_string\nraw_bytes = rs.asm('jmp esp', format='raw')\nprint '\"jmp esp\" assembled to raw bytes =', raw_bytes\nstring = rs.asm('jmp esp', format='string')\nprint '\"jmp esp\" assembled to string =',string\narm_bytes = rs.asm('bx sp', arch='ARM')\nprint '\"bx sp\" assembled to hex string =', arm_bytes\n\n##### disassemble bytes #######\narm_instructions = rs.disasm(arm_bytes, arch='ARM')\nprint arm_bytes, 'disassembled to \"%s\"' % arm_instructions\n\n# Change the imagebase, this also change the imagebase for all loaded gadgets of this binary\nrs.setImageBaseFor(name=ls, imagebase=0x0)\n\n# reset image base\nrs.setImageBaseFor(name=ls, imagebase=None)\n\ngadgets = rs.getFileFor(name=ls).gadgets\n\n# gadget address\nprint hex(gadgets[0].address)\n\n# get instruction bytes of gadget\nprint bytes(gadgets[0].bytes).encode('hex')\n\n# remove all gadgets containing bad bytes in address\nrs.options.badbytes = '000a0d'  # gadgets are filtered automatically\n```\n\nProject page\n------------------------------------\nhttp://scoding.de/ropper\n\n\nScreenshots\n------------------------------------\n\n\u003cimg src=\"https://scoding.de/uploads/load.jpg\" alt=\"load\"\u003e\u003c/img\u003e\n\n\u003cimg src=\"https://scoding.de/uploads/x86.jpg\" alt=\"x86\"\u003e\u003c/img\u003e\n\n\u003cimg src=\"https://scoding.de/uploads/arm.jpg\" alt=\"arm\"\u003e\u003c/img\u003e\n\n\u003cimg src=\"https://scoding.de/uploads/mips.jpg\" alt=\"mips\"\u003e\u003c/img\u003e\n\n\u003cimg src=\"https://scoding.de/uploads/ppc.jpg\" alt=\"ppc\"\u003e\u003c/img\u003e\n\n\u003cimg src=\"https://scoding.de/uploads/ropchain.jpg\" alt=\"ropchain\"\u003e\u003c/img\u003e\n\n\u003cimg src=\"https://scoding.de/uploads/header.jpg\" alt=\"header\"\u003e\u003c/img\u003e\n\n","funding_links":[],"categories":["[*] System hacking / Pwnable","Python","Python (144)","others","Tools","Exploiting / Pwn","Programming/Comp Sci/SE Things"],"sub_categories":["[+] TIP \u0026 Tools  :+1:","Exploitation/PWN"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsashs%2FRopper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsashs%2FRopper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsashs%2FRopper/lists"}