ERESI(1) The ERESI Reverse Engineering Software Interface

SYNOPSIS

elfsh [OPTIONS]

etrace [OPTIONS]

e2dbg programtodebug

kernsh

DESCRIPTION

The ERESI Reverse Engineering Software Interface is a unified reverse engineering framework for UNIX operating systems based on the Executable & Linking Format (ELF) such as Linux, BSD, Solaris, IRIX, and BeOS. It has a command line interface that make it useful remotely, and can generate graph images from code analysis on demand. It has a real dedicated reverse engineering language that makes it scriptable and adaptable to the precise needs of the users. ERESI contains more than 10 innovative and exclusive features that turns it into an environment of choice for the instrumentation, analysis, debugging, tracing, hooking, or simply integrity checking and events logging of binary programs. ERESI is composed of ELFsh (the ELF shell), E2dbg (The Embedded ELF debugger) and Etrace (The Embedded ELF tracer). This documentation applies on all of the components.

OPTIONS

The ELF shell (part of ERESI) can take the following command line parameters:

-f
input file
-w
output file

Note that the command line is slightly different for E2dbg and Etrace which do NOT take those parameters.

COMMANDS

E2dbg and Etrace have to be executed using a unique command line parameter (the program file to be debugged or traced). The following primitives can be used interactively in E2dbg, Etrace, and ELFsh, but also on command line when preceded by a - (ELFsh only) at the UNIX shell command prompt.

General purpose commands

cat edit exec exit help info list load lscripts nocolor profile quit sdir setcolor switch unload workspace

cat
print the file argument

edit
Edit the file given in parameter

exec
Fork and execute parameter command (with args)

help
Print the help screen

info
Print the extra details help screen

list
List the loaded files and their ID

load filename
Load input file filename

lscripts
List macro commands

nocolor
Toggle color status

profile (enable | disable) (traces | warns | alloc | debug | all)

Change the ELFsh profiling behavior. Traces profiling print all the internal function calls done by the framework. Warning profiling prints all the (fatal and non-fatal) warnings reported by the internal API : it very useful for tracking bugs and it should be used when reporting issues on the bugtracking system. Allocation and debug profiling are experimental and should only be used by experienced ERESI developers.

quit
Quit the shell without saving

sdir
Change the script directory. This allows to make precise the location of complete ERESI library and bind script files on command names in the shell.

setcolor Associates data types to colors

setcolor type [bg,fg] color

setcolor type [underline,bold] (1=on,0=off)

Available types : address, number, string, endstring, warnstring typestring, fieldstring, instr, pspecial, psname pspecial, pversion, prelease, pedition

Available colors : black red green yellow blue magenta cyan white

switch (filename | fileID)
Change the current file to work on to filename or fileID

unload (filename | fileID)
Unload file filename or fileID without saving

workspace [wname]
When executed without parameter, this command list existing workspaces. When given an existing workspace name, this command switch to that workspace. If given a non-existing workspace name, this command creates a new workspace and switch to it.

tables [regex]
If given without parameter, list all the existing hash tables in the ERESI framework. If given with a parameter, print the content of hash tables whoose name match the regular expression.

vectors [vname[:idx1:...:idxN]] [symbol|addr]
If given without parameter, list all the existing vectors in the ERESI framework. If given with a parameter, print the content of this vector. If given one long parameter, print the content of a given vector entry. If given 2 parameters, modify the vector entry with a user provided address or resolved symbol address.

========================================================================

Ondisk/Memory ELF commands

Those commands works in all components of the ERESI framework (ELFsh, E2dbg, and Etrace).

add cmp ctors disasm div dtors dyn dynsym elf findrel get got hexa interp mod mul notes pht print redir rel reladd set sht sub write test

add
Add the 2 parameters and put the result in variable $_

cmp
Compare 2 parameters. The difference is put in variable $_

ct ctors [Regex]
Print .ctors section entries matching Regex

D disasm [Regex]
Disassemble matching binary objects in current file

disasm parameter

Allowed parameter format : regx regx:rva regx:rva%size regx%size
 - regx : Regular expression (mandatory)
 - rva  : Byte offset from the beginning (optional)
 - size : Bytes number limit (optional)

div
Divide first param by second one and put the result in the first one

dt dtors [Regex]
Print .dtors section entries matching Regex

dyn
Print the ELF dynamic section

ds dynsym [Regex]
Print dynamic symtab (.dynsym) entries matching Regex

e elf
Print the ELF header

