FIXME: This file is not updated to ERESI 0.8 ! TO DO ASAP

                -------------------
                ELFSH 0.65rc2-linux
                -------------------

Hello dear ELFsh & E2dbg user,

Try to read this README, its a precious information ressource for the ELF shell project .

For impatient people, this is a short list of provided features :

. Analysis on nearly all types of sections
. Cool disasm/resolving engine with libelfsh and libasm
. Raw read/write capability into ELF32 AND ELF64 objects
. Modify ELF header, PHT, SHT, GOT, CTORS, DTORS, .dynamic, PAX bits
. Modify symbol table, dynamic symbol table and relocation tables
. Remove or reconstruct SHT
. Real interactive and scripting modes
. Many kind of section injection [even working in non-exec environments]
. Control flow graphs with graphviz output (i386) : see modflow
. ELFsh Module support and ELFsh internal API
. Quiet output for tiny screens and shellcript friendship
. Experimental ET_EXEC relocation and remapping feature (INTEL)
. Full ET_REL injection into ET_EXEC (INTEL / SPARC / ALPHA)
. PLT infection (INTEL, SPARC, ALPHA, MIPS)
. ALTPLT technique (INTEL, SPARC, ALPHA)

Major features of 0.65 are :

. 64 bits support
. A better scripting language with variables, conditions, and loops
. Support of ALPHA, MIPS, and SPARC64 architecture
. The Embedded ELF Debugging for Linux / IA32
. The DUMP protocol for connections between elfsh nodes
. The very first source release of libasm
. The EXTPLT technique for the X86 architecture
. The ALTGOT technique for the MIPS architecture
. The CFLOW technique for function redirection on IA32 and MIPS
. EXTSTATIC technique for extending static executables  

The major features of the 0.65 releases are available both for static injections and memory injection, using the Embedded ELF Debugger (e2dbg) for now on the Linux / IA32 environment.

We succesfully tested the debugger on Solaris x86 but we are still in the testing phase for it. BSD port is coming as well so stay tuned. If you are running BSD or Solaris and want to test elfsh, then make sure to look at elfsh 0.51rc3 that include a lot of the previously mentionned static features.

[0] Introduction [1] Communicate with ELFsh [2] Libelfsh and BFD [3] Portability [4] Changes [5] Module interface [6] Bugs and WIP [7] Contact

[0] Introduction

$ elfsh

     The ELF shell 0.65rc2 (32 bits built) .::. 

     .::. This software is under the General Public License V.2 
     .::. Please visit http://www.gnu.org 

(elfsh-0.65rc2)

[1] ELFsh syntax

You can choose to use ELFsh in interactive mode, script mode, or command line.

$ elfsh

     The ELF shell 0.65rc2 (32 bits built) .::.

     .::. This software is under the General Public License V.2
     .::. Please visit http://www.gnu.org

(elfsh-0.65rc2) help

             The ELF shell 0.65rc2 (compiled for 32 bits objects) 

Configuration commands .::. help, info, cat, sdir, lscripts, profile, quit, exit load, unload, switch, list, workspace ELFsh modules commands .::. modload, modunload, modhelp Ondisk/Memory ELF commands .::. elf, interp, pht, got, sht, rel, notes, dyn, dynsym findrel, ctors, disasm, hexa, set, get, write, print add, sub, mul, div, mod, cmp, reladd, redir Debugger commands .::. break, delete, continue, dumpregs, stack, dbgstack backtrace, linkmap, step ELF objects flags .::. fixup, shtrm, sstrip Ondisk only ELF commands .::. flush, save, sym, stab, append, extend, insert, remove Network commands .::. net, netlist, netkill, connect, disconnect, peerslist, rcmd

Available prefixes .::. all, sort, quiet, verb Available Script jumps .::. jmp, je, jne, jg, jl, jge, jle Available modules .::. modtest, modremap, modflow

Type 'help command' for specific information

(elfsh-0.65rc2)

Since ELFsh support his own module format, you can inject code into the VM very easily, or choose to improve libelfsh, if the needed modifications are pure ELF manipulation.

[*] D and X commands parameters syntax

• Available formats : regx, regx:rva, regx:rva%size, regx%size

• regx : Regular expression (mandatory)

• rva : Byte offset from the beginning (optional)

• size : Bytes number limit (optional)

  [*] Object access path format

• ELF header : filename.hdr.field

• got/ctors/dtors tables : filename.table[index]

• pht/symtab/dynsym/dynamic/sht/sections : filename.table[index].field

• Relocation tables : filename.rel[indextable][indexent].field

• Section raw data : filename.section[index:offset%elemsize].raw

  [*] Section raw data designation format

• Available constructions : index, index:offset, index:offset%elemsize

• index : The section's index

• offset : if specified, offset from the beginning of the section

• elemsize : if specified, offset = offset * elemsize

  The size of the data to be written is automatically determined as :

  • The lenght of the string for object type ELFSH_OBJSTR
  • The lenght until the end of the section for object type ELFSH_OBJRAW
  • sizeof(long) for object type ELFSH_OBJINT

  [*] Table index format

  GOT, CTORS, DTORS, SYMTAB, DYNSYM, SHT, Sections, and Relocation tables can be indexed by their exact name instead of an index number. The choice is left to the users.

  [*] Fields list

• hdr [ magic class type machine version entry phoff shoff flags ehsize phentsize shentsize phnum shnum shstrndx pax_pageexec pax_emultramp pax_mprotect pax_randmmap pax_randexec pax_segmexec ]

• sht [ type offset addr size link info align entsize a w x s m l o ]

• pht [ type offset paddr vaddr filesz memsz flags align ]

• symtab/dynsym [ name value size bind type other ]

• dynamic [ val tag ]

