Bunkerbuster release.

This update allows ARCUS to explore nearby paths not covered in the processor trace, snapshot APIs, and more.

Author: carter-yagemann

README.md

@@ -65,15 +65,24 @@ The general setup steps are:
 
 * [ARCUS Paper Evaluation](https://super.gtisc.gatech.edu/arcus-dataset-public.tgz)
 
+* [Bunkerbuster Paper Evaluation](https://super.gtisc.gatech.edu/bunkerbuster-dataset-public.tgz)
+
 ## Unit Tests
 
 If you make contributions to the repository, please try to keep `tools/angr/test/test.py` up-to-date. For non-unit tests,
 create a new script in `tools/angr/test`. We currently do not have a unified framework for non-unit tests.
 
 ## Publications
 
-* C. Yagemann, M. Pruett, S. P. Chung, K. Bittick, B. Saltaformaggio, W. Lee, *ARCUS: Symbolic Root Cause Analysis of Exploits
-in Production Systems.* To appear in the 30th USENIX Security Symposium (USENIX'21). August 11--13, 2021.
+* C. Yagemann, S. Chung, B. Saltaformaggio, W. Lee,
+*Automated Bug Hunting With Data-Driven Symbolic Root Cause Analysis.*
+Appeared in the 2021 ACM Conference on Computer and Communications Security (CCS’21).
+Seoul, Republic of Korea. November 15--19, 2021.
+
+* C. Yagemann, M. Pruett, S. P. Chung, K. Bittick, B. Saltaformaggio, W. Lee,
+*ARCUS: Symbolic Root Cause Analysis of Exploits in Production Systems.*
+Appeared in the 30th USENIX Security Symposium (USENIX'21).
+August 11--13, 2021.
 
 ## Related Work
 

docs/arcus.md

@@ -18,6 +18,38 @@ Upon detecting a vulnerability, the analysis will attempt to look backwards to f
 introducing the problem along with a root cause for the misbehavior. Currently, this will appear as part
 of the logging output.
 
+## Exploration
+
+With the release of exploration plugins (codename: Bunkerbuster), ARCUS can now explore nearby paths to
+find more bugs. Simply add the `--explore` flag to `analysis.py`.
+
+**Note:** Exploration is significantly slower and more memory expensive than simply following the trace.
+
+The "Explore Options" section in `analysis.py --help` contains additional advanced settings. For example,
+you can configure the analysis to switch to exploration after a timeout, regardless of whether the end
+of the trace has been reached. You can also use a Redis database to record which paths were explored so
+other analysis sessions won't re-explore the same stuff.
+
+## Snapshots
+
+Also new in the Bunkerbuster release is the ability for Tracer to break traces down into snapshots. This
+is useful for programs that are too big to analyze symbolically from start to finish. Passing `tracer.py`
+the flag `--snapshot-api` will cause it to snapshot invocations of imported functions. If you really know
+what you're doing, you can use `--snapshot-rva` to give a virtual address (relative to the main object's
+base address) to snapshot.
+
+**Note:** When using `--snapshot-rva`, results may be unstable if the address is not the start of a function.
+
+For each snapshot, the analysis will attempt to symbolize its parameters, using either a prototype definition
+(if one is available in `tools/angr/plugins/prototypes`) or by analyzing the memory accesses from the trace.
+
+**Note:** This is an under-constrained symbolic analysis, so bugs found under these conditions may not be
+reachable in real executions. However, since snapshots are taken at API entry points, bugs found this way
+are typically of relevance to the API's developers.
+
+It is possible to generate more prototypes for the `tools/angr/plugins/prototypes` directory using C/C++
+headers. See `tools/prototype-parser/parse_function.py --help` for more details.
+
 # Development
 
 This section is for developers who want to contribute to the project.
@@ -34,9 +66,16 @@ types of vulnerabilities, keep tracing on track, etc. The recommended steps for
 
 ## Plugins
 
-The analysis uses a plugin system to make extending easy. There are currently two kinds of plugins: **hooks** and
-**detectors**. Hooks provide angr `SimProcedure` classes to speed up analysis. Detectors scan each state for
-vulnerabilities and then analyze detections at the end.
+The analysis uses a plugin system to make extending easy. There are currently four kinds of plugins: **hooks**,
+**detectors**, **explorers**, and **prototypes**:
+
+* Hooks provide angr `SimProcedure` classes to speed up analysis.
+
+* Detectors scan each state for vulnerabilities and then analyze detections at the end.
+
+* Explorers guide the analysis down interesting nearby paths.
+
+* Prototypes define the parameters to functions captured as snapshots.
 
 Adding plugins is as simple as creating a Python file to the appropriate directory. The `__init__.py` script in
 each plugin directory will automatically handle loading and validating the plugins. You should not need to modify

docs/misc-tools.md

@@ -5,8 +5,33 @@ Here's a list of other tools provided and their purpose:
 * `tools/angr/memlayout.py` - Takes a trace and prints the memory layout.
 * `tools/angr/decode.py` - Decodes a GRIFFIN trace (usually named `trace.griffin`) and prints out the sequence
 of executed basic blocks along with some other details.
+* `tools/angr/rewriter.py` - Instruments program to record run-time data in PT trace. Explained in more detail
+in a following subsection.
 * `tools/pt/cmppath` - Compares traces using hashmaps and checksums.
 
+## Instrumenting Programs
+
+Processor traces usually only record control flow, so for analysis that requires data flow, the program has to be rewritten
+to encode the data of interest. This can be done with `tools/angr/rewriter.py`. See `-h` for more details.
+
+The JSON file provided to this tool is used to specify where to place hooks and what to record at those
+places. For example, to capture the contents of the `rax` register at the code located at relative virtual
+address `0x839`:
+
+```
+{"hooks": [
+    {"addr": 2105, "src": "rax"}
+]}
+```
+
+And if we want to record the value at a memory location instead:
+
+```
+{"hooks": [
+    {"addr": 2105, "src": 123456}
+]}
+```
+
 ## Comparing Traces
 
 The tool `cmppath` uses hashmaps and checksums to compare traces. Setup is as easy as:

docs/scaling-arcus.md

@@ -31,4 +31,4 @@ you may want to use `tools/pt/cmppath` to filter out similar traces.
     ./run.sh /path/to/traces-dir master
 
     # pass additional arguments to analysis.py
-    ./run.sh /path/to/traces-dir master --logging=40
+    ./run.sh /path/to/traces-dir master --explore --logging=40

tools/angr/analysis.py

@@ -37,11 +37,13 @@
 import agc
 import angrpt
 import dwarf
+import explore
 from globals_deep import SimStateDeepGlobals
 import griffin
 import hooks
 import plugins.detectors
 import plugins.hooks
+import plugins.explorers
 import reporting
 import taint
 import xed
@@ -108,6 +110,20 @@ def parse_args():
             help='Save reports as JSON files to provided directory')
     parser.add_option_group(group_analysis)
 
+    group_explore = OptionGroup(parser, 'Explore Options')
+    group_explore.add_option('--explore', action='store_true', default=False,
+            help='Explore paths near the traced path for additional bugs')
+    group_explore.add_option('--explore-after', action='store', type='str', default=None,
+            help='Explore after given time, even if end of trace has not been reached '
+                 '(supports suffixes: s/m/h, defaults to m)')
+    group_explore.add_option('--explore-db', action='store', default=None,
+            help='Use database so explorers can share data across sessions (supported: '
+                 'Redis - redis://111.222.333.444:6379/0)')
+    group_explore.add_option('--explore-plugins', action='store', type='str', default=None,
+            help='Comma seperated list of explorer plugins to use, by module name '
+                 '(example: "arg_max,loop_bounds")')
+    parser.add_option_group(group_explore)
+
     group_logging = OptionGroup(parser, 'Logging Options')
     group_logging.add_option('-l', '--logging', action='store', type='int', default=20,
             help='Log level [10-50] (default: 20 - Info)')
@@ -572,6 +588,10 @@ def set_log_levels(options):
     for module in list(plugins.detectors.loaded.values()):
         logging.getLogger(module.__name__).setLevel(options.logging)
 
+    # explorer plugins
+    for module in list(plugins.explorers.loaded.values()):
+        logging.getLogger(module.__name__).setLevel(options.logging)
+
 def get_predecessor(tech, index):
     """Helper function to get predecessors by index, ignoring None elements.
 
@@ -848,6 +868,19 @@ def main():
 
     set_log_levels(options)
 
+    # input validation
+    if options.explore_after:
+        if not options.explore:
+            options.explore = True  # user clearly intends to explore
+        explore_delta = parse_timedelta(options.explore_after, default_suffix='m')
+        if explore_delta is None:
+            log.error("Invalid value for --explore-after: %s" % options.explore_after)
+            return
+        if explore_delta < 1:
+            log.error("Value for --explore-after must be positive: %d" % explore_delta)
+            return
+        options.explore_after = explore_delta
+
     trace_dir = args[0]
     input_trace_candidates = ['trace.griffin', 'trace.griffin.gz']
     input_trace = None
@@ -955,7 +988,7 @@ def main():
 
     # initialize the starting state, exploration technique and simulation manager
     tech = angrpt.Tracer(bb_seq, start_address=regs['rip'])
-    init_state, init_env = parse_entry_state_json(proj, trace_dir, snapshot_dir, False,
+    init_state, init_env = parse_entry_state_json(proj, trace_dir, snapshot_dir, options.explore,
                                                   options.override_max_argv)
     simgr = proj.factory.simgr(init_state)
 
@@ -1062,13 +1095,19 @@ def main():
                 raise CriticalMemoryException('Memory critically low')
 
             analysis_duration = (datetime.now() - analysis_start_time).total_seconds()
+            if options.explore_after and analysis_duration > options.explore_after:
+                log.warning("Analysis timeout reached, moving to exploration early")
+                break
 
     except KeyboardInterrupt:
         log.warning("Received interrupt, cleaning up...")
+        options.explore = False  # forcibly disable exploration
     except (CriticalMemoryException, MemoryError):
         log.error("Memory critically low, halting analysis")
+        options.explore = False
     except AssertionError:
         log.error("Failed assertion: %s" % format_exc())
+        options.explore = False
     except angr.errors.AngrTracerError as ex:
         log.error("Angr stopped early: %s" % str(ex))
 
@@ -1086,17 +1125,112 @@ def main():
                 log.error("Stopped here: (symbolic)")
     except KeyboardInterrupt:
         log.warning("Received interrupt, cleaning up...")
+        options.explore = False  # forcibly disable exploration
 
     # update reports
     log.info("Updating reports with root cause analysis")
     try:
         reports = analyze(simgr, bb_seq)
     except KeyboardInterrupt:
         log.warning("Received interrupt, cleaning up...")
+        options.explore = False  # forcibly disable exploration
+
+    ################################################
+    ### PHASE 2: Optionally Explore Nearby Paths ###
+    ################################################
+
+    try:
+        if options.explore:
+            log.info("Starting explorers")
+            # backup list of predecessors for original trace
+            orig_preds = simgr._techniques[0].predecessors.copy()
+            # we no longer need the tracer exploration technique
+            simgr.remove_technique(tech)
+            assert len(simgr._techniques) == 0
+
+            # filter for if user wants us to only use a subset of plugins
+            allowed_explorers = None
+            if options.explore_plugins:
+                allowed_explorers = options.explore_plugins.split(',')
+
+            for explorer in list(plugins.explorers.loaded.values()):
+                e_short_name = explorer.__name__.split('.')[-1]
+                if not (allowed_explorers is None or e_short_name in allowed_explorers):
+                    log.info("Skipping explorer %s at user's request" % e_short_name)
+                    continue
 
+                log.debug("Invoking explorer: %s" % e_short_name)
+
+                # reactivate detectors because this is a new exploration
+                for detector in list(plugins.detectors.loaded.values()):
+                    detector.active = True
+
+                try:
+                    explorer_tech = explorer.explorer(orig_preds, bb_seq, options)
+                    simgr.use_technique(explorer_tech)
+                except KeyboardInterrupt:
+                    # let the outer try-except catch these
+                    raise ex
+                except:
+                    log.error("Uncaught exception while trying to setup explorer: %s" % format_exc())
+                    buggy_plugins.add(explorer.__name__)
+                    continue
+
+                mem_mgr.enable()
+                # step until explorer is complete
+                while not simgr.complete():
+                    try:
+                        simgr.step()
+                    except (KeyboardInterrupt, CriticalMemoryException, MemoryError) as ex:
+                        # let the outer try-except catch these
+                        raise ex
+                    except ReferenceError:
+                        # something is wrong with the active state, drop it, all explorers are
+                        # designed to react robustly to an empty active stash
+                        simgr.drop(stash='active')
+                    except:
+                        log.error("Uncaught exception raised by explorer plugin: %s" % format_exc())
+                        log.error("Stopping explorer and moving on")
+                        buggy_plugins.add(explorer.__name__)
+                        break
+
+                    if not hasattr(simgr._techniques[0], 'predecessors'):
+                        log.error("Detectors rely on explorers maintaining predecessors, which is missing, cannot continue")
+                        buggy_plugins.add(explorer.__name__)
+                        break
+
+                    if len(simgr.stashes['active']) > 0:
+                        if len(simgr.stashes['active']) > 1:
+                            log.warn("Explorer created %d active states, most detectors only examine one" % len(simgr.stashes['active']))
+
+                        check_for_vulns(simgr, proj)
+                        # this is a bit excessive, but because we don't know when an explorer is going to rewind
+                        # we have to check for new states to analyze after each step so simgr._techniques[0].predecessors
+                        # remains accurate
+                        analyze(simgr, bb_seq, reports)
+
+                    if psutil.virtual_memory().available <= min_memory:
+                        mem_mgr.reap_predecessors()
+                    if psutil.virtual_memory().available <= crit_memory:
+                        raise CriticalMemoryException('Memory critically low')
+
+                # cleanup explorer
+                log.debug("Explorer %s complete" % explorer.__name__)
+                mem_mgr.disable()
+                simgr.remove_technique(explorer_tech)
+                assert len(simgr._techniques) == 0
+
+    except KeyboardInterrupt:
+        log.warning("Received interrupt, cleaning up...")
+        mem_mgr.disable()
+    except (CriticalMemoryException, MemoryError):
+        log.error("Memory critically low, halting analysis")
+        mem_mgr.disable()
+    except AssertionError:
+        log.error("Failed assertion: %s" % format_exc())
 
     ################################
-    ### PHASE 2: Final Reporting ###
+    ### PHASE 3: Final Reporting ###
     ################################
 
     log.info("** Analysis complete, final results **")