{"id":13483733,"url":"https://github.com/pfalcon/ScratchABit","last_synced_at":"2025-03-27T15:30:29.417Z","repository":{"id":30236788,"uuid":"33787951","full_name":"pfalcon/ScratchABit","owner":"pfalcon","description":"Easily retargetable and hackable interactive disassembler with IDAPython-compatible plugin API","archived":false,"fork":false,"pushed_at":"2020-11-25T22:03:17.000Z","size":879,"stargazers_count":394,"open_issues_count":29,"forks_count":47,"subscribers_count":31,"default_branch":"master","last_synced_at":"2024-10-11T15:10:15.864Z","etag":null,"topics":["disassembler","ida","ida-plugin","idapython","reverse-engineering"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pfalcon.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}},"created_at":"2015-04-11T18:50:22.000Z","updated_at":"2024-10-03T05:11:51.000Z","dependencies_parsed_at":"2022-08-31T02:00:07.389Z","dependency_job_id":null,"html_url":"https://github.com/pfalcon/ScratchABit","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2FScratchABit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2FScratchABit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2FScratchABit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2FScratchABit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pfalcon","download_url":"https://codeload.github.com/pfalcon/ScratchABit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245871682,"owners_count":20686246,"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":["disassembler","ida","ida-plugin","idapython","reverse-engineering"],"created_at":"2024-07-31T17:01:14.736Z","updated_at":"2025-03-27T15:30:28.908Z","avatar_url":"https://github.com/pfalcon.png","language":"Python","readme":"ScratchABit\n===========\n\nScratchABit is an interactive incremental disassembler with data/control\nflow analysis capabilities. ScratchABit is dedicated to the efforts of\nthe OpenSource reverse engineering community (reverse engineering to\nproduce OpenSource drivers/firmware for hardware not properly supported\nby vendors, for hardware and software interoperability, for security\nresearch).\n\nScratchABit supports well-known in the community IDAPython API to write\ndisassembly/extension modules.\n\nScratchABit is a work in progress, features are added on as needed basis,\ncontributions are welcome.\n\nScratchABit is released under the terms of GNU General Public License v3\n(GPLv3).\n\n\nRequirements/manifesto\n----------------------\n\n1. Should not be written in an obfuscated language. These include languages\nwhich are too low-level, which allow to access non-initialized variables,\nwhich don't differentiate between variables and functions/procedures, which\nstart array indexes from arbitrary numbers, etc., etc. ScratchABit is\nwritten in Python (modern version, Python3) for your pleasure and sanity.\n\n2. User interface framework should allow user interaction of the needed\nlevel, not add dependencies, bloat, issues, and incompatibilities between\nframework's versions. ScratchABit currently uses simple full-screen text\nuser interface, using ANSI/VT100 terminal escape sequences (yes, even\ncurses library was deemed too bloat a dependency to force upon users).\n\n3. Should leverage easy to use text formats to store \"database\", to\nfacilitate easy reuse and tool writing, and storage in version control\nsystems.\n\n\nInstallation\n------------\n\nTo use ScratchABit, you need [Python3](https://www.python.org/) installed\n(tested with Python 3.3 thru 3.7) and VT100 (minimum) or XTerm (recommended)\nterminal or terminal emulator (any Unix system should be compliant, like\nLinux/BSD/etc., see FAQ below for more).\n\nClone the code using:\n\n    git clone --recursive https://github.com/pfalcon/ScratchABit\n\nIf you cloned code without `--recursive`, run `git submodule update --init`\nin the ScratchABit directory.\n\nScratchABit now ships with [Capstone Engine](http://www.capstone-engine.org/)\nbased CPU plugin(s), which allow access to a number of CPU architectures.\nTo use it, recent Python bindings module for Capstone should be installed\n(in the preference to packages shipped by OS distributions, which are often\noutdated). The easiest way to install it is into the Python user packages\ndirectory:\n\n    pip3 install --no-cache-dir --user capstone\n\nAn alternative is to install it to a Python\n[virtual environment](https://docs.python.org/3/library/venv.html) within\nthe ScratchABit directory:\n\n    python3 -m venv .venv\n    source .venv/bin/activate\n    pip3 install --no-cache-dir capstone\n\nWhenever you open a new terminal session to work with ScratchABit,\nrun `source .venv/bin/activate` command again to activate the virtual\nenvironment.\n\nIf nothing of the above works, you can try to install the capstone\npackage system-wide (not recommended):\n\n    sudo pip3 install --system capstone\n\n\nQuick start\n-----------\n\nIf you want to disassemble a file in self-describing executable format\n(like ELF), just pass it as an argument to `ScratchABit.py`. The repository\nincludes a number of `example-*.elf` files for various architectures for\na quick start. For example, to try x86 32bit version:\n\n    python3 ScratchABit.py example-x86_32.elf\n\nAlternatively, if you want to disassemble a raw binary file, you need\nto create a .def (definition) file, to specify what memory areas are\ndefined for the code, at which address to load binary file, etc. (Note:\na .def file may be useful for .elf and similar files too.) The repository\nincludes a simple x86_64 raw binary code, and the corresponding\n[example-x86_64.def](example-x86_64.def) file (look inside for\ndescription of available options):\n\n    python3 ScratchABit.py example-x86_64.def\n\nPress F9 to access menus (mouse works too in XTerm-compatible terminals).\nPress F1 to get help about key bindings (most actions are also accessible\nvia menu). The workflow of ScratchABit is similar to other interactive\ndissamblers (some previous experience or background reading may be helpful).\n\nUsing Plugins\n-------------\n\nIDAPython processor plugins can be loaded from anywhere on the Python\nmodule path. Alternatively, you can symlink/copy the plugin `.py` file(s)\ninto the [`plugins/cpu/`](plugins/cpu/) subdirectory.\n\nAfter the plugin is made available, create a new definition file based\non [`example-x86_64.def`](example-x86_64.def#L4) that sets the plugin module\nname (without `.py` extenstion) in the `cpu xxx` line.\n\nFor a very simple example that uses an external plugin, see this\n[esp8266.def file](https://gist.github.com/projectgus/f898d5798e3e44240796)\nthat works with the xtensa.py plugin from the\n[ida-xtensa2 repository](https://github.com/pfalcon/ida-xtensa2).\n\nTODO/Things to decide\n---------------------\n\n* ~~Currently uses multiple files for \"database\", each storing particular\n  type of information. Switch to a single YAML file instead?~~\n* ~~Add color (low priority, (unbloated!) patches welcome).~~\n* ~~Few important UI commands to implement yet for comfortable work.~~ (\n  All the most important commands should be there, other functionality is\n  expected to be implemented using plugins).\n* ~~Offer to save DB on quit if modified.~~\n* Git integration for DB saving.\n* ~~Improve robustness (add exception handler at the main loop level, don't\n  abort the application, show to user/log and continue).~~\n* Try to deal with code flow inconsistencies (e.g. within an instruction -\n  low priority for intended usage) and data access inconsistencies (e.g.\n  accessing individual bytes of previosly detected word - higher priority).\n  (Improved in 1.4.)\n* See how to support other types of IDAPython plugins besides just processor\n  modules.\n* Parse and use debugging information (e.g. DWARF) present in ELF (etc.)\n  files.\n\n\nFAQ\n---\n\n\u003e Q: What processors/architectures are supported?\n\nA: ScratchABit doesn't support any processor architectures on its own,\nit is fully retargettable using IDAPython API plugins. Many plugins are\navailable, writing a new plugin is easy. To let users test-drive\nScratchABit, a simple x86 processor plugin is included in the\ndistribution, using [Pymsasid](https://github.com/pfalcon/pymsasid3)\ndisassembler under the hood.\n\nFrom version 2.0, [Capstone](http://www.capstone-engine.org/) plugin\nis also included, allowing access to a number of architectures,\nincluding x86, ARM, MIPS, PowerPC, SPARC, etc. (architecture support\nis enabled gradually based on user testing).\n\nYou can read about the plugins shipped together with ScratchABit in\nthe [README for `plugins/cpu/` dir](plugins/cpu/).\n\n\u003e Q: Debugger?\n\nA: ScratchABit is dedicated to static analysis and easy support for\nnew CPU architectures (just code up an new CPU plugin in Python - you\ncan get initial results in few hours). Dynamic analysis wasn't conceived\nto be a core feature and there're no immediate plans to implement it.\nPatches are welcome though.\n\n\u003e Q: Decompiler?\n\nA: There is a related project, called\n[ScratchABlock](https://github.com/pfalcon/ScratchABlock) for deep\nprogram analysis, transformation and decompilation. It's expected\nthat as ScratchABlock matures, some of its functionality will be\navailable within ScratchABit (perhaps via plugins).\n\n\u003e Q: I'm not on Linux, how can I run ScratchABit?\n\nA: Install Linux in an emulator/VM on your system and rejoice.\n\n\u003e Q: Mandatory screenshot?\n\nA: Sure:\n\n![screenshot](https://raw.githubusercontent.com/pfalcon/ScratchABit/master/docs/scratchabit.png)\n","funding_links":[],"categories":["\u003ca id=\"tag-dev\" href=\"#tag-dev\"\u003eDev\u003c/a\u003e","Tools","Python","2. [↑](#-content) Pentesting","工具"],"sub_categories":["\u003ca id=\"tag-dev-other\" href=\"#tag-dev-other\"\u003eOther Dev projects\u003c/a\u003e","Disassemblers and debuggers","2.4 [↑](#-content) Disassembler and debuggers","有关渗透测试和安全方面的Docker镜像"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfalcon%2FScratchABit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpfalcon%2FScratchABit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfalcon%2FScratchABit/lists"}