-------------------------------------------------------------------------------
code snippet creator plugin for ida pro by servil
version 0.990 beta (Oct 2008)
supported ida versions: 4.9 and above till API change
(tested on 5.2 without backward compatibility enforcement)
-------------------------------------------------------------------------------

basic ida plugin to automate migration of one or more functions from host
program to custom assembly project (primarily masm targetted). some effort was
put to be generic and able to process any processor and format based on
function model using basic assembler data types (byte, word, dword...), however
focussed and only properly tested on 32-bit borland and msvc code and is
expected to give best results for these compilers (generally the more actual
format is distant from pe-32 the less functionality you may expect), also all
runtime features only are available for pe-32 formats.

major features:

  * static code and data flowgraph traversal
  * static data formatting and bounds determining
  * code and data integrity care
  * integrated runtime evaluated addressing resolver (orig. executable required)
  * integrated process data dumping with emulation of accessed virtual data and
    stack variables (orig. executable required)
  * iat address translation for dynamic runtimes build (pe-32 only)
  * lexical compatibility adjustments, name conflicts resolving and basic
    output garbage cleanup
  * final flowgraph (version 5.1 and newer)

plugin is designed to cover all possible address ranges the root function(s)
can access in real. the plugin is not click and go solution, only benefit csc
gives is reduction of boring uphill work - in most cases output will need
manual adjustments to pass compiler. plugin always builds reportlist hiliting
warnings, problems, unsure places, etc..., beside it doubtful lines are
commented in the sourcecode also.
note: the ripper generally explores every x-ref from every address triggered.
unwanted output grow may be caused by false offsets in passed code, in such
case restrict the rules in start dialog or seek`n`destroy false offsets (this
may give quite headache though). generally exhaustive output should be expected
if exporting a top-level function or not disabling library code in output
(depends on type of application and runtime libraries used to compile).
code traversal is based on x-refs, not raw operand values, so that mutual
linkage of related ranges can be flexibly adjusted by user offsets or x-refs
manager (see below).

the plug got 3 components:

1. code ripper self
   this is the main component: basic (optionally) recursive deadcode traversal
   and creating output source file. for csc better results dont use 'coagulate
   data segments in final pass` ida analysis option (offsets and other
   meaningful types can be hidden inside dummy arrays made by ida). additional
   options and adjustments are available from startup dialog. most obvious
   enough, two run-time features explained here:

   * runtime evaluated addressing resolver is useful for discovering indirect
     or runtime-evaluated jump/call targets (eg. call dword ptr [edx+08h], jmp
     eax, etc.): while targets are evaluated and reached at run-time in host
     application naturally, they are invisible at export time from deadcode,
     thus they wouldn't be expectingly not even exported. the resolver cares of
     tracing real targets and including targets to output - recommended for
     images written by OOP language.

   * process data dumper recognizes offsets to image range and to a known heap
     block. currently these dynamic block types are recognized: msvc malloc,
     delphi/cbuilder getmem, bcc malloc, gnu gcc malloc, virtualalloc, stack
     variables. relaxing the rules for offset recognition may increase amount
     of false offsets rapidly. runtime engines can process both standalone
     executables and dll`s on certain conditions (a loader directly executable
     by createprocess is present, loads the dll at some time and executes
     desired code there, loader once chosen saved to netnode is used any
     later). the image containing exported ranges must not be packed.
     note: csc dont handle resource. any resource accessed by the snippet must
     be saved by a 3rd-party tool (reshacker for ex.) to .res/.rc format and
     relink with snippet.

2. indirect flow resolver from external debugger
   this component was replaced by integrated resolver of code ripper providing
   same job the simplier way, this component is kept for rare cases.
   co-operative helper plugin for ollydbg is kept in .\flowinsp\ dir.
   development of this part was stopped.