findrel
Try to find back stripped relocation information. Note: retreiving this information in a very exact manner is very difficult, this command only gives you an approximative list of pointer accesses in the binary code. It does not deal either with constructed addresses using multiple arithmetic and logic instructions, or with false positives that appear to be valid mapped pointers but are not in reality (ex: Hashed data)

get
Print parameter object value. The parameter can be a constant or defined value, a variable or any ELF object that is part of any file loaded in the shell, provided you give its id at the beginning of the object path. See info command for the exact grammar of object paths.

g got [Regex]
Print the entries of the Global Offset Table (GOT) matching Regex. The regex can apply on either an address, an entry index, or a resolved symbol from the entry address (or contained address).

X hexa [Regex]
Dump matching binary objects in current file. This has the same syntax than D/disasm command.

X parameter

ParamFormat : regx regx:rva regx:rva%size regx%size
 - regx : Regular expression (mandatory)
 - rva  : Byte offset from the beginning (optional)
 - size : Bytes number limit (optional)

interp
Print ELF interpreter path standing in .interp section.

mod
Modulo operation between 2 parameters. The result is put in the destination variable.

mul
Multiply the 2 parameters. The result is put in the destination variable.

n notes [Regex]
Print the Notes sections entries matching Regex

p pht
Print the Program Header Table (PHT)

print [ObjectPath1 ObjectPath2 ... ObjectPathN]
Print the values of objects ObjectPath1 ObjectPath2 ... ObjectPathN. Objects can be constant strings, ELF objects, variables, defined values, and so on.

redir func (func2 | addr)
Redirect calls to function func to func2 or address addr. If the original function has a PLT entry, the ALTPLT technique is used to perform the redirection. If the function is internal (or if we are in a static binary) the CFLOW technique is used to perform the redirection. ALTPLT technique is available on INTEL, SPARC, MIPS, and ALPHA architectures. CFLOW technique is currently not available on the SPARC architecture. The hook (second) function is usually an injected C code provided by the user and injected using the reladd primitive. In case the provided hook function calls other function which are not in the host binary, ERESI will use the EXTPLT technique (or EXTSTATIC technique on static binaries) to relink the host binary in order to add new relocation entries, dynamic symbols with their names, symbol versions, extra GOT and PLT entries (using additionally the ALTGOT technique on RISC architectures), and will fixup the .dynamic section to reflect those changes on the section list.

r rel [Regex]
Print the relocation entries matching Regex

reladd (DestFilePath | DestfileID) (RelocFilePath | RelocFileID)
Inject the ELF relocatable object RelocFileID into the ELF executable object DestFileID. This command is used for injecting plain C compiled code linked into a .o file into a host ET_EXEC (executable) or ET_DYN (shared library) ELF file.

set DestObjectPath SourceObjectPath
Set the value of object DestObjectPath to SourceObjectPath. The $_ variable gets modified depending on the result. See the info command for a list of all accessible objects using the set command.

s sht [Regex]
Print the sections in the Section Header Table (SHT) matching Regex

sub
Substract 2nd parameter to the first one. The $_ variable is modified depending on the result.

write DestObjectPath SourceObjectPath
Copy data from SourceObjectPath to DestObjectPath. The destination object has to be of type RAW (the data field of a section) and the source object has to be of type RAW or STRING. See the info command for more detail about this.

========================================================================

Debugger commands

backtrace break continue dbgstack delete dumpregs linkmap stack step display threads itrace

backtrace
Print backtrace (needs frame pointer).

break (BPsymbol | 0xaddress)
Put a breakpoint on symbol or address. Print all breakpoints if given without parameter.

step

Enable or disable stepping of debuggee program. Use continue for singlestepping.

continue

Continue executing debuggee program after breakpoint or singlestep.

delete (BPID | BPsymbol | 0xaddress)

Delete breakpoint by symbol, address, or ID.

dbgstack WordsNBR

Dump N words (N given as first parameter) from the debugger stack. We can do that because the debugger is embedded into the debuggee process.

stack WordsNBR

Dump WordsNBR words on debuggee stack.

dumpregs

Dump registers of debuggee at breakpoint or step.

linkmap

Print Linkmap list for the debuggee process.

display BPid Full_ERESI_command
Set a command to be executed on event. The first parameter must be the breakpoint id that correspond to the event. The ERESI command can be any valid ERESI command, including the sourcing of an ERESI script.

