Finish up plugin docs, including a master index.

This closes #6.

docs/Plugins.md

@@ -0,0 +1,82 @@
+Plugin Index
+============
+
+PANDA has many plugins. Here we provide a comprehensive index, broken down by categories.
+
+Taint-related plugins
+---------------------
+
+* [dead_data](../qemu/panda_plugins/dead_data/USAGE.md)
+* [ida_taint](../qemu/panda_plugins/ida_taint/USAGE.md)
+* [ida_taint2](../qemu/panda_plugins/ida_taint2/USAGE.md)
+* [file_taint](../qemu/panda_plugins/file_taint/USAGE.md)
+* [taint](../qemu/panda_plugins/taint/USAGE.md)
+* [taint2](../qemu/panda_plugins/taint2/USAGE.md)
+* [taint_compute_numbers](../qemu/panda_plugins/taint_compute_numbers/USAGE.md)
+* [tainted_branch](../qemu/panda_plugins/tainted_branch/USAGE.md)
+* [tainted_instr](../qemu/panda_plugins/tainted_instr/USAGE.md)
+* [tstringsearch](../qemu/panda_plugins/tstringsearch/USAGE.md)
+
+Plugins related to [Tappan Zee (North) Bridge](http://wenke.gtisc.gatech.edu/papers/tzb.pdf)
+-----------------------
+
+* [textfinder](../qemu/panda_plugins/textfinder/USAGE.md)
+* [textprinter](../qemu/panda_plugins/textprinter/USAGE.md)
+* [textprinter_fast](../qemu/panda_plugins/textprinter_fast/USAGE.md)
+* [unigrams](../qemu/panda_plugins/unigrams/USAGE.md)
+* [bigrams](../qemu/panda_plugins/bigrams/USAGE.md)
+* [memdump](../qemu/panda_plugins/memdump/USAGE.md)
+* [keyfind](../qemu/panda_plugins/keyfind/USAGE.md)
+* [memsnap](../qemu/panda_plugins/memsnap/USAGE.md)
+* [memstrings](../qemu/panda_plugins/memstrings/USAGE.md)
+* [correlatetaps](../qemu/panda_plugins/correlatetaps/USAGE.md)
+* [stringsearch](../qemu/panda_plugins/stringsearch/USAGE.md)
+* [tapindex](../qemu/panda_plugins/tapindex/USAGE.md)
+
+Callstack Tracking
+------------------
+
+* [fullstack](../qemu/panda_plugins/fullstack/USAGE.md)
+* [printstack](../qemu/panda_plugins/printstack/USAGE.md)
+* [callstack_block_pc](../qemu/panda_plugins/callstack_block_pc/USAGE.md)
+* [callstack_instr](../qemu/panda_plugins/callstack_instr/USAGE.md)
+
+Operating System Introspection (OSI) plugins
+--------------------------------------------
+
+* [osi](../qemu/panda_plugins/osi/USAGE.md)
+* [osi_linux](../qemu/panda_plugins/osi_linux/USAGE.md)
+* [osi_test](../qemu/panda_plugins/osi_test/USAGE.md)
+* [osi_winxpsp3x86](../qemu/panda_plugins/osi_winxpsp3x86/USAGE.md)
+* [asidstory](../qemu/panda_plugins/asidstory/USAGE.md)
+* [linux_vmi](../qemu/panda_plugins/linux_vmi/USAGE.md)
+* [debianwheezyx86intro](../qemu/panda_plugins/debianwheezyx86intro/USAGE.md)
+* [testdebintro](../qemu/panda_plugins/testdebintro/USAGE.md)
+* [win7x86intro](../qemu/panda_plugins/win7x86intro/USAGE.md)
+
+System call logging & analysis
+------------------------------
+
+* [syscalls](../qemu/panda_plugins/syscalls/USAGE.md)
+* [syscalls2](../qemu/panda_plugins/syscalls2/USAGE.md)
+* [win7proc](../qemu/panda_plugins/win7proc/USAGE.md)
+* [fdtracker](../qemu/panda_plugins/fdtracker/USAGE.md)
+
+Miscellaneous
+-------------
+
+* [bir](../qemu/panda_plugins/bir/USAGE.md)
+* [tralign](../qemu/panda_plugins/tralign/USAGE.md)
+* [bufmon](../qemu/panda_plugins/bufmon/USAGE.md)
+* [coverage](../qemu/panda_plugins/coverage/USAGE.md)
+* [llvm_trace](../qemu/panda_plugins/llvm_trace/USAGE.md)
+* [lsmll](../qemu/panda_plugins/lsmll/USAGE.md)
+* [memsavep](../qemu/panda_plugins/memsavep/USAGE.md)
+* [memstats](../qemu/panda_plugins/memstats/USAGE.md)
+* [network](../qemu/panda_plugins/network/USAGE.md)
+* [pmemaccess](../qemu/panda_plugins/pmemaccess/USAGE.md)
+* [rehosting](../qemu/panda_plugins/rehosting/USAGE.md)
+* [replaymovie](../qemu/panda_plugins/replaymovie/USAGE.md)
+* [sample](../qemu/panda_plugins/sample/USAGE.md)
+* [scissors](../qemu/panda_plugins/scissors/USAGE.md)
+* [useafterfree](../qemu/panda_plugins/useafterfree/USAGE.md)

qemu/panda_plugins/bir/USAGE.md

@@ -4,6 +4,8 @@ Plugin: bir
 Summary
 -------
 
+FIXME: don't know how `bir` is supposed to work.
+
 Arguments
 ---------
 

qemu/panda_plugins/osi_winxpsp3x86/USAGE.md

@@ -4,7 +4,7 @@ Plugin: osi_winxpsp3x86
 Summary
 -------
 
-`osi_winxpsp3x86` is an introspection provider for Windows XP SP3 guests, supplying information for the OSI API. Not much more to say about it; it should Just Work as long as the guest OS is Windows XP SP3.
+`osi_winxpsp3x86` is an introspection provider for Windows XP SP3 32-bit guests, supplying information for the OSI API. Not much more to say about it; it should Just Work as long as the guest OS is Windows XP SP3.
 
 Arguments
 ---------
@@ -28,3 +28,8 @@ Running `osi_test` on an Windows XP SP3 32-bit replay:
 
     $PANDA_PATH/x86_64-softmmu/qemu-system-x86_64 -replay foo \
         -panda osi -panda osi_winxpsp3x86 -panda osi_test
+
+Bugs
+----
+
+The `osi_winxpsp3x86` plugin currently does not support listing loaded kernel modules, even though the OSI API suggests that it should.

qemu/panda_plugins/taint2/USAGE.md

@@ -17,7 +17,7 @@ PANDA's taint system is implemented by translating TCG code to LLVM and then ins
 
 Note that the `taint2` plugin replaces the original `taint` plugin and is preferred for most use. The main improvements are:
 
-* Speed: `taint2` is much faster due to inlining taint operations into the generated LLVM code rather than accumulating taint operations in a buffer and the processing them after each basic block.
+* Speed: `taint2` is much faster (rough estimate: ~10x) due to inlining taint operations into the generated LLVM code rather than accumulating taint operations in a buffer and the processing them after each basic block.
 * Memory: many analyses were simply impossible in the original `taint` plugin because the memory requirements were too high. `taint2` should solve this. Note that because it uses a large `mmap`ed area for its shadow memory, you may need to adjust the value of `vm.overcommit_memory` via `sysctl`.
 * Interface: the interface to `taint2` is somewhat cleaner, and allows things like tainted branch, tainted instruction, and taint compute number counting to be implemented as separate plugins.
 

qemu/panda_plugins/tainted_instr/USAGE.md

@@ -16,12 +16,6 @@ Dependencies
 
 `tainted_instr` uses `taint2` to track taint, and `callstack_instr` to provide callstack information whenever tainted branches are encountered.
 
-    panda_require("taint2");
-    assert(init_taint2_api());
-    panda_require("callstack_instr");
-    assert (init_callstack_instr_api());
-    PPP_REG_CB("taint2", on_taint_change, taint_change);
-
 APIs and Callbacks
 ------------------
 

qemu/panda_plugins/tapindex/USAGE.md

@@ -4,23 +4,42 @@ Plugin: tapindex
 Summary
 -------
 
+The `tapindex` plugin creates an index listing how many bytes are read or written by each tap point. This index can then be used in conjunction with the `memdump` plugin to quickly search for patterns read from or written to memory and map them back to individual tap points.
+
+The plugin creates two files, `tap_reads.idx` and `tap_writes.idx`. Once you have both a memory dump (`tap_reads.bin` and `tap_writes.bin`) and the index files, you can map offsets in the dump to tap points using `scripts/idxmap.py` (see the Example section for an example of its use).
+
 Arguments
 ---------
 
-
+None.
 
 Dependencies
 ------------
 
-
+None.
 
 APIs and Callbacks
 ------------------
 
+None.
+
+Example
+-------
+
+Generate an index:
 
+    $PANDA_PATH/x86_64-softmmu/qemu-system-x86_64 -replay foo \
+        -panda tapindex
 
+Then dump memory with `memdump`:
 
+    $PANDA_PATH/x86_64-softmmu/qemu-system-x86_64 -replay foo \
+        -panda memdump
 
-Example
--------
+Now search for something in the memory reads dump and store the offsets where it's found into a file named `foo_offsets.txt`:
+
+    grep -bao 'foo' tap_reads.bin | cut -d: -f1 > foo_offsets.txt
+
+And finally, we can map that back to individual tap points with:
 
+    scripts/idxmap.py tap_reads.idx foo_offsets.txt

qemu/panda_plugins/testdebintro/USAGE.md

@@ -4,23 +4,33 @@ Plugin: testdebintro
 Summary
 -------
 
+Despite its name, `testdebintro` is not actually specific to Debian introspection. Rather, it is a test plugin that can be used to see if `osi` is working, similar to the `osi_test` plugin. Instead of printing out information periodically as `osi_test` does, it instead implements a monitor callback so that whenever `plugin_cmd pid` is entered the monitor it will dump out the current process and a list of running processes.
+
 Arguments
 ---------
 
-
+None.
 
 Dependencies
 ------------
 
-    if(!init_osi_api()) return false;
+`testdebintro` uses the `osi` plugin to provide information about the guest operating system. As with other plugins based on `osi`, you will also need an *introspection provider* such as `win7x86intro` or `osi_linux`.
 
 APIs and Callbacks
 ------------------
 
+None.
 
+Example
+-------
 
+The `testdebintro` plugin can be run on a live VM. Supposing we have a Windows 7 32-bit virtual machine:
 
+    $PANDA_PATH/x86_64-softmmu/qemu-system-x86_64 -hda win7.qcow2 -m 1G -monitor stdio \
+        -panda osi -panda win7x86intro -panda testdebintro
 
-Example
--------
+Then, while the system is running, enter at the qemu monitor:
+
+    QEMU 1.0,1 monitor - type 'help' for more information
+    (qemu) plugin_cmd pid
 

qemu/panda_plugins/textfinder/USAGE.md

@@ -4,23 +4,40 @@ Plugin: textfinder
 Summary
 -------
 
+The `textfinder` plugin writes out a report of memory writes, grouped by tap point, with a histogram of the individual bytes written.
+
+Output is placed in a binary file called `mem_report.bin`. It can be parsed with the following Python code:
+
+```Python
+f = open('mem_report.bin')
+ulong_size = unpack("<i", f.read(4))[0]
+ulong_fmt = '<u%d' % ulong_size
+print >>sys.stderr, "target_ulong size: %d" % ulong_size
+print >>sys.stderr, "Loading data...",
+rectype = np.dtype( [ ('caller', ulong_fmt), ('pc', ulong_fmt), ('cr3', ulong_fmt), ('hist', '<I4', 256) ] )
+data = np.fromfile(f, dtype=rectype)
+print >>sys.stderr, "done (%d tap entries loaded)" % data.size
+```
+
+**Warning**: `textfinder` is deprecated. Please use `unigrams` instead.
+
 Arguments
 ---------
 
-
+None.
 
 Dependencies
 ------------
 
-
+None.
 
 APIs and Callbacks
 ------------------
 
-
-
-
+None.
 
 Example
 -------
 
+    $PANDA_PATH/x86_64-softmmu/qemu-system-x86_64 -replay foo \
+        -panda textfinder

qemu/panda_plugins/textprinter/USAGE.md

@@ -4,23 +4,68 @@ Plugin: textprinter
 Summary
 -------
 
+The somewhat misnamed `textprinter` plugin writes the contents of any data flowing through a set of tap points out to a log file. These log files can then be examined and processed to look for interesting information.
+
+The plugin is usually used after identifying some tap points of interest, using something like the `stringsearch` plugin.
+
+`textprinter` reads a list of tap points to monitor from a file named `tap_points.txt`, one per line. Each tap point consists of a caller, program counter, and address space.
+
+`textprinter` saves output to two files named `read_tap_buffers.txt.gz` and `write_tap_buffers.txt.gz`. These logs are gzipped text files that have entries of the form:
+
+    [Callstack] [PC] [ASID] [Virtual Address] [Access Count] [Byte Value]
+
+The virtual address is the location in memory where the data was read from or written to. The access count is a number indicating how many memory operations have occurred; the idea is that for a multi-byte write (e.g., `mov DWORD PTR [0x1234], eax`) all four bytes will have the same access count.
+
+Once you have a tap point log, you can split it up into its constitutent tap points with `scripts/split_taps.py`:
+
+    $ scripts/split_taps.py --help
+    usage: split_taps.py [-h] [-c CALLERS] logfile prefix
+
+    Split a logfile containing tap point data into its constitutent taps.
+
+    positional arguments:
+      logfile               log file containing tap point data (can be gzipped)
+      prefix                prefix for output files
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -c CALLERS, --callers CALLERS
+                            levels of calling context to use when splitting
+
+The resulting files will contain the raw data seen at each tap point.
+
 Arguments
 ---------
 
-
+None.
 
 Dependencies
 ------------
 
-    if(!init_callstack_instr_api()) return false;
+`textprinter` uses the `callstack_instr` plugin to get callstack information for each memory access.
 
 APIs and Callbacks
 ------------------
 
+None.
+
+Example
+-------
+
+First create a file called `tap_points.txt` with your tap points:
 
+    683158d0 686a375c 3eb5b180
+    680c54e2 686dd7e3 3eb5b180
 
+Then run PANDA with `textprinter`:
 
+    $PANDA_PATH/x86_64-softmmu/qemu-system-x86_64 -replay foo \
+        -panda textprinter
 
-Example
--------
+You will get output in `read_tap_buffers.txt.gz` and `write_tap_buffers.txt.gz`. This snippet of such a log file shows four bytes (`0x8d 0x64 0x24 0x04`) being written to address `0x001aebe8`:
+
+    692483d1 [...] 683158d0 686a375c 3eb5b180 001aebe8 3331087336 8d
+    692483d1 [...] 683158d0 686a375c 3eb5b180 001aebe9 3331087336 64
+    692483d1 [...] 683158d0 686a375c 3eb5b180 001aebea 3331087336 24
+    692483d1 [...] 683158d0 686a375c 3eb5b180 001aebeb 3331087336 04