================================================================================
B A S T A R D                                            disassembly environment


Introduction
============
The bastard is a UNIX disassembler developed primarily for use on x86 Linux
ELF binaries. Its features include an embedded database, a C-like scripting
language, and a modular design that allows the user to replace automated
analysis routines.

See the man pages or the HOWTO [doc/Disasm-HOWTO.txt] for a more detailed
introduction to the bastard. The text files in doc/ also provide a more 
in-depth look at the bastard, its usage, and its internals.

For those who dislike the command line interface, a Gtk front-end called 
'sob' can be built [see "Installation"]. 


Installation
============
The disassembler should be compiled with:

	make install
	
This will compile the bastard and install it to /usr/local/bastard, with the
main executable symlinked to /usr/local/bin/bastard. It is recommended that
'make install' be performed with a binary distribution as well in order to
put libbastard in the library path. This can be bypassed by doing

	user@localhost>LD_LIBRARY_PATH=/usr/local/bastard/lib \
	               /usr/local/bastard/bin/bastard
						
or any of the usual UNIX techniques. 


Starting with version .14, a Gtk GUI is supplied with the bastard and can
be compiled and installed from the main makefile with:

	make sob-install
	
This will compile the sob binary and install it in /usr/local/bastard/bin, 
with a symlink in /usr/local/bin. Note that 'bastard' and 'sob' are linked
with ./lib automatically added to the library search path, so running either
of these from within the bastard home directory will work fine.

The sob utility is a Gtk front-end to libbastard.so; it is under heavy
development and does not pretend to be a full-featured, or even fully-
functional, application. It is included for user experimentation, as an
example of writing a libbastard front-end, and to provide some solace for
those who fear anything on the console.


The bastard can be run from any directory; it will determine the location of
its home directory based on the location of the bastard binary. Therefore it 
is important to leave the bastard binary in its home directory, and use 
symlinks to place it in the path. Alternatively, the environment variable
$BASTARD_HOME can be set to override the location of the home directory.

NOTE: if you do a "make" rather than a "make install", the bastard [or sob]
will build correctly but will remain in the current directory and will not
be moved to /usr/local/bin; this is recommended for developers who do not
want to trash their working version of, say, .14 for something as potentially
chaotic as .16. When built this way, the bastard [or sob, or any of the other
front-ends] can be executed with

	bin/bastard
	
from within the root of the bastard distribution [e.g., /usr/src/bastard-0.16].



The makefile contains a few options [program name, install location, etc] at
the very top if the defaults are not satisfactory. In order to do partial 
builds, the makefile provides the following targets:

	all           -- make the program and required libraries
	install       -- make all, install to $(INSTALL_DIR), link to $(INSTALL_BIN)
	uninstall     -- remove $(INSTALL_DIR) and links in $(INSTALL_BIN)
	sob           -- make the sob GUI 
	sob-install   -- install sob to $(INSTALL_DIR) and $(INSTALL_BIN)
	sob-uninstall -- remove sob from $(INSTALL_DIR) and $(INSTALL_BIN)
	sob-clean     -- remove the binaries and object files for sob
	eic           -- make the eic library and utilities
	typhoon       -- make the typhoon library and utilities
	extras        -- make extra utilities [e.g. bobjdump]
	extras-clean  -- remove binaries, object files for extras
	extensions    -- make all extensions [e.g. arch/, formats/]
	ext-clean     -- remove binaries, object files for extensions
	libdisasm     -- make libdisasm in src/arch/i386/libdisasm
	bin/bastard   -- make bin/bastard binary
	libbastard.a  -- make lib/libbastard.a static library
	libbastard.so -- make lib/libbastard.so shared library
	release       -- make all, strip the executable and shared libraries
	clean         -- remove the binaries and object files
	distclean     -- remove the seer and typhoon object files
	tgz           -- make the distribution tarballs
	
Note that the default make targets include "extras" and "extensions", but 
not "sob" or "libdisasm".