threads [ThreadID]
If called without parameter, this command list existing threads in the debuggee process. If called with a thread ID parameter, the current thread is switched to the thread indicated by the ID.

itrace
Singlestep the debuggee program until next breakpoint event, printing all executed instructions until it stops.

========================================================================

ELFsh modules commands

modhelp modload modunload

modhelp ModuleFilePath
Print help for a loaded ERESI module.

modload ModuleFilePath
Load an ERESI module. The path has to be absolute or relative to the registered module path.

modunload ModuleFilePath
Unload an ERESI module. The path has to be absolute or relative to the registered module path.

========================================================================

ELF objects flags

fixup shtrm sstrip

fixup
Mark BSS section to be included in disk file. The BSS gets immediately fixed in the ELFsh internal descriptor of the object.

shtrm
Mark Section Header Table as removed. The SHT will be removed only when the file is saved.

sstrip
Mark the Section Header Table (SHT) and Symbol Table (.symtab) as stripped. They will be removed only when the file is saved.

========================================================================

Ondisk only ELF commands

Those commands only works in ELFsh, or in E2dbg when switched to the static mode using the mode command.

append extend flush insert remove save stab sym

append SectionName SourceObjectPath
Append the data of object SourceObjectPath to section SectionName

extend SectionName length
Extend section SectionName with length zero bytes

flush
Flush all injected .o files from current file.

insert
Inject new object (section, symbol, or program header) in current working file.

insert sect name code|data|unmap [sz] [align]
       sym   name value           [sz]
       phdr  type vaddr           [sz]

remove
Remove ELF object (section, symbol, or program header) from current working file

remove sect name
       sym  name
       phdr index

save filename
Dump current selected file to output file filename. This command writes a file on disk.

debug
Print unified debug format information for the current file.

st sym [Regex]
Print the symtab (.symtab) entries matching Regex.

========================================================================

Kernsh modules commands

Those commands only works in Kernsh.

openmem
Open kernel memory and static kernel

closemem
Close kernel memory and static kernel

sct
Display the syscall table

idt
Display the interrupt descriptor table

gdt
Display the global descriptor table

alloc
Alloc contiguous kernel memory

free
Free contiguous kernel memory

alloc_nc
Alloc non contiguous kernel memory

free_nc
Free non contiguous kernel memory

kmodule
Handle kernel module

kmodule -l module : load a lkm

kmodule -u module : unload a lkm

kmodule -r module1 module2 moduleout : link module with another

kmodule -i module original_name evil_name : change lkm init (original_name) with another function (evil_name)

ksym
Get an address of a kernel symbol

kmd5 sa output | sa:rva output | sa%rva%size output | sa%size output
Make a md5sum.

sa : Symbol or addr

rva : Byte offset form the beginning (optional)

size : Bytes number limit (optional) (if size is 0 or not put, we search the end of the function)

output : file output (optional)

kcmd5 format | file
Check a md5.

format : addr:mode:size:off:md5

file : filename

========================================================================

Type related primitives

Those primitives allow to define and habitate types in the ERESI meta-language:

type [regex]

Print list of types (only those matching the regular expression if given in parameter).

type name = field1:type1 ... fieldN:typeN

Define a new type in the ERESI meta-language. Predefined types include byte, short, int, caddr, daddr, long, hash, vector, string, and raw.

typedef tname tname2

Copy and rename a type. Any modification on one of the types will not affect the other.

inform type [name | address]

Make type name habitated by the variable standing at address name. If called with a single type name parameter, the command list all variables that habitate this type. If given 2 parameters, the name is interpreted as a symbol pointing on a variable. Its address is resolved and the type is informed about this variable. If only an address is given, its symbol is looked up and the variable corresponding to the symbol is informed. If no symbol corresponds to this address, a new one is created that points on the address, and the newly symbolic variable is informed.

uninform type [name]

Uninform a given variable from a type. If no variable name is given, all variables previously informed are removed from the type habitation.

========================================================================

Network commands

connect disconnect net netkill netlist peerslist rcmd

connect
Add a DUMP connection to given host

disconnect
Kill the DUMP connection from IP

net
Activate networking capabilities

netkill
Kill a network client by IP

netlist
List connected network clients

peerslist
List connected DUMP peers

rcmd
Execute a command on a remote machine

========================================================================

Available prefixes

alert all quiet sort verb

alert
Alert prefix : change alert regular expression

a all regex
Set a global regular expression. All commands which take a regular expression as a parameter will default to use this global regular expression.