• section [ name raw ]

• rel [ type sym offset ]

  [2] LIBELFSH AND BFD

  ELFsh mechanisms are different from those of the GNU BFD project since libelfsh is reverse engineering oriented, where BFD is binary translation oriented.

  [3] PORTABILITY

  The major features of the 0.65 releases are available both for ondisk injections and memory injection, using the Embedded ELF Debugger (e2dbg) for now on the Linux / IA32 environment.

  We succesfully tested the debugger on Solaris x86 but we are still in the testing phase for it. BSD port is coming as well so stay tuned. If you are running BSD or Solaris and want to test elfsh, then make sure to look at elfsh 0.51rc3 that include a lot of the previously mentionned static features.

  [4] MAJOR CHANGES

  This version is a MAJOR update. Look at doc/Changelog for a complete list of changes. The internal descriptor of ELF objects has been complexified but clarified using an internal hierarchy, and everything is indexed using hash tables. We really care about the modularity of our programs so a lot of general purpose macros make the life easy in elfsh development. See vm/tables.c for an example of such interfaces.

  This package is now composed of :

  elfsh       .::. The scripting language interpreter
  e2dbg       .::. The embedded ELF debugger
  libdump     .::. ELFsh Distributed Update Management Protocol implementation
  libasm      .::. Disassembly and analysis of IA32 opcodes
  libelfsh    .::. The ELF manipulation library
  testsuite   .::. Example programs using libelfsh
  doc     .::. Documentation and information
  modules     .::. ELFsh provided modules (see modtest.c for basic example)

  • ELFsh :

  • We have interactive mode, scripting mode, command line mode. The scripting language now support lazy type variables like in Perl. See examples of scripts in testsuite/testscripts/ for example on the language syntax.

  • We use readline (version 5). Find it on ftp://ftp.gnu.org/gnu/readline/

  • Check http://elfsh.devhell.org/logs/ for detailed log and script samples results working with this version of ELFsh.

  • E2dbg :

  • The embedded ELF debugger is the very first UNIX userland debugger that does not use ptrace. It runs in the same process as the debuggee process thus have much more better performance. The debugger is also fully compatible with the PaX hardening Linux kernel patch that you can find on pax.grsecurity.net, at the exception of the MPROTECT option, for which we now know a solution but which is not available in this version of the project.

  • Most ondisk commands works in the debugger. The 'mode' command let you select between the inspection and change of the memory and the ondisk version of the ELF program. ET_REL injection and function redirection is known to work as well in memory.

  • E2dbg is a real debugger. It has the important debugger features, such as breakpoints, backtrace, step-by-step analysis, disassembly in memory. E2dbg also provides a display command integrated in the scripting language of ELFsh, so you can execute on step or breakpoint more powerful things than you could do with gdb.

  • Libelfsh :

  • The library now support both 32 and 64 bits files with a single code. It means that you have to compile 2 versions (one for 32bits, one for 64bits) if you want to manipulate the 2 different formats at the same time. There is no compatibility between these 2 built for now.

  • We implemented a self-profiler for the whole project. Using the 'profile' command of elfsh you can control its behavior. It is very useful for understanding more about the internal mechanisms of the code. The self-profiler includes a cheap memory system for function call that makes it capable of a very rudimentary pattern matching, which avoid too big traces.

  • We kept our modularity by our hook system that allow for plugging new supports for other architectures and OS in the future. Please do contribute anything you can ! See libelfsh/hooks.c for more information.

  • Libasm :

  This is a very first source code release of libasm. It now supports only the IA32 architecture, but SPARC and MIPS supports are in the way. Libasm is used at various places in elfsh, particulary useful for guessing the instructions length or plugging symbol resolution callbacks on code fetching. The source is work in progress.

  • Libdump :

  This is the very first release of libdump in the project. DUMP is a protocol that we implemented in peer-to-peer style for communicating between elfsh and e2dbg nodes. You can connect for starting a remote debugging session or communicate widely over the network between nodes. Some of the network commands of ELFsh rely on it.

  • Modules :

  • modtest is a simple test module for those interrested in writing elfsh or e2dbg modules.

  • modremap is an old test written by spacewalker and adapted inside elfsh by the ELFsh crew for trying to remap ET_EXEC ELF binaries whoose relocation tables are stripped. It is known to work on small binaries from /bin but wont work on bigger binaries.

  • modflow now provides basic control flow graph with a good looking output using graphviz (by ATT labs.) This feature is known to work for small binaries, but the graphing tool wont follow libasm on bigger binaries.

  [5] Module support

  ELFsh support modules, they are very easy to code, and you can load it at runtime using the modload command (see modunload for unloading) .

  A basic module would be : modules/modtest.c

  The module API:

  • void elfsh_init() Mandatory
  • void elfsh_fini() Optional

  From the modules, you can use the internal ELFsh API :

  • All vm_* API (See vm/include/elfsh.h)

  [6] BUGS AND WIP

  • The SHT reconstruction engine is rewritten at the moment to deal with various special case of the 0.43b insertion based algorithm (use ELFsh 0.43b for this feature, waiting for the new implementation in this serie).

  • Changing sh_size and then display the section content may faults if data it not appended (reported by emper0r)

  • ET_REL injection on MIPS is work in progress.

  • The debugger is for now only garanted to work on Linux / IA32. Other OS are beeing tested (BSD, Solaris, HPUX) and other architectures are studied. See the doc/TODO file for a more complete view of the future plans.

  [7] CONTACT

  If you have any requests (new features, bugtracking, comments, or just to say hello) you can mail us :

  elfsh@devhell.org

  If you're interrested in the subject, visit the project page :

  http://elfsh.devhell.org

  Share & Enjoy !

                          The ELF shell crew