Troubleshooting the Build
=========================
The required libraries and headers may need to be installed on your system, or
the build may fail for any number of reasons. The general procedures for manual
compilation if 'make all' does not work are:

	Readline [required, not included]:
	/usr/src/readline> ./configure;make;make install

	EiC [required]:
	/usr/src/bastard/src/EiC> config/makeconfig; make; make install
	/usr/src/bastard/src/EiC> cp lib/*.a /usr/src/bastard/lib
	/usr/src/bastard/src/EiC> cp include/eic* ../../include/script
	/usr/src/bastard/src/EiC> cp -r include/* ../../include/script/eic
               
	
	Typhoon [required]:
	/usr/src/bastard/src/typhoon> ./configure; make
	/usr/src/bastard/src/typhoon> cp src/libtyphoon.a /usr/src/bastard/lib

	Bastard:
	/usr/src/bastard> make && make install

	SOB [requires Gtk developer headers & libs]:
	/usr/src/bastard/src/sob> ./configure; make && make install
	/usr/src/bastard> make sob-install

Recently, EiC has failed to build "out of the box" for different reasons.
In using a version of EiC not supplied with the bastard, an uknown-type
error may be generated for "fpos_t"; the fix for this is as follows:

	Change line 221 of src/EiC/config/gensdtio from
		crt_inttypedef(fp, "fpos_t", sizeof(fpos_t));
	to
		crt_inttypedef(fp, "fpos_t", sizeof(__off_t));
	if EiC breaks with an fpos_t "unknown type" error.
		  
		  
Reports have it that the EiC 'make install' can break with a error such as 

	../../../include/cytpe.h: No such file
	
where "ctype.h" exists in src/EiC/module/stdClib/src but not in src/EiC/include.
The way to fix this it to remove the following files

	src/EiC/module/stdClib/src/instH  src/EiC/module/stdClib/src/instSysH

and run the build again. If this fails for the same reason, the include files
may be moved manually:

	cp src/EiC/module/stdClib/src/*.h src/EiC/include

and the build started over.

Remember, when all else fails, do a "make clean; make".



Required Libraries
==================
  libtyphoon	: Typhoon 1.11 Embedded Relational Database 
  libeic 		: EiC Embedded C Interpreter
  libreadline  : GNU readline library version 4.1

Both Typhoon and EiC are supplied with this distribution in binary and source
form; they can also be downloaded from the Bastard distribution site at

	http://www.sourceforge.net/projects/bastard
	
The licenses for the libraries are in .license/typhoon, .license/EiC, and 
.license/GNU.

Also, readline headers are assumed to be in $INCLUDE/readline.



Intended Usage
==============
All types of devious purposes.

In brief, the bastard is used to disassemble and examine arbitrary binary
files. The intended target is x86 ELF binaries; however the design of the
bastard is flexible enough that arbitrary CPU architectures and file formats
can be supported by writing "extensions" [C-like scripts and shared libraries].

When started, the bastard displays a command prompt [by default, ";>"] and
waits for the user to start issuing commands. The available commands can
be displayed  by typing "help" or "?"; in addition, C programming statements
and calls to the bastard programming API can be used.

For disassembling an ELF file, the command "l filename" will load and 
disassemble the file "filename", "d" will print the disassembly of the target,
and "q" will quit the bastard. Alternatively, the target can be redirected
to the bastard on the command line, for example:

	/home/work>cat /usr/bin/tr | bastard -- 
	/home/work>bastard -- < /usr/bin/yes 
	/home/work>bastard -- < /usr/bin/tail > tail.lst
	
Note that the "--" parameter causes STDIN to be read as the target binary,
rather than as a list of commands for the bastard to execute [which is the
default behavior].

Additional commands, as well as the BC scripting language, are documented
in the man pages; the include files api.h and bdb.h are also recommended
reading material. Finally, the README.CODERS file has hints on using the
bastard, a brief discussion of how it works, and the philosophy --such as it
is-- behind it.

Caveats: Typhoon uses a semaphore in /tmp, so two processes cannot use 
Typhoon simultaneously. This means that one process cannot make database calls
while another process is making them -- you can run two sessions of the bastard
concurrently, but they will have to take turns using the DB [e.g. printing a
disassembled listing, disassembling a file, and basically any behavior other
than sitting there idle]. This will be addressed in future releases.

The bastard can take quite a lot of diskspace during runtime [10-20 MB for
dynamic binaries, 20-100MB for static binaries] and may expand to fill 
available memory or CPU on some targets; static-linked binaries are especially
prone to this. While work continues to make runtime requirements more 
reasonable, be warned that the bastard is still very much a work in progress.


Design Goals
============
One point about the bastard which seems to get lost in all the excitement is
that is was designed to be an interpreter for disassembling and analyzing
binary files. This means is would act like perl or awk, running a set of
commands [a script] over the target binary file, or providing a prompt which
allows the user to manually enter commands line-by-line.

This means that the proper use of the bastard is to fire it up and use API
routines such as target_load(), target_set_arch(), and disasm_target() at 
the prompt or in a script. Since the API commands can be a bit clunky and
since the majority of disassembly requires the same common operations during
the automatic analysis phase, some "meta commands" have been provided in the
bastard that are essentially shortcuts [such as "l" and "d"]. These shortcuts
expand to API routines and, while convenient, can be immediately discarded in
favor of straight API routines when they fail.

The majority of the bastard extensions and plugins operate in the same manner:
they can all be jettisoned in favor of straight C and API calls at the command
prompt; though naturally with some of these [e.g., the ARCH disassembler] the
amount of work entailed is prohibitive.

Naturally this means that the bastard itself is tough to use and is not a
beginner's disassembler. Since most of the people who use a disassembler as
a precursor to byte patching aren't particularly advanced programmers, this
means the fuctionality of the bastard was largely being wasted. The creation
of libbastard provides the capability for front-ends of arbitrary complexity
[such as sob, bobjdump, and bdbdump] to be developed for use as standard
interactive or non-interactive disassemblers.



License
=======
This bastard is given artistic license to roam free, as specified in the file
.license/bastard in the bastard's home directory.

Despite the reuse provisions of the GNU license, which has a "forest for the
trees" flaw typical of rms' stuff and tends to violate in letter what it 
promises in spirit, the source code for libreadline is *not* being distributed
along with this package. The source code is too huge, and too readily available
from other sources ... in fact, it seems so far that every extant linux 
distribution comes with it.


CVS
===
Bastard developers can retrieve the latest source code from the CVS repository
at Sourceforge. The CVSROOT for the project is

	username@cvs.bastard.sourceforge.net:/cvsroot/bastard
	
and ssh must be used along with cvs to handle the remote connection.


For the lead-me-by-the-hand non-CVS types:

  [/usr/src]$>mkdir bastard; cd bastard
  [/usr/src/bastard]$>export CVS_RSH=`which ssh`
  [/usr/src/bastard]$>cvs -duser@cvs.bastard.sourceforge.net:/cvsroot/bastard co .

Alternatively, the cvs tarball can be downloaded from SourceForge at:

  http://cvs.sourceforge.net/cvstarballs/bastard-cvsroot.tar.gz
  
This tarball is updated nightly by Sourceforge.


Known Bugs
==========
Submit your favorites! See KNOWN_BUGS.txt.
