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