README.md

   1 ScratchABit
   2 ===========
   3
   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).
   9
  10 ScratchABit supports well-known in the community IDAPython API to write
  11 disassembly/extension modules.
  12
  13 ScratchABit is a work in progress, features are added on as needed basis,
  14 contributions are welcome.
  15
  16 ScratchABit is released under the terms of GNU General Public License v3
  17 (GPLv3).
  18
  19
  20 Requirements/manifesto
  21 ----------------------
  22
  23 1. Should not be written in an obfuscated language. These include languages
  24 which are too low-level, which allow to access non-initialized variables,
  25 which don't differentiate between variables and functions/procedures, which
  26 start array indexes from arbitrary numbers, etc., etc. ScratchABit is
  27 written in Python (modern version, Python3) for your pleasure and sanity.
  28
  29 2. User interface framework should allow user interaction of the needed
  30 level, not add dependencies, bloat, issues, and incompatibilities between
  31 framework's versions. ScratchABit currently uses simple full-screen text
  32 user interface, using ANSI/VT100 terminal escape sequences (yes, even
  33 curses library was deemed too bloat a dependency to force upon users).
  34
  35 3. Should leverage easy to use text formats to store "database", to
  36 facilitate easy reuse and tool writing, and storage in version control
  37 systems.
  38
  39
  40 Quick start
  41 -----------
  42
  43 To use ScratchABit, you need Python3 installed and VT100 (minimum) or
  44 XTerm (recommended) terminal or terminal emulator (any Unix system
  45 should be compliant, like Linux/BSD/etc., see FAQ below for more).
  46
  47 Clone the code using:
  48
  49     git clone --recursive https://github.com/pfalcon/ScratchABit
  50
  51 If you cloned code without `--recursive`, run `git submodule update --init`.
  52
  53 If you want to disassemble a file in self-describing executable format
  54 (like ELF), just pass it as an argument to `ScratchABit.py`. The repository
  55 includes `example-x86_32.elf` (x86 32bit) for a quick start:
  56
  57     python3 ScratchABit.py example-x86_32.elf
  58
  59 Alternatively, if you want to disassemble a raw binary file, you need
  60 to create a .def (definition) file, to specify what memory areas are
  61 defined for the code, at which address to load binary file, etc. (Note:
  62 a .def file may be useful for .elf and similar files too.) The repository
  63 includes a simple x86_64 raw binary code, and the corresponding
  64 [example-x86_64.def](example-x86_64.def) file (looks inside for
  65 description of available options):
  66
  67     python3 ScratchABit.py example-x86_64.def
  68
  69 Press F9 to access menus (mouse works too in XTerm-compatible terminals).
  70 Press F1 to get help about key bindings (most actions are also accessible
  71 via menu). The workflow of the ScratchABit is similar to other interactive
  72 dissamblers; some previous experience or background reading may be helpful).
  73
  74 Using Plugins
  75 -------------
  76
  77 IDAPython processor plugins can be loaded from anywhere on the Python
  78 module path. Alternatively, you can symlink the plugin `.py` file into
  79 the `plugins/cpu/` subdirectory.
  80
  81 After the plugin is made available, create a new definition file based
  82 on `example-x86_64.def` that sets the plugin module name in the `cpu xxx`
  83 line.
  84
  85 For a very simple example that uses an external plugin, see this
  86 [esp8266.def file](https://gist.github.com/projectgus/f898d5798e3e44240796)
  87 that works with the xtensa.py plugin from the
  88 [ida-xtensa2 repository](https://github.com/pfalcon/ida-xtensa2).
  89
  90 TODO/Things to decide
  91 ---------------------
  92
  93 * ~~Currently uses multiple files for "database", each storing particular
  94   type of information. Switch to a single YAML file instead?~~
  95 * ~~Add color (low priority, (unbloated!) patches welcome).~~
  96 * ~~Few important UI commands to implement yet for comfortable work.~~ (
  97   All the most important commands should be there, other functionality is
  98   expected to be implemented using plugins).
  99 * ~~Offer to save DB on quit if modified.~~
 100 * Git integration for DB saving.
 101 * ~~Improve robustness (add exception handler at the main loop level, don't
 102   abort the application, show to user/log and continue).~~
 103 * Try to deal with code flow inconsistencies (e.g. within an instruction -
 104   low priority for intended usage) and data access inconsistencies (e.g.
 105   accessing individual bytes of previosly detected word - higher priority).
 106   (Improved in 1.4.)
 107 * See how to support other types of IDAPython plugins besides just processor
 108   modules.
 109 * Parse and use debugging information (e.g. DWARF) present in ELF (etc.)
 110   files.
 111
 112
 113 FAQ
 114 ---
 115
 116 > Q: What processors/architectures are supported?
 117
 118 A: ScratchABit doesn't support any processor architectures on its own,
 119 it is fully retargettable using IDAPython API plugins. Many plugins are
 120 available, writing a new plugin is easy. To let users test-drive
 121 ScratchABit, a very simple (!) X86 processor plugin is included in the
 122 distribution, using Pymsasid disassembler under the hood.
 123
 124 > Q: Debugger?
 125
 126 A: ScratchABit is dedicated to static analysis and easy support for
 127 new CPU architectures (just code up an new CPU plugin in Python - you
 128 can get initial results in few hours). Dynamic analysis wasn't conceived
 129 to be a core feature and there're no immediate plans to implement it.
 130 Patches are welcome though.
 131
 132 > Q: Decompiler?
 133
 134 A: There is a related project, called
 135 [ScratchABlock](https://github.com/pfalcon/ScratchABlock) for deep
 136 program analysis, transformation and decompilation. It's expected
 137 that as ScratchABlock matures, some of its functionality will be
 138 available within ScratchABit (perhaps via plugins).
 139
 140 > Q: I'm not on Linux, how can I run ScratchABit?
 141
 142 A: Install Linux in an emulator/VM on your system and rejoice.
 143
 144 > Q: Mandatory screenshot?
 145
 146 A: Sure:
 147
 148 ![screenshot](https://raw.githubusercontent.com/pfalcon/ScratchABit/master/docs/scratchabit.png)