
not up2date.
					------------
					ELFSH 0.51b3
					------------


Hello dear ELFsh 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 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]
	. 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)
	. PLT infection (INTEL and SPARC)
	. ALTPLT technique (INTEL and SPARC)
	. Control flow graphs with graphviz output (i386)

 [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 is an interactive and scriptable ELF machine to play with executable files, 
     shared libraries and relocatable ELF32 objects. It is useful for daily binary
     manipulations such as on-the-fly patching, code analysis, or embedded code injection
     in research fields such as reverse engineering, security auditing and intrusion
     detection. ELFsh is composed of libelfsh and libasm, so that the API is really
     usefull for opensource projects.

bash-2.05$ elfsh

         Welcome to The ELF shell 0.51b3 .::. 

         .::. This software is under the General Public License 
         .::. Please visit http://www.gnu.org to know about Free Software 

[ELFsh-0.51b3]$ 




 [1] ELFsh syntax



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


 Interactive only commands :

 load          filepath       .::. Load input file
 save          outputfile     .::. Dump output file
 unload        obj{name,id}   .::. Unload object without saving
 switch        obj{name,id}   .::. Change the current working object
 modload       modpath        .::. Load an ELFsh module
 modunload     mod{name,id}   .::. Unload an ELFsh module
 list                         .::. List loaded objects

 Command line only :

 -f 	: Specify input file
 -w 	: Specify output file


 Other commands (add '-' if called from command line) :


[ELFsh-0.51b3]$ help


                 The ELF shell 0.51b3

 info                         .::. Extra details help screen info
 load          filepath       .::. Load input file
 save          outputfile     .::. Dump output file
 unload        obj{name,id}   .::. Unload object without saving
 switch        obj{name,id}   .::. Change the current working object
 modload       modpath        .::. Load an ELFsh module
 modunload     mod{name,id}   .::. Unload an ELFsh module
 list                         .::. List loaded objects
 help                         .::. Print this screen
 fixup                        .::. Insert BSS section in corefile
 findrel                      .::. Dump absolute references list
 shtrm                        .::. Mark the SHT as removed
 quit/exit                    .::. Quit the shell without saving
 elf    [e]                   .::. Print ELF header
 interp [i]                   .::. Print .interp section
 pht    [p]    regx           .::. Print Program Header Table (PHT)
 got    [g]    regx           .::. Print Global Offset Table (GOT)
 sht    [s]    regx           .::. Print Section Header Table (SHT)   
 rel    [r]    regx           .::. Print relocation tables entries    
 notes  [n]    regx           .::. Print Notes sections entries
 dyn    [d]    regx           .::. Print .dynamic section entries     
 dynsym [ds]   regx           .::. Print dynamic symbtab entries (.dynsym)   
 sym    [st]   regx           .::. Print symtab entries (.symtab)     
 stab   [sb]   regx           .::. Print raw stab entries (.stabs)    
 ctors  [ct]   regx           .::. Print .ctors section               
 dtors  [dt]   regx           .::. Print .dtors section               
 disasm [D]    regx:rva%size  .::. Disassembly the matching objects             
 hexa   [X]    regx:rva%size  .::. Dump in hexadecimal the matching objects
 reladd objdst objsrc         .::. Insert ET_REL into ET_EXEC
 OP     objdst objop          .::. Arithmetics on objects (add/sub/mul/div/mod)
 set    objdst objsrc         .::. Modify object value (see info)
 get    objdst                .::. Print object value
 append sctnam objsrc         .::. Append data to section
 extend sctnam size           .::. Extend section (fill with 0x00)
 write  objdst objsrc         .::. Transfer data between objects                
 print  obj1 obj2 ... objN    .::. Print sequence of objects or constants
 redir  func   func2|addr     .::. Redirect a function (need .plt entry)               

 Available prefixes :
 all    [a]  regx             .::. Give a global weak regular expression
 sort   [sr] {a,s}            .::. Sort entries by address (a) or size (s)
 quiet/verb                   .::. Toggle the verbosity flag

 Available modules :
 modtest                      .::. Sample test module
 modremap                     .::. ET_EXEC immediate relocator
 modflow                      .::. Control flow blocks grapher

[ELFsh-0.51b3]$ 


 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 not very similar to BFD since libelfsh is reverse
 engineering oriented, where BFD is binary translation oriented . Moreover
 libelfsh is ELF specific and contains IA32 and SPARC architecture dependant
 code.


 [3] PORTABILITY

 
 It's a beta version (0.51b3) and still a development version . Some
 features are still in progress like stripping and SHT reconstruction.
 It is still a beta version but it has been tested on Linux/i386, 
 Linux/sparc, FreeBSD/i386, NetBSD/i386, and Solaris/sparc.


 [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 now everything is indexed using hash tables.

 This package is now composed of :

		elfsh		.::. The shell itself
		libelfsh	.::. The ELF manipulation lib
		libhash		.::. ELFsh hashing library
		testsuite	.::. Example programs using libelfsh
		doc		.::. Documentation and information
		modules		.::. ELFsh provided modules (see modtest.c for basic example)
 
 - ELFsh : 

	* We now have a real interactive mode and a real scripting mode, with module support
	and an object oriented architecture, with lazy typing like in perl. 

	* We use readline (ELFsh doesnt work with other version than libreadline 4.3), find
	it on ftp://ftp.gnu.org/gnu/readline/ and uncomment the readline option in 
	vm/Makefile

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

 - Libelfsh : 

 	* The block scanning code has been cleared to provide architecture independant
 	interface. 

	* All objects changed name (no more Elsh32_*, but elfsh*_t)

	* New objects : elfshobj_t, elfshsect_t, elfshrel_t, elfshblock_t

	* Libelfsh documentation is not yet updated to 0.5, find the libelfsh 0.43b
 	documentation in doc/libelfsh-ref.txt

 - Libasm :

	This is a new ressource used by ELFsh, designed for x86 binaries, 
	find it on http://devhell.org/projects/libasm/ and uncomment the libasm
	option lines in vm/Makefile.

 - Modules :

	* modflow now provides basic control flow graph with a good
	looking output using graphviz (by ATT labs.) This feature is not
	considered as stable and works only on i386. 


 [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 doc/elfsh-ref.txt)


 [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 the 0.5 serie).

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

 - BSD linking need to remove -ldl in vm/Makefile (still not get autoconf back ..)

 - Section pre-interp injection does not work with FreeBSD current dynamic linker, 
   ('Killed'). Nevertheless, ET_REL injection works on all OS, since section 
   injection is done in the allowed areas depending on the operating system. 

 - ALTPLT redirection on sparc/solaris is flushed if you call the original function
   (solaris does not use r_offset field and breaks TIS standard).


 [7] CONTACT

 Many features are still planed (look at the TODO file) . 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

 Enjoy ! ;)

							
								The ELF shell crew