3. flirt names matching (a helper for code ripper)
   comparing libnames recognized by flirt to real library names is helpful to
   prevent later linking problems (unmatched names get library flag removed),
   worx in conjunctin with code ripper's 'include library functions` option
   turned off. the exact match method takes into account stdlib names
   decoration so names _GetModuleHandleA@4, _GetModuleHandleA,
   GetModuleHandleA and __imp__GetModuleHandleA are considered same (but not
   so GetModuleHandle).
   available input formats for capturing names: coff objfiles and static libs,
   omf objfiles and static libs, coff and omf implibs, 32bit executables with
   exports.
   the comparison engine cares of name types, names placed in code area only
   are matched to names marked as code in library and vice versa about data
   names. type sensitivity is off if input format doesnot support type
   classification or option `ignore name type` is checked. this is helpful for
   dummy libraries deklaring everything public as code (e.g. implibs made out
   of autogenerated .def files)
   note: use 'fix mangling...` feature only on own risk as its very slow and
   very expreimental (no fundamental method was adapted to find safely
   alternate name on unmatched names) - its always better to use
   version-specific signatures for that sdk. `fix mangling...` is capable to
   parse not-too-complex ms c++ and borland c++ names, then find name from
   library that sounds similar (similar in meaning same root name, but
   different type or wrapper class). this option is off by default and
   reviewing list of changed names is highly advised when active.

4. xrefs manager (plugin call parameter 3)
   view/create/remove user links between any two places of disassembly. two
   samples of usage: for code ripper to cover code or data ranges not referred
   from any of collected static areas or to change anchor point of non-head
   memory operands (o_mem) [note: for non-head offsets use user offset <ctrl-r>
   instead, the anchor point will be adjusted automatically by kernel, not so
   on memory access operands].
   note: user xrefs from memory-access operands are not stable against regular
   kernel re-analysis on level of ua_code (ua_ana) and higher. csc uses 'weak'
   analysis (a_ana0) wherever possible to retain user x-refs, however not so
   may other components do (and most probably they won't). user xrefs also
   aren't resistent against analysis invoked from gui (such as pressing 'c').
   use insert/delete to add/remove x-refs from address at cursor. enter jumps,
   escape exits.
   (xrefs auto-convert tail -> head+offset helper with param 4)

to install copy .plw to <ida>\plugs\. to enable helper features, append
these lines to plugs.cfg:

    xrefs_manager...                       csc    0          3
    match_flirt_names...                   csc    0          2
;    resolve_indirect_calls_from_ollydbg... csc    0          1   ; deprecated
    code_snippet_creator...                csc    alt-f10    0

known bugs and limitations:
shure ;)

servil


some changelog:

0.979 alpha (08/01/05)
+ code ripper: preventing local<->global name conflicts
+ code ripper: more detection of truncated variables
+ code ripper: process heap exploring + replicating (experimental)
+ code ripper: remapping libfunc offsets for dynamic link
+ code ripper: process dumper func arguments analyzing and stack arglist saving
! code ripper: care referring tail lines of excluded functions
! flirt names matching: occassional setting library flags back

0.97 (07/15/05)
+ a bit description made
+ added flirt names matching helper
+ code ripper: added offset revealing filter (only make offset to defined heads)
+ code ripper: added option to undef enums (compat. issue)
+ code ripper: added runtime evaluated flow resolving directly in ida, faster
  and simplier than via ollydbg
+ code ripper: added runtime data dumper (executed directly in ida, dump values
  at snippet start to disassembly, affects only .data and .bss segments)
+ code ripper: added recognition of library variables
! code ripper: fixed exporting of collapsed functions
! code ripper: fixed xrefs enumerating from fresh formatted variables
+ new bugs again

0.96 (04/29/05)
* recompiled for new ida api
! some minor fixes i can't remember

0.95 (01/05/05)
+ added filter to skip hidden (collapsed) entities (applies to functions and
  segments)
+ added asm compatibility option to disable enums in output (due to laziness
  not implemented into gui, can be set in csc.ini however)
    [csc]
    enums=[0|1]
  defaults to 1 (enabled), turning off may reduce compiling errors
! fixed destroying of local structs didn't work for non bp-frame based
  functions
+ added full support for new ida function ranging model (all ranking chunks of
  function are covered in the output). this disables plugin downward
  compatibility (not updated for older ida versions more)
! importing references from tracelog/flowtable ignores extern addresses
! bug fixed in flow inspector so it can handle register calls and jumps in
  autoresolve mode
! zillion of small adjustments whose i can't remember atm ;_)
