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


                         Bastard  Disassembly  HOWTO



================================================================================
 Contents

 1. Down and Dirty with the CLI
 2. Streetwalking with the Bastard API
 3. Modifying an Initial Disassembly
 4. Producing Output Files
 5. DB Queries and Reports
 
 A. CLI Tricks
 B. The Little Grey Bastard

================================================================================
 1: Using the CLI

The bastard is designed to operate as an interpreter: you can type in it, you
can script it, you can pipe to it, in the future you will even be able to cat
binary files to it. In general, however, it will be controlled with a front-end
such as a script.

The utils/ directory contains a few sample shell scripts which can be used to
produce the disassembly of an ELF file to stdout:
   
   disasm.color.sh      produces a 'full' disassembly in ANSI color
   disasm.full.sh       produces a 'full' disassembly in mono
   disasm.text.sh       produces a disassembly of .text in mono
   
These scripts can be run from any location. The bastard installs itself to
/usr/local/bastard with a symlink to /usr/local/bin; left to these settings, it
will correctly locate its shared libraries in /usr/local/bastard/lib, however
if its home directory is moved, these libraries must be in LD_LIBRARY_PATH as
usual.

When run as a shell --e.g. by just typing `./bastard`-- the full CLI commands
can be used:

   LOAD [target [format [arch]]]  : Load and disassemble a file
   BDB  [bdbname]                 : Load previously-disassembled file

   DISASM [outfile]               : Print a disassembly of target
   DUMP                           : Print a hexdump of target
   STRINGS                        : Print list of found strings
   SECTION name                   : Print disassembly of section 'name'
   RANGE   start end              : Print disassembly of 'start' to 'end' rva
   HEADER                         : Print program file header
   
   DEBUG                          : Run target in a debugger
   EXEC   [command]               : Execute a shell command
   RUN    script                  : Run a .bc script file
   {{     \n script \n  }}        : Code and execute a script

   
   API                            : Display bastard.h in pager
   HOWTO                          : Display this HOWTO in pager
   MAN                            : Display the manual in pager

   QUIT                           : Exit the bastard

Some of these commands have one-character aliases for convenience:
      L LOAD               R RANGE
      B BDB                S SECTION
      D DISASM             A STRINGS
      U DUMP               Q QUIT
      H HEADER             M MAN
      ? HELP
Neither the commands nor their aliases are case-sensitive.

The LOAD command is the most important; its complete invocation is
    LOAD target  file_format  cpu_arch
and the parameters default to
    LOAD "./a.out"  "ELF" "i386"
...which is what the command will be if you just type "L" (though if the 
target name is passed on the command line, as in `./bastard /usr/bin/tr`,
it will replace "./a.out"). For Linux x86 ELF files, the syntax
    LOAD target
will be sufficient. For other files, "format" must be a .bc or a .so in
the formats/ directory, and "arch" must be a .bc or a .so in the arch/
directory. Note that only the base name should be specified, so that "ELF.bc"
and "libELF.so" both are referred to as "ELF".

When a file is loaded, the display will look like this:

   =========================================================================
      B A S T A R D                    disassembly environment
      brought to you by the proud folks at the HCU linux forum
   ;>l
   Disassembling named symbols. Instruction stack:
   --------------/

The "---" line displays a visual stack representing the nesting of the program;
when it unwinds all the way, the disassembly will finish, and another prompt
will appear. Disassembly time is usually 2-3 minutes per MB.

At this point, various information about the file can be displayed with 'H'
(file header), 'A' (strings), 'D' (disassembly), and so on. Further modification
of the file requires running external scripts or using the API directly, and 
will be treated in other sections.

To exit the disassembler, type 'Q' for QUIT. The .bdb file for the target will
be saved automatically, for future use. 


================================================================================
 2: Using the API

    The Bastard API
    ---------------
     bastard.h

    Calling API Routines in the CLI
    -------------------------------

    Using Multiline Scripts
    -----------------------

    Running External Scripts
    ------------------------

    Running Plugins
    ---------------
    
    Direct Extension Access
    -----------------------
     extension.h


 
================================================================================
 3: Working with the Disassembly

    Naming Addresses
    ----------------

    Adding Comments
    ---------------

    Identifying Strings
    -------------------

    Defining Functions
    ------------------

    Using Structures
    ----------------

    Constants and Data Types
    ------------------------

    Inline Functions
    ----------------


================================================================================
 4: Producing Output Files

The easiest way to produce an output file with the CLI is to use the DISASM
command:
   ;>D disasm.out
This will write the disassembly output to the file disasm.out .

A second method is to use the redirection operator (>) built into the CLI; this
will redirect stdout to an arbitrary file:
   ;>D > disasm.out
Note that the file will be appended if it exists, not truncated; thus the >
operator acts more like >> in shell.

The final method for creating output files is to use the API routines directly:

   SaveAsASM(char *filename);    /* Save as asm suitable for re-assembly */
   SaveAsLST(char *filename);    /* Save as a disassmbled listing */
   SaveAsHLL(char *filename);    /* Save as code in High Level Lang */
   SaveAsDump(char *filename);   /* Save as a Hex Dump */
   SaveAsDiff(char *filename);   /* Save as a binary diff with the original */
   SaveAsBinary(char *filename); /* Save as an executable */

Note that SaveAsASM and SaveAsHLL are simply wrapper functions for the file
generation routines in the ASM and LANG extensions; SaveAsDiff and SaveAsBinary
are intended for binary patching, and are currently not supported.


================================================================================
 5: Working with the Database
 

 The CLI DB Interface

 The DB API Interface

   
================================================================================
 A: CLI Tricks

 * Use pipes : |
   This works very well with grep, wc, head, and sed.

 * Use redirection : >

 * Use 'set' and 'show' to change runtime settings


================================================================================
 B: LGB

The lgb, aka Saraboos, is a very crude Tk front-end to the bastard residing in 
the utils directory; it is intended to simplify the very basic operations of 
the bastard. The usage is a pretty straightforward, menu-driven approach; those
not wishing to brave the CLI are invited to suffer the limitations of lgb (which
still provides a console for direct CLI command entry).


