fenris(1)

NAME
fenris - program execution path analysis tool

SYNOPSIS
fenris [ -E PAR=VAL ] [ -u user ] [ -o file ] [ -L dbase ] [ -t nnn ] [-R n:n ] [ -P i:a:v ] [ -sdyiCSfFAmxpe ] program [ params... ]

DESCRIPTION
This manual page briefly documents the fenris utility command-line parameters. For more complete documentation about functionality, features, concepts, bug reporting, etc, please refer to /usr/doc/fenris/README or visit http://lcamtuf.coredump.cx/fenris/. This program and related components (such as ragnarok(1)) are intended to support human-driven security audits, algorithm and protocol analysis attempts and binary code reverse engineering.

COMMAND-LINE OPTIONS
Mandatory parameter is program name, eventually followed by program parameters. If, for some reason, program name has to start with '-', it should be preceded with '--' parameter. Before program name, you can place one or more optional parameters, such as: -o filename This options writes results to file instead of stderr. It is faster and recommended in all cases. -E PAR=VAL Puts PAR in the environment. This is especially useful if you want to trace a program with unusual LD_PRELOAD or other settings that would affect the functionality of 'fenris' itself if modified earlier. Multiple -E options are allowed. -u user Run as user. This option is available for root (see section 0x04, security issues), and will cause program to effectively run with uids, gids and supplementary groups of given user. -L dbase Load additional (supplementary) fingerprints database. Multiple -L options allowed. If filename does not contain slashes, fenris will look for it in directories described later in this section. -R a:b This option traces code from the moment when eip reaches point a to the moment when it reaches b. Incomplete range can be provided - for example, -R :0x12345678 will trace code from the beginning to eip 0x12345678, and -R 0x12345678: will start tracing at 0x12345678 and continue as long as possible. NOTE: think of it as trigger points, not a continous range. For example, if you use -R 0x12345678:, but eip 0x12345678 is never reached, even if 0x23456789 is being executed, trace will never start. -t nnn Main function is nnn rets from _do_global_ctors_aux. By default, this is set to 2, and does not have to be changed unless something is really wrong. You should use this option if you see that trace ends with '...return from main' almost immediately at the beginning (try increasing -t parameter) or somewhere in the middle or does not reach main at all (try decreasing). However, this should not happen, in general. The only case I'm aware of are HMM 3 binaries (patchlevel 1.3.1a, does not affect 1.3), they require -t 3 instead. -P ip:off:val This directive means: change a byte at address 'off' to 'val' when eip reaches 'ip'. If 'ip' is omitted or zero, this rule will be applied immediately to the freshly mapped binary (keep in mind that some memory regions mapped later may be not available at this moment). Read-only flag is generally overriden, and for files mapped into memory in read-only mode, a local copy of the modified page is spawned. All values passed to this parameter can be in decimal or in hex if preceeded with 0x, and multiple options are possible. Non-IP entries will be applied only once, at the beginning. All others will be applied every time a given IP is reached. There are some additional considerations to be aware of when used in conjunction with tracing across execve()s - see -e option description for details. -A Assume that all functions return some value, regardless of all other conditions. This will trigger some meaningless return values reported, but is useful if the binary is very optimized. -s This option disables automatic prolog detection. It is not recommended, as it makes ./fenris trace whole linking process and libc initialization. However, in rare cases when binary is compiled on odd, not supported system, this might be a solution. For long-term operations, however, it is recommended to contact the author providing his with this binary (or parts of it), so he'll be able to add support for this specific construction. -y Reports memory writes and reads immediately (without -y, memory access is reported per function on return). -C Inhibits tracing conditional expressions. This option is useful if output will be read by human, as it might decrease amount of reported information. -S Inhibits resolving library functions. This might effect in some speed improvement, but is generally not recommended without a good reason. -f Trace child processes after fork() or vfork(). Might be useful for tracing daemons and such (however it might cause some problems due to signal delivery semantics changes, see 0x07, known bugs) -d Do not describe function parameters. Reduces amount of generated output. -F Do not fingerprint functions. This option is effective for static binaries only, and will disable loading and displaying fingerprints. This is not really recommended - for stripped binaries, it makes your life more difficult, for binaries with symbols has almost no effect. However it might reduce memory usage and improve speed. -m Do not trace memory writes. This option reduces amount of generated input. -i This option disables indenting, reporting of pid and nesting level. It makes output non-structural, non-standard, but shorter. This will also break compatibility with ragnarok. -x This option causes fenris to ignore 'return from main' and to continue tracing, returning to nest level 0. Generally speaking, this is not recommended at any time. If you have problems with 'return from main' appearing too early in the trace, try re-adjusting -t parameter instead. If this do not help, apparently one or more of calling or return conventions used by traced application are not supported, and you shouldn't rely on results anyway. -p Prefix every message with eip. Some commands report eip, some not, this might be useful for debugging. This option is compatible with ragnarok. -e Trace new code loaded by execve(). This option might be convinient in some cases, but should be used with caution. Also, be warned that -P option will be global and apply to both old and new image in memory, except for no-IP entries that would be applied only once.

FILES
./fnprints.dat, ~/.fenris/fnprints.dat, /etc/fnprints.dat, ~/fnprints.dat, default fingerprints database locations (in order of search)

SECURITY
This program is not intended to be used on any production system to audit binaries originating from unknown sources and of possibly harmful nature. Because fenris performs real-time tracing, there is no way to ensure that actions taken by traced applications are legitimate and that output is not tampered with. Please use objdump(1) and gdb(1) to examine suspected code in trusted systems.

BUGS
Numerous. Please consult /usr/doc/fenris/README for a complete list of known bugs, then visit http://lcamtuf.coredump.cx/fenris/ to get the recent version of this program. If this does not help, use fenris-bug(1) bug reporting utility or mail the author.

SEE ALSO
ragnarok(1), fprints(1), getfprints(1), fenris-bug(1), ragsplit(1), strace(1), ltrace(1), gdb(1), objdump(1), ptrace(2), fnprints.dat(5).

AUTHOR
fenris was written by Michal Zalewski <lcamtuf@coredump.cx>.