Update/create READMEs for all examples (#56)

hainest · web-flow · commit 5e79f72b8d0b · 2024-02-05T10:56:10.000-06:00
diff --git a/CFGraph/README.md b/CFGraph/README.md
@@ -0,0 +1,19 @@
+# Control Flow Graph
+
+## Create a Graphviz file from the CFG
+
+The following complete example uses ParseAPI to parse a binary and
+dump its control flow graph in the Graphviz file format.
+
+---
+
+## Usage
+
+Run the mutator
+
+	$ ./CFGraph /path/to/binary >binary.dot
+
+Convert the DOT file into an image
+
+	$ dot ./binary.dot binary.png
+
diff --git a/DynC/README.md b/DynC/README.md
@@ -0,0 +1,11 @@
+# DynC
+
+## The Dyninst C-like snippet language
+
+Dyninst is a powerful instrumentation tool, but specifying
+instrumentation code (known as an Abstract Syntax Tree) in the
+BPatch snippet language can be cumbersome. DynC API enables a programmer to easily and quickly build
+snippets using a simple C-like language. Other advantages to
+specifying snippets using DynC include cleaner, more readable
+mutator code, automatic variable handling, and runtime-compiled
+snippets.
diff --git a/README.md b/README.md
@@ -10,15 +10,9 @@ To configure the build, you can use
 
 NOTE: The last three parts of the `Dyninst_DIR` path *must* be the `lib/cmake/Dyninst` directory under your Dyninst installation.
 
-The project can be built out-of-source using the usual `-B` and `-H` CMake flags.
-
-The default CMake configure uses GNU Makefiles as the generator, so to build is just
-
-    make install
-
 To build only specific examples, you can specify their names like so
 
-    make codeCoverage CFGraph
+    cmake --build <build_dir> --target codeCoverage
 
 ## Running
 
diff --git a/codeCoverage/README.md b/codeCoverage/README.md
@@ -1,8 +1,11 @@
-This directory contains a simple code coverage tool built with DyninstAPI. The
-tool uses Dyninst to instrument every function in a program binary as well as
+# Code Coverage
+
+### A simple code coverage tool built with DyninstAPI
+
+The tool uses Dyninst to instrument every function in a program binary as well as
 optionally instrumenting every basic block to record code coverage data.  
 
-The goal of this tool is to demonstrate some of the capabilities of DyninstAPI.
+The goal is to demonstrate some of the capabilities of DyninstAPI.
 It does very little processing of the raw code coverage data, just some basic
 sorting when outputting the data. This tool should serve as the basis for
 creating a more feature-rich code coverage tool using Dyninst.
diff --git a/common/README.md b/common/README.md
@@ -0,0 +1,5 @@
+# Common files
+
+## Common files for the examples
+
+These are not intended to demonstrate any particular purpose of Dyninst.
diff --git a/dataflowAPI/README.md b/dataflowAPI/README.md
@@ -0,0 +1,25 @@
+# DataflowAPI
+
+## Small code snippets showing ideas of dataflow analysis
+
+These are not standalone programs. They only demonstrate the minimal code necessary
+to use a feature of DataflowAPI.
+
+---
+
+## Liveness
+
+Query for live registers.
+
+## Slicing
+
+Perform a backward slice on an indirect jump instruction to determine the instructions that affect the
+calculation of the jump target.
+
+## Stack Analysis
+
+Use stack analysis to print out all defined stack heights at the first instruction in a block.
+
+## Symbolic Evaluation
+
+Expand a slice to ASTs and analyze them.
diff --git a/disassemble/README.md b/disassemble/README.md
@@ -0,0 +1,13 @@
+# Disassembly
+
+## Use InstructionAPI to generate textual representations of instructions
+
+---
+
+## Function Disassembly
+
+Uses InstructionAPI to disassemble the basic blocks in a function.
+
+## Unknown Instructions
+
+Implement a custom handler for instructions not known to Dyninst.
diff --git a/dyninstAPI/README.md b/dyninstAPI/README.md
@@ -0,0 +1,10 @@
+# Dyninst API
+
+## A toolkit for instrumentation
+
+---
+
+## Wrap Function
+
+Wrapping malloc with fastMalloc while allowing functions to still access the original
+malloc function by calling origMalloc.
diff --git a/insertSnippet/README.md b/insertSnippet/README.md
@@ -0,0 +1,10 @@
+# Snippets
+
+## Insert arbitrary code into a binary
+
+---
+
+## No-op Snippet
+
+Insert a sequence of x86 nop instructions into the beginning of every function in a binary.
+This creates a "nop slide" that is sometimes seen in adversarial binaries.
diff --git a/instructionAPI/README.md b/instructionAPI/README.md
@@ -0,0 +1,13 @@
+# InstructionAPI
+
+## Small code snippets showing ideas of instruction parsing and analysis
+
+---
+
+## Stateless Visitor
+
+Prints out the name of each type of AST visited.
+
+## Stateful Visitor
+
+Tracks the most-recently seen type of AST.
diff --git a/instrumentAFunction/README.md b/instrumentAFunction/README.md
@@ -0,0 +1,9 @@
+# Instrument a Function
+
+## Write code into a function
+
+---
+
+This example demonstrates instrumentation by inserting a variable to count the
+number of times a function is called. This is similar to how a non-sampling code
+coverage tool might work.
diff --git a/instrumentMemoryAccess/README.md b/instrumentMemoryAccess/README.md
@@ -0,0 +1,13 @@
+# Instrument Memory Access
+
+## A tool for counting the number of times a load or store is performed
+
+This is similar to Memory Access Counter, but
+**all** functions in the binary are instrumented here.
+
+This example illustrates how to use Dyninst to iterate over a
+function’s control flow graph and inspect instructions. These are steps
+that would usually be part of a larger data flow or control flow
+analysis. Specifically, this example collects every basic block in a
+function, iterates over them, and counts the number of instructions that
+access memory.
diff --git a/interceptOutput/README.md b/interceptOutput/README.md
@@ -0,0 +1,9 @@
+# Intercept Stream Output
+
+Add code to a running program to save all data the program writes to its
+standard output file descriptor. In this way it
+works like "tee," which passes output along to its own standard out
+while also saving it in a file. The motivation for the example program
+is that you run a program, and it starts to print copious lines of
+output to your screen, and you wish to save that output in a file
+without having to re-run the program.
diff --git a/maxMallocSize/README.md b/maxMallocSize/README.md
@@ -0,0 +1,4 @@
+# Maximum Malloc Size
+
+Instruments the C standard library `malloc` to find the largest requested allocation
+in a program.
diff --git a/memoryAccessCounter/README.md b/memoryAccessCounter/README.md
@@ -0,0 +1,13 @@
+# Memory Access Counter
+
+## A tool for counting the number of times a load or store is performed
+
+This example is similar to Instrument Memory Access, but only one function
+is instrumented here.
+
+This example illustrates how to use Dyninst to iterate over a
+function’s control flow graph and inspect instructions. These are steps
+that would usually be part of a larger data flow or control flow
+analysis. Specifically, this example collects every basic block in a
+function, iterates over them, and counts the number of instructions that
+access memory.
diff --git a/parseAPI/README.md b/parseAPI/README.md
@@ -0,0 +1,16 @@
+# ParseAPI
+
+## Small code snippets showing ideas of binary parsing
+
+These are not standalone programs. They only demonstrate the minimal code necessary
+to use a feature of ParseAPI.
+
+---
+
+## Edge Predicate
+
+Traverse all of the basic blocks within a function.
+
+## Loop Analysis
+
+Get loop information using ParseAPI's Function object.
diff --git a/patchAPI/README.md b/patchAPI/README.md
@@ -0,0 +1,44 @@
+# PatchAPI
+
+## Demonstrations of using the ParseAPI toolkit
+
+---
+
+## Address Space
+
+An address space plugin to manage memory.
+
+## CFG Maker
+
+A custom function CFG generator to trace when a function is parsed.
+
+## CFG Traversal
+
+Traverses the control flow graph (CFG) of a binary, printing the names of the functions
+and addresses of the basic blocks encountered.
+
+## Finding Points
+
+Find the entry points for every function.
+
+## Nop Patching
+
+Similar to Insert Snippet, insert a sequence of x86 nop instructions into the beginning of every function in a binary.
+This creates a "nop slide" that is sometimes seen in adversarial binaries.
+
+## Patch Modification
+
+PatchAPI provides binary modification with the `PatchModifier` class
+to manipulate the CFG. The three key benefits of the PatchAPI modification interface are
+abstraction, safety, and interactivity. We use the CFG as a mechanism
+for transforming binaries in a platform-independent way that requires no
+instruction-level knowledge by the user. These transformations are
+limited to ensure that the CFG can always be used to instantiate code,
+and thus the user can avoid unintended side-effects of modification.
+Finally, modifications to the CFG are represented in that CFG, allowing
+users to iteratively combine multiple CFG transformations to achieve
+their goals.
+
+## Point Creation
+
+A custom point generator to trace when an instrumentation point is created.
diff --git a/proccontrol/README.md b/proccontrol/README.md
@@ -0,0 +1,9 @@
+# ProcControlAPI
+
+## Small code snippets showing ideas of controlling processes and threads
+
+---
+
+# Callback
+
+Inserts a user-defined callback to be invoked when a thread is created by Proccontrol.
diff --git a/readGlobalVariables/README.md b/readGlobalVariables/README.md
@@ -0,0 +1,3 @@
+# Global Variables
+
+Reads all global variables from the library created with 'globals.cpp'.
diff --git a/stackwalker/README.md b/stackwalker/README.md
@@ -0,0 +1,21 @@
+# Stackwalker
+
+## Small code snippets showing ideas of stack analysis
+
+---
+
+## Simple 3rd-party Walk
+
+Collect a complete view of the process' stack every five seconds.
+
+## Complex 3rd-party Walk
+
+Like Simple 3rd-party walk, but carefully checks for debug events.
+
+## This Thread
+
+Walk and print the call stack of the currently-running thread.
+
+## Determine Walker Party
+
+How to determine if first-party or third-party walker.
diff --git a/symbolicEvalInstructions/README.md b/symbolicEvalInstructions/README.md
@@ -0,0 +1,3 @@
+# Symbolic Evaluation
+
+Symbolic evaluation of all instructions in a binary.
diff --git a/symtabAPI/README.md b/symtabAPI/README.md
@@ -0,0 +1,25 @@
+# SymtabAPI
+
+## Small code snippets showing ideas of symbols
+
+---
+
+## Add Symbol
+
+Add a new variable to a binary.
+
+## Add Type
+
+Add a user-defined type to a binary.
+
+## Print Line Info
+
+Line number information for source files used to create a binary can be queried.
+
+## Print Local Variables
+
+Local variables from within the entire object file or just within a function can be looked up.
+
+## Print Symbols
+
+Symbols can be looked up using a specific type and name as well as by regular expression.
diff --git a/unstrip/README.md b/unstrip/README.md
@@ -1,12 +1,9 @@
-This directory contains unstrip, a library fingerprinting tool built with
-parseAPI and symtabAPI. The tool identifies library wrapper functions in an
-input binary and outputs a new binary with meaningful names assigned to these
-functions.
-
-The provided Makefile can be used to build unstrip. The DYNINST_ROOT
-environment variable should be set to the directory where Dyninst was
-built/installed. This directory should include an include directory with the
-Dyninst header files and a lib directory with the library files. 
+# unstrip
+
+## A library fingerprinting tool
+
+The tool identifies library wrapper functions in an input binary and outputs
+a new binary with meaningful names assigned to these functions.
 
 To see usage information, run unstrip without an arguments.
 
diff --git a/unusedArgs/README.md b/unusedArgs/README.md
@@ -0,0 +1,3 @@
+# Unused Function Arguments
+
+Uses liveness analysis to find the formal parameters that are not used by a function.
