Skip to content

Latest commit

 

History

History
executable file
·
120 lines (97 loc) · 5.8 KB

Using OpenSAW.md

File metadata and controls

executable file
·
120 lines (97 loc) · 5.8 KB

Using OpenSAW

If you don't have a working OpenSAW environment, please follow the instructions in docs/SETUP.md

Getting Familiar with OpenSAW

In the OpenSAW virtual machine some samples are provided. These are located in /home/vagrant/opensaw_samples.

To run OpenSAW on a trivial program that throws an exception on the input 'bad!' you run

cd ~/opensaw_samples/sage1
make

This compiles the program and launches OpenSAW. OpenSAW will by default create a folder opensaw_dir that contains information about the current execution and temporary files. See opensaw_dir for more information.
The logfile opensaw_dir/opensaw.log is the main source of information for how a opensaw run is progressing.

Another way to check on OpenSAW progress is by using the web-ui. If you are using Vagrant, then port 8080 has already been forwarded to your host machine, and all you need to do is point your browser on the host machine to localhost:8080

Usage

Currently the default concolic execution engine of OpenSAW supports two types of executables.
Executables that take a single input file as argument and executables that read all their input from STDIN. In both these cases the initial input is given as a file to OpenSAW using the -i argument.

The way to run OpenSAW is as a python package, using the -m command line option, like:

python2.7 -m opensaw $executable -i $initial_input --inputType file

Note that the argument to --inputType can either be 'file' or 'stdin'.

All switches can be found by running

python2.7 -m opensaw --help

One of the great features with OpenSAW is that it lets users quickly get their hands dirty and experiment with new bug-finding search strategies. Descriptions of existing search strategies and also instructions on how to write your own can be found in docs/Strategies.md

The opensaw_dir folder

OpenSAW will by default create a folder opensaw_dir that contains information about the current execution and temporary files.

Other files in this folder are identified by their file ending

  • .in These are inputs generated by OpenSAW

After a finished run of OpenSAW opensaw_dir/tracegraph.dot is generated. This is the trace graph that was uncovered during the run. opensaw_dir/statistics.json is also generated, which contains easily parseable statistics about the run.

The opensaw_dir may contain other files temporarily, and files created by the specific concolic execution engine. For example the default pinbap engine will generate files temporarily and permanently with names ending in

  • .il These contain execution traces in readable format
  • .cov These contain block coverage information
  • .log These contain log information from runs of pin.

Development

To get the bleeding-edge version of OpenSAW, re-create a new virtual machine using Vagrant, and within the machine go to /opt/OpenSAW and run

git pull

If you want to do development on your local machine, place the git repository in the same folder as the Vagrantfile. Then (on the virtual machine) remove the /opt/OpenSAW folder and symlink the repository there using

ln -s /vagrant/OpenSAW /opt/OpenSAW

FAQ

OpenSAW is using too much memory.

By default OpenSAW passes traces that are to be analyzed for new inputs in memory. These traces are built by parsing trace files and finding nodes in the tracegraph. You can use the flag --reanalyzeTraces to make OpenSAW discard traces before putting them on the queue and rebuilding them from the trace file before they are to be analyzed.

For large applications you may need to limit the time a single execution of the application is allowed to run. This is because long executions lead to large trace files which are loaded into memory by OpenSAW. Limiting execution time can be done with the --tracerTimeout flag, which sets a CPU Timelimit using RLIMIT_CPU. When using --tracerTimeout, be sure to also use --ignoreSignal SIGXCPU as OpenSAW will consider timeouts to be exceptions otherwise.

OpenSAW is using too much storage.

By default OpenSAW has stores an unlimited number of traces. As traces may be big, this might fill your storage. You can use --maxTraceQueue <nr> to limit the number of traces that OpenSAW has stored, this will make the tracer thread pause if there are too many unanalyzed traces. We suggest you use --discardOverflow to allow the tracer thread to continue, but throw away traces with the least priority if the trace queue is too big.

PIN and BAP are used extensively in variable and function names, what do they mean?

These names are a legacy from the time when OpenSAW was bound to a single concolic execution engine. PIN was the execution tracer and BAP was the symbolic executor that generated new program inputs.