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