quiet
Toggle quiet flag (do not print executed commands)

sort
Sorting prefix (use a -addr- or s -size-)

verb
Toggle verbose flag (undo the quiet flag)

========================================================================

Available Script jumps

A certain number of jumps construct are available:

je jg jge jl jle jmp jne

je
Jump on label if equal (use last cmp result)

jg
Jump on label if greater (use last cmp result)

jge
Jump on label if greater or equal (use last cmp result)

jl
Jump on label if lower (use last cmp result)

jle
Jump on label if lower or equal (use last cmp result)

jmp
Unconditional jump to script label

jne
Jump on label if nont equal (use last cmp result)

You might also consider using a foreach construct, which is not described in this manual page.

========================================================================

Available modules

modflow modremap modtest

modflow
Modflow is an ELFsh module designed to perform control flow analysis on ELF binaries for detailed examples and usage see README in ELFsh/modules/modflow

modremap
Modflow is an ELFsh module designed to perform remapping sections in Elf binaries see ELFsh/modules/modremap for further details

modtest
Modtest is a ElFsh module designed to show the usage of adding new commands to ELFsh see ELFsh/modules/modtest for further details

========================================================================

OBJECT PATH FORMAT

This section explains how to access different objects in an ELF file. For most commands the object can also be a decimal or hexadecimal numbers. In this case the ObjectPath is the number.

ELF Header
filename.hdrfield

ELF header fields are :

magic
Magic number

class
File class

type
Object file type

machine
Architecture

version
Object file version

entry
Entry point virtual address

phoff
Program header table file offset

shoff
Section header table file offset

flags
Processor-specific Flags

ehsize
Size of the ELF header in bytes

phentsize
Size of the program headers

shentsize
Size of the section headers

phnum
Number of program headers

shnum
Number of section headers

shstrndx
Section header string table index

pax_pageexec
PAX use paging based non-executable pages

pax_emultramp
PAX emulate trampolines

pax_mprotect
PAX restrict mmap

pax_randmmap
PAX randomize mmap

pax_randexec
PAX randomly map executable address

pax_segmexec
PAX use segmentation based non-executable pages

got/ctors/dtors tables
(filename | fileID).(got|ctors|dtors)[index]

In this command, the index can also be a symbol name that corresponds to the requested GOT, CTORS, OR DTORS entry.

Program segment header table
(filename | fileID).pht[index].fi eld

Program segment header table entry fields are :

type
Segment type

offset
Segment file offset

paddr
Segment physical address

vaddr
Segment virtual address

filesz
Segment size in file

memsz
Segment size in memory

flags
Segment flags

align
Segment alignment

Symbol/Dynamic symbol tables
(filename | fileID).(symtab|dynsym)[index].fi eld

Symbol/Dynamic symbol table entry fields are :

name
Symbol name

value
Symbol value

size
Symbol size

bind
Symbol binding

type
Symbol type

other
Symbol visibility

Dynamic section
(filename | fileID).dynamic[index].fi eld

The .dynamic section entry fields are :

val
Integer or address value

tag
Dynamic entry type

Section header table (filename | fileID).sht[index].fi eld

The index can be the name of the section. Section Header Table entries fields are :

type
Section type

offset
Section Offset in ELF file

addr
Section Address

size
Section Size in bytes

link
Link to another section

info
Additional Info

align
Section Alignment

entsize
Entry size if section holds table

flags

a
Section occupies memory during execution

w
Section is Writeable

x
Section is Executable

s
Contains nul-terminated strings

m
Section might be merged

l
Preserve order after combining

o
OS specific

Relocation table
(filename | fileID).rel[indextable][indexentry].fi eld

Relocation entry fields are :

type
Relocation Type

sym
Relocation symbol index

offset
Address

Additional sections information (filename | fileID).section[sectionindex].fi eld

The section object is not a real object of the binary, but a kind of virtual one. It holds all the information about a section that do not stand in the sectoin header table entries. Section fields are :

name
Section name

raw
Section Raw data

To access use following path format :

filename.section[index[:offset[%elemsize]]].raw

AUTHOR

ERESI was created by Julien Vanegue and developed by the ERESI team

                        <team at eresi-project dot antispam org>

The complete list of ERESI contributors can be found on the website:

                        http://www.eresi-project.org

This manual page was created by Julien Vanegue, from previous work on the ELFsh man page by Peter De Schrijver for the Debian GNU/Linux system. Additional improvements were made by stingduk for version 0.7.