#!/usr/bin/perl
# POD documentation for the Examiner
# I chose not to include this in the source itself so it's here.  If you don't
# Like that just delete the first line and append it to the end of the proggie.
__END__

=head1 NAME

B<examiner - A ELF binary executable analyzer>

=head1 SYNOPSIS

B<examiner> [ B<-hvVsHRLq> ] [ B<-d directory> ] [ B<-C coroner.conf> ] [ B<-o outfile> ] [ B<-c 'comment char'> ] -x executable

=head1 DESCRIPTION

The I<examiner> is a program used to analyze and comment on ELF executables.
Its purpose is mainly intended for forensic analysis but can be used for
general reverse engineering.  The goal is to take a foreign executable and
analyze it without running it.  The I<examiner> relies on objdump to do its
disassembly and then it parses the assembly output and attempts to put
human readable comments to help facilitate analysis of the binary.

The commented file will be created with the name of the target binary with
the extension of .commented.  By default the Examiner creates F<$HOME/examiner-data> directory 
to store its output.  This can be overridden with the B<-d> option.  Also if
The Coroners Toolkit (TCT) is installed the I<examiner> will use the
directory specified by TCT.  See below for more information for using 
the Examiner with TCT.  You may use the B<-o> option to specify a seperate
file for the commented source.  If you use B<-o -> Then Examiner will print
the commented source to STDOUT.

The I<examiner> requires that you use the B<-x> option to specify an executable
to analyze.  By default the I<examiner> only reports what Phase of analysis
it is currently working on.  The I<examiner> analyzes binaries in four
phases.

=over

=item PHASE 1 - Initial analysis and parsing

=item PHASE 2 - Passes over the information and collects info

=item PHASE 3 - Manipulates collected data to draw conclusions

=item PHASE 4 - Generate the commented output

=back

If the B<-v> option is used then the program will report on each step within
the phase as well.  You can also have a brief summary reported that will
give you some information about the total number of functions found, etc.
If you don't want any output you can use the B<-q> option.

The I<examiner> will attempt to read ASCII strings from the .rodata section
headers.  It will then cross references this information in its output.
It attempts to only print the printable characters and display hex or C style
representations for special characters such as '\n'.  In the commented output
the I<examiner> will restrict the length of the string.  This feature can be
overridden with the B<-L> option.  This is really not recommended.

You can generate additional reports that may help in analysis.  If the B<-H>
option is supplied it will dump each section in the executable.  The files
are stored in the working directory.  These files will have the target
executables name with the section as an extension, eg: binary.rodata.

You can generate Reference files with the B<-R> option.  These files are
generated for help in cross referencing information.  Currently it will
create three files: functions, interrupts, and sections.  The function
file contains the guessed function name and it's address.  The interrupts
file list any interrupts that are called and what the stack would look like
at the time (sort of).  The section file contains a list of all section and
their memory ranges.

For a brief summary of all the options you can use the B<-h> option.
If you supply the B<-V> option I<examiner> will print its version info and
then exit.

=head1 USING EXAMINER WITH TCT

The I<examiner> can optionally be run on a system that has The Coroners Toolkit
(TCT) installed.  The Examiner will use some executables when the are
installed.  The paths to these may be specified in TCT paths.pl file.  The
Examiner will also read in the F<coroner.conf> file to locate the section it
should use as its working directory.  You can specify a different F<coroner.conf>
file with the B<-C> option.

The newer version of the Examiner will read in an optional hash library.
This library is simply hash references that would normally be generated by
parsing the F<net.h> and  F<unistd.h> files.  This file F<examiner_hashes.pl> 
will be parsed if its in the current directory or F</usr/share/tct>.  F<unistd.h> is substituted for F<syscall.h> on BSD based systems.  Check the F<os>
directory for some pre-created examiner hashes.

=head1 FILES

=over

=item F<coroner.conf> - (optional conf file)

=item F<examiner_hashes.pl> - (optional) If present won't parse header files

=back

=head1 LICENSE

The program is copyrighted by Craig Smith under the terms of the GPL

=head1 AUTHOR(s)

Craig Smith

=cut
