| blob | eec9b15bd25172e04ed09850279acf4c283a3876 |
1 ScratchABit
2 ===========
4 ScratchABit is an interactive incremental disassembler with data/control
5 flow analysis capabilities. ScratchABit is dedicated to the efforts of
6 the OpenSource reverse engineering community (reverse engineering to
7 produce OpenSource drivers/firmware for hardware not properly supported
8 by vendors, for hardware and software interoperability, for security
9 research).
11 ScratchABit supports well-known in the community IDAPython API to write
12 disassembly/extension modules.
14 ScratchABit is a work in progress, features are added on as needed basis,
15 contributions are welcome.
17 ScratchABit is released under the terms of GNU General Public License v3
18 (GPLv3).
21 Requirements/manifesto
22 ----------------------
24 1. Should not be written in an obfuscated language. These include languages
25 which are too low-level, which allow to access non-initialized variables,
26 which don't differentiate between variables and functions/procedures, which
27 start array indexes from arbitrary numbers, etc., etc. ScratchABit is
28 written in Python (modern version, Python3) for your pleasure and sanity.
30 2. User interface framework should allow user interaction of the needed
31 level, not add dependencies, bloat, issues, and incompatibilities between
32 framework's versions. ScratchABit currently uses simple full-screen text
33 user interface, using ANSI/VT100 terminal escape sequences (yes, even
34 curses library was deemed too bloat a dependency to force upon users).
36 3. Should leverage easy to use text formats to store "database", to
37 facilitate easy reuse and tool writing, and storage in version control
38 systems.
41 Installation
42 ------------
44 To use ScratchABit, you need [Python3](https://www.python.org/) installed
45 (tested with Python 3.3 thru 3.7) and VT100 (minimum) or XTerm (recommended)
46 terminal or terminal emulator (any Unix system should be compliant, like
47 Linux/BSD/etc., see FAQ below for more).
49 Clone the code using:
51 git clone --recursive https://github.com/pfalcon/ScratchABit
53 If you cloned code without `--recursive`, run `git submodule update --init`
54 in the ScratchABit directory.
56 ScratchABit now ships with [Capstone Engine](http://www.capstone-engine.org/)
57 based CPU plugin(s), which allow access to a number of CPU architectures.
58 To use it, recent Python bindings module for Capstone should be installed
59 (in the preference to packages shipped by OS distributions, which are often
60 outdated). The easiest way to install it is into the Python user packages
61 directory:
63 pip3 install --no-cache-dir --user capstone
65 An alternative is to install it to a Python
66 [virtual environment](https://docs.python.org/3/library/venv.html) within
67 the ScratchABit directory:
69 python3 -m venv .venv
70 source .venv/bin/activate
71 pip3 install --no-cache-dir capstone
73 Whenever you open a new terminal session to work with ScratchABit,
74 run `source .venv/bin/activate` command again to activate the virtual
75 environment.
77 If nothing of the above works, you can try to install the capstone
78 package system-wide (not recommended):
80 sudo pip3 install --system capstone
83 Quick start
84 -----------
86 If you want to disassemble a file in self-describing executable format
87 (like ELF), just pass it as an argument to `ScratchABit.py`. The repository
88 includes a number of `example-*.elf` files for various architectures for
89 a quick start. For example, to try x86 32bit version:
91 python3 ScratchABit.py example-x86_32.elf
93 Alternatively, if you want to disassemble a raw binary file, you need
94 to create a .def (definition) file, to specify what memory areas are
95 defined for the code, at which address to load binary file, etc. (Note:
96 a .def file may be useful for .elf and similar files too.) The repository
97 includes a simple x86_64 raw binary code, and the corresponding
98 [example-x86_64.def](example-x86_64.def) file (look inside for
99 description of available options):
101 python3 ScratchABit.py example-x86_64.def
103 Press F9 to access menus (mouse works too in XTerm-compatible terminals).
104 Press F1 to get help about key bindings (most actions are also accessible
105 via menu). The workflow of ScratchABit is similar to other interactive
106 dissamblers (some previous experience or background reading may be helpful).
108 Using Plugins
109 -------------
111 IDAPython processor plugins can be loaded from anywhere on the Python
112 module path. Alternatively, you can symlink/copy the plugin `.py` file(s)
113 into the [`plugins/cpu/`](plugins/cpu/) subdirectory.
115 After the plugin is made available, create a new definition file based
116 on [`example-x86_64.def`](example-x86_64.def#L4) that sets the plugin module
117 name (without `.py` extenstion) in the `cpu xxx` line.
119 For a very simple example that uses an external plugin, see this
120 [esp8266.def file](https://gist.github.com/projectgus/f898d5798e3e44240796)
121 that works with the xtensa.py plugin from the
122 [ida-xtensa2 repository](https://github.com/pfalcon/ida-xtensa2).
124 TODO/Things to decide
125 ---------------------
127 * ~~Currently uses multiple files for "database", each storing particular
128 type of information. Switch to a single YAML file instead?~~
129 * ~~Add color (low priority, (unbloated!) patches welcome).~~
130 * ~~Few important UI commands to implement yet for comfortable work.~~ (
131 All the most important commands should be there, other functionality is
132 expected to be implemented using plugins).
133 * ~~Offer to save DB on quit if modified.~~
134 * Git integration for DB saving.
135 * ~~Improve robustness (add exception handler at the main loop level, don't
136 abort the application, show to user/log and continue).~~
137 * Try to deal with code flow inconsistencies (e.g. within an instruction -
138 low priority for intended usage) and data access inconsistencies (e.g.
139 accessing individual bytes of previosly detected word - higher priority).
140 (Improved in 1.4.)
141 * See how to support other types of IDAPython plugins besides just processor
142 modules.
143 * Parse and use debugging information (e.g. DWARF) present in ELF (etc.)
144 files.
147 FAQ
148 ---
150 > Q: What processors/architectures are supported?
152 A: ScratchABit doesn't support any processor architectures on its own,
153 it is fully retargettable using IDAPython API plugins. Many plugins are
154 available, writing a new plugin is easy. To let users test-drive
155 ScratchABit, a simple x86 processor plugin is included in the
156 distribution, using [Pymsasid](https://github.com/pfalcon/pymsasid3)
157 disassembler under the hood.
159 From version 2.0, [Capstone](http://www.capstone-engine.org/) plugin
160 is also included, allowing access to a number of architectures,
161 including x86, ARM, MIPS, PowerPC, SPARC, etc. (architecture support
162 is enabled gradually based on user testing).
164 You can read about the plugins shipped together with ScratchABit in
165 the [README for `plugins/cpu/` dir](plugins/cpu/).
167 > Q: Debugger?
169 A: ScratchABit is dedicated to static analysis and easy support for
170 new CPU architectures (just code up an new CPU plugin in Python - you
171 can get initial results in few hours). Dynamic analysis wasn't conceived
172 to be a core feature and there're no immediate plans to implement it.
173 Patches are welcome though.
175 > Q: Decompiler?
177 A: There is a related project, called
178 [ScratchABlock](https://github.com/pfalcon/ScratchABlock) for deep
179 program analysis, transformation and decompilation. It's expected
180 that as ScratchABlock matures, some of its functionality will be
181 available within ScratchABit (perhaps via plugins).
183 > Q: I'm not on Linux, how can I run ScratchABit?
185 A: Install Linux in an emulator/VM on your system and rejoice.
187 > Q: Mandatory screenshot?
189 A: Sure:
191 