pyroclastic 3.1.4__py3-none-any.whl

pyroclastic-3.1.4.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: pyroclastic
+Version: 3.1.4
+Summary: Python Interface for LAVA
+Author-email: Andrew Quijano <andrew.quijano@nyu.edu>
+License-Expression: GPL-2.0-only
+Project-URL: Homepage, https://github.com/panda-re/lava
+Project-URL: Source, https://github.com/panda-re/lava
+Project-URL: Tracker, https://github.com/panda-re/lava/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dotenv
+Requires-Dist: colorama
+Requires-Dist: db
+Requires-Dist: ipython
+Requires-Dist: lockfile
+Requires-Dist: numpy
+Requires-Dist: pandare==1.8.78
+Requires-Dist: PyYAML
+Requires-Dist: SQLAlchemy
+Requires-Dist: tabulate
+Requires-Dist: psycopg2-binary
+Requires-Dist: ijson
+Dynamic: license-file
+
+# LAVA: Large Scale Automated Vulnerability Addition
+
+[![Publish Lava Package and Container](https://github.com/panda-re/lava/actions/workflows/publish_docker.yml/badge.svg)](https://github.com/panda-re/lava/actions/workflows/publish_docker.yml)
+
+[![Lava Tests](https://github.com/panda-re/lava/actions/workflows/parallel_tests.yml/badge.svg)](https://github.com/panda-re/lava/actions/workflows/parallel_tests.yml)
+
+Evaluating and improving bug-finding tools is currently difficult due to
+a shortage of ground truth corpora (i.e., software that has known bugs
+with triggering inputs). LAVA attempts to solve this problem by
+automatically injecting bugs into software. Every LAVA bug is
+accompanied by an input that triggers it whereas normal inputs are
+extremely unlikely to do so. These vulnerabilities are synthetic but, we
+argue, still realistic, in the sense that they are embedded deep within
+programs and are triggered by real inputs. Our work forms the basis of
+an approach for generating large ground-truth vulnerability corpora on
+demand, enabling rigorous tool evaluation and providing a high-quality
+target for tool developers.
+
+LAVA is the product of a collaboration between MIT Lincoln Laboratory,
+NYU, and Northeastern University.
+
+# Quick Start
+
+## Docker
+The latest version of LAVA's `master` branch is automatically built as a docker images based on Ubuntu 22.04 and published to [Docker Hub](https://hub.docker.com/r/pandare/lava). Most users will want to use the `lava` container which has PANDA and LAVA installed along with their runtime dependencies, but no build artifacts or source code to reduce the size of the container.
+
+To use the `lava` container you can pull it from Docker Hub:
+```
+$ docker pull pandare/lava
+```
+Or build from this repository:
+```
+$ DOCKER_BUILDKIT=1 docker build lava .
+```
+
+## Ubuntu, Debian
+On a system running Ubuntu 22.04, you should be able to just run `bash install.sh`. Note that this [install script](./install.sh) will install packages and make changes to your system.
+
+## Final steps
+
+### Utilizing host.json
+Next, run `init-host.py` to generate a `host.json`.
+This file is used by LAVA to store settings specific
+to your machine. You can edit these settings as necessary, but the default
+values should work, see [vars.sh](scripts/vars.sh).
+
+A few values to keep in mind are the following:
+* **buildhost** This is the location of where LAVA is being executed from. Currently, it defaults to `localhost`
+* **docker** is the name of the docker image to use that has the LAVA binaries. Currently it defaults to `lava32`, but you can switch this to `pandare/lava`
+* **pguser** This is the name of database user, currently defaults to `postgres`
+* **pgpass** This is the password of the database user, currently defaults to `postgrespostgres`
+* **host** is the name of the Postgres SQL database with all the LAVA bugs. Currently it defaults to `database`, although if you installed LAVA locally, you likely should change this to `localhost`
+
+### Project configurations
+Project configurations are located in the `target_configs` directory, where
+every configuration is located at `target_configs/projectname/projectname.json`.
+Paths specified within these configuration files are relative to values set
+in your `host.json` file.
+
+### Setting up postgres SQL database
+As alluded to, you should create a Postgres SQL user. You can use a script to [use default credentials](scripts/setup_postgres.sh) for the following:
+* Create the user with default password
+* Update Postgres SQL database on host to accept traffic from external sources (e. g. LAVA Docker container)
+* Switch password encryption to md5 (Do we need this?)
+
+# Usage
+
+Finally, you can run `./scripts/lava.sh` to actually inject bugs into a program. Just provide the name of a project that is in the `target_configs` directory, for example:
+
+```
+./scripts/lava.sh toy
+```
+
+You should now have a buggy copy of toy!
+
+If you want to inject bugs into a new target, you will likely need to make some
+modifications. Check out [How-to-Lava](docs/how-to-lava.md) for guidance.
+
+# Documentation
+Check out the [docs](docs/) folder to get started.
+
+
+# Current Status
+## Version 2.0.0
+
+Expected results from test suite:
+```
+Project       RESET    CLEAN    ADD      MAKE     TAINT    INJECT   COMP
+blecho        PASS     PASS     PASS     PASS     PASS     PASS     PASS
+libyaml       PASS     PASS     PASS     PASS     PASS     PASS     PASS
+file          PASS     PASS     PASS     PASS     PASS     PASS     PASS
+toy           PASS     PASS     PASS     PASS     PASS     PASS     PASS
+pcre2         PASS     PASS     PASS     PASS     PASS     PASS     PASS
+jq            PASS     PASS     PASS     PASS     PASS     PASS     PASS
+grep          PASS     PASS     PASS     PASS     PASS     FAIL
+libjpeg       PASS     PASS     PASS     PASS     FAIL
+tinyexpr      PASS     PASS     PASS     PASS     FAIL
+duktape       PASS     PASS     PASS     FAIL
+tweetNaCl     PASS     PASS     FAIL
+gzip          FAIL
+```
+
+# Authors
+
+LAVA is the result of several years of development by many people; a
+partial (alphabetical) list of contributors is below:
+
+* Andy Davis
+* Brendan Dolan-Gavitt
+* Andrew Fasano
+* Zhenghao Hu
+* Patrick Hulin
+* Amy Jiang
+* Engin Kirda
+* Tim Leek
+* Andrea Mambretti
+* Andrew Quijano
+* Wil Robertson
+* Aaron Sedlacek
+* Rahul Sridhar
+* Frederick Ulrich
+* Ryan Whelan

pyroclastic-3.1.4.dist-info/RECORD

@@ -0,0 +1,29 @@
+pyroclastic-3.1.4.dist-info/licenses/LICENSE,sha256=6wat89yFXtw45OVk6X18KOl3VfZa2HuertwM-pczDM4,773
+scripts/add_queries.sh,sha256=agMzIbTCOOXrVIwHjvqJFdgQeJrUDBPFaSiS9Dvxh0c,7707
+scripts/arg_parse.sh,sha256=AeLnwKPay71p9CYWOl8cITWR70udBjXPEC_HnVq50GA,6313
+scripts/bug_mining.py,sha256=7lRo4MbSPkX9259DQs_1jYZRPD7xchxpDSOl6-l38dc,7205
+scripts/database_types.py,sha256=rzf_6-jdzFcE1d7kRukXzQ25CwAV0ccZ99KSOyqB8X8,26994
+scripts/docker-shell.sh,sha256=qWWV8rE35lp3JZQOXlYizwzA490hMLtIHN177b0J7N8,1966
+scripts/find_bug_injection.py,sha256=fkumA6omN5bX3E1nfWLTRmuPP_iK-rOF1x9UfZKZYq8,37980
+scripts/fninstr.py,sha256=HVJK-s5d_miRZ14FBJZm3Hy4MQayMCIzar_aB8CNN_U,9730
+scripts/funcs.sh,sha256=tJ3afatYss3JNjQ6NkFt-JkjdEUmDZXfJXqa9iLMlFI,3320
+scripts/generate_schema.py,sha256=tNtLHe9rU9oVI-cE6reoAq1TnLALgEm346fa-lrwRtc,16731
+scripts/get_c_files.py,sha256=RASd8RxdVT-IaqqCaDSosgkabrdCRuTBrpyD9wfJJtI,1792
+scripts/inject.py,sha256=6R0JzkYlaQCIrhZvA3l9J_UIt6n3bAGOsOutyy4Fjq8,8040
+scripts/lava.py,sha256=BZQ0H08rpiI60zf4JHb1stQw860_zpowO9ygmOnRTfI,35270
+scripts/lava.sh,sha256=31yIKF4AC6C_ecXZuBLZ4866_coMWJeqJXmdcqDkNs4,8765
+scripts/lava.sql,sha256=UkZw_GoJPJdsT9NPPKtaYxaxqAtEnGpUbEhTkJ6kujM,5966
+scripts/preprocess.py,sha256=KZejoxkMqGOWbeJC3Xy_YkM7nmyUE9l-ByMt9oOV5uI,6992
+scripts/process_compile_commands.py,sha256=I8dh1yorLyuPzKgzOiadNB-_HqX1Z-FeiTwAQfLTP5M,1312
+scripts/reset_db.sh,sha256=88zw5fBJsGFXqKMUs-gl2c-ERYlhk4jmmZdbDNxIyHw,1046
+scripts/setup_postgres.sh,sha256=C6002AQqPCmT0iVYRSOH1l6WZnUsdmp3SGOWyu0swNk,1436
+scripts/shell.sh,sha256=5r-3zTssC4-GOIPYmSxdWPT4gyAf-QfUaBt_jSK_Dp8,1297
+scripts/sw-btrace,sha256=CyLyA_kTgLqV3Y-nyWN1EzgmMniaeBEp_FGUxClJsTQ,1493
+scripts/sw-btrace-to-compiledb,sha256=-u6-7PDAbGlFOL5CyJd1IwT3Mtumv_iYelb4X-KVitE,5121
+scripts/test_crash.py,sha256=or2BPwXaSv8EGNDi0TE2tfF8HXckpHBk60P-tR6zlsQ,2221
+scripts/vars.py,sha256=qWCIT-xKBUmrda-eM3EHkjLBLa3CErce-LxI7lREFr4,4581
+scripts/vars.sh,sha256=7sm2l2iZDOsGJddxaRwAQidMB2BpYSqc3I2kO3Tlhxo,3024
+pyroclastic-3.1.4.dist-info/METADATA,sha256=vXs5Km6672cMi2OfleNsDpg4Bz_TiMdzM_LR5gfJUIA,6553
+pyroclastic-3.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyroclastic-3.1.4.dist-info/top_level.txt,sha256=rmzd5mewlrJy4sT608KPib7sM7edoY75AeqJeY3SPB4,8
+pyroclastic-3.1.4.dist-info/RECORD,,

pyroclastic-3.1.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyroclastic-3.1.4.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+SPDX-License-Identifier: GPL-2.0
+
+Copyright (C) 2016, MASSACHUSETTS INSTITUTE OF TECHNOLOGY
+
+This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

pyroclastic-3.1.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+scripts

scripts/add_queries.sh

@@ -0,0 +1,231 @@
+#!/bin/bash
+# Query insertion script.
+#
+# Takes one argument, the project name
+# That json file must contain all of the following
+#
+# name         name for project, usually the name of the software (binutils-2.25, openssh-2.1, etc)
+# directory    directory in which src-2-src query injection will occur -- should be somewhere on the nas
+# tarfile      path to software tar file
+# configure    how to configure the software (./configure plus arguments) (will just use /bin/true if not present)
+# make         how to make the software (make might have args or might have FOO=bar required precursors)
+# install      how to install the software (note that configure will be run with --prefix ...lava-install)
+#
+# script proceeds to untar the software, run btrace on it to extract a compile_commands.json file,
+# which contains all information needed to compile every file in the project.
+# then, the script runs lavaTool using that compile_commands.json file, on every source file,
+# adding extra source code to perform taint queries.  At the time of this writing, the taint
+# queries were for every argument of every fn call, injected both before and after the call.
+# Also, the return value of the fn is queried.  Oh, and lavaTool also injects "queries" that
+# indicate when a potential attack point has been encountered.  At the time of this writing,
+# that includes calls to memcpy and malloc.
+#
+# After lavaTool has transformed this source, it exits.  You should now try to make the project
+# and deal with any complaints (often src-to-src breaks the code a little). Once you have a working
+# version of the compiled exec with queries you will need to log on to a 64-bit machine
+# and run the bug_mining.py script (which uses PANDA to trace taint).
+#
+
+tick
+
+USAGE() {
+    echo "Usage: $1 [ATP_Type] JSONfile"
+}
+
+set -e # Exit on error
+# set -x # Debug mode
+
+if [ $# -lt 1 ]; then
+    USAGE $0
+elif [ $# -lt 2 ]; then
+  echo "No ATP_Type specified.  Defaulting to all."
+  ATP_TYPE=""
+  json="$(readlink -f $1)"
+elif [ $# -eq 2 ]; then
+  ATP_TYPE="-$1"
+  json="$(readlink -f $2)"
+else
+  USAGE $0
+  exit 1
+fi
+
+absolute_path=$(readlink -f "$0")
+scripts_path=$(dirname "$absolute_path")
+lava=$(dirname "$scripts_path")
+project_name="$1"
+
+# Load lava-functions and vars
+source "$scripts_path/funcs.sh"
+source "$scripts_path/vars.sh"
+
+progress "queries" 0  "Entering $directory/$name."
+mkdir -p "$directory/$name"
+cd "$directory/$name"
+
+progress "queries" 0  "Untarring $tarfile..."
+source=$(tar tf "$tarfile" | head -n 1 | cut -d / -f 1)
+
+if [ -e "$source" ]; then
+  progress "queries" 0  "Deleting $directory/$name/$source..."
+  rm -rf "$directory/$name/$source"
+fi
+tar xf "$tarfile"
+
+progress "queries" 0  "Entering $source."
+cd "$source"
+
+progress "queries" 0  "Creating git repo."
+rm -rf .git || true #Remove any existing git repo
+git init
+git config user.name LAVA
+git config user.email "nobody@nowhere"
+git add -A .
+git commit -m 'Unmodified source.'
+
+progress "queries" 0  "Configuring..."
+mkdir -p lava-install
+configure_file=${configure_cmd%% *}
+if [ -e "$configure_file" ]; then
+    CC=$llvm/bin/clang \
+        CXX=$llvm/bin/clang++ \
+        CFLAGS="-O0 -DHAVE_CONFIG_H -g -gdwarf-2 -fno-stack-protector -D_FORTIFY_SOURCE=0 -I. -I.. -I../include -I./src/" \
+        $configure_cmd --prefix=$(pwd)/lava-install
+fi
+
+
+progress "queries" 0  "Making with btrace..."
+# Delete any pre-existing btrace.log (could be in archive by mistake)
+rm -f btrace.log
+ORIGIN_IFS=$IFS
+IFS='&&'
+read -ra MAKES <<< "$makecmd"
+for i in "${MAKES[@]}"; do
+    IFS=' '
+    read -ra ARGS <<< "$i"
+    echo "$scripts_path/sw-btrace ${ARGS[@]}"
+    CC=$llvm/bin/clang \
+        CXX=$llvm/bin/clang++ \
+        CFLAGS="-O0 -DHAVE_CONFIG_H -g -gdwarf-2 -fno-stack-protector -D_FORTIFY_SOURCE=0 -I. -I.. -I../include -I./src/" \
+    "$scripts_path/sw-btrace" "${ARGS[@]}"
+    IFS='&&'
+done
+IFS=$ORIGIN_IFS
+
+
+progress "queries" 0  "Installing..."
+bash -c $install
+
+
+progress "queries" 0  "Creating compile_commands.json..."
+# Delete any pre-existing compile commands.json (could be in archive by mistake)
+rm -f compile_commands.json
+"$scripts_path/sw-btrace-to-compiledb" $llvm/lib/clang/11/include
+if [ -e "$directory/$name/extra_compile_commands.json" ]; then
+    sed -i '$d' compile_commands.json
+    echo "," >> compile_commands.json
+    tail -n +$((2)) "$directory/$name/extra_compile_commands.json" >> compile_commands.json
+fi
+git add compile_commands.json
+git commit -m 'Add compile_commands.json.'
+
+cd ..
+
+# Switching IFS to '\n' to support paths with spaces in them.
+c_files=$($python "$scripts_path/get_c_files.py" "$source")
+IFS=$'\n'
+c_dirs=$(for i in $c_files; do dirname "$i"; done | sort | uniq)
+
+progress "queries" 0  "Copying include files..."
+for i in $c_dirs; do
+  echo "   $i"
+  if [ -d "$i" ]; then
+    cp "$lava"/tools/include/*.h "$i"/
+  fi
+done
+
+# Run another clang tool that provides information about functions,
+# i.e., which have only prototypes, which have bodies.  
+progress "queries" 0 "Figure out functions" 
+for this_c_file in $c_files; do
+    "$lava/tools/install/bin/lavaFnTool" "$this_c_file"
+done
+
+#progress "queries" 0  "Initialize variables..."
+#for i in $c_files; do
+#    /src_clang/build/lavaTool -action=init \
+#    -p="$source/compile_commands.json" \
+#    -src-prefix=$(readlink -f "$source") \
+#    $i
+#done
+
+# TODO: This should probably be just for dataflow
+# but we still need it for non-dataflow targets, otherwise we inject into
+# va_args functions and everything breask
+
+# Analyze that output and figure out
+fnfiles=$(echo $c_files | sed 's/\.c/\.c\.fn/g')
+fninstr=$directory/$name/fninstr
+
+echo "Creating fninstr [$fninstr]"
+echo -e "\twith command: \"python $lava/scripts/fninstr.py -d -o $fninstr $fnfiles\""
+$python "$scripts_path/fninstr.py" -d -o $fninstr $fnfiles
+
+if [[ ! -z "$df_fn_blacklist" ]]; then
+    cmd=$(echo "sed -i /${df_fn_blacklist}/d $fninstr")
+    echo "Removing blacklisted functions with regex: $df_fn_blacklist"
+    $cmd
+fi
+
+if [ "$dataflow" = "true" ]; then
+    # Insert queries with DF - could merge this with the else if logic below instead of duplicating
+    # TODO: Just make lavaTool load dataflow from project.json instead of passing as CLI arg.
+    # Since it's okay to pass the whitelist either way
+    progress "queries" 0  "Inserting queries for dataflow"
+    for i in $c_files; do
+        "$lava/tools/install/bin/lavaTool" -action=query \
+        -lava-db="$directory/$name/lavadb" \
+        -p="$directory/$name/$source/compile_commands.json" \
+        -arg_dataflow \
+        -lava-wl="$fninstr" \
+        -src-prefix=$(readlink -f "$source") \
+        $ATP_TYPE \
+        -db="$db" \
+        $i
+    done
+else
+    progress "queries" 0  "Inserting queries..."
+    # TODO: remove lava-wl here, unless we're using it to limit where we inject
+    for i in $c_files; do
+        "$lava/tools/install/bin/lavaTool" -action=query \
+        -lava-db="$directory/$name/lavadb" \
+        -lava-wl="$fninstr" \
+        -p="$source/compile_commands.json" \
+        -src-prefix=$(readlink -f "$source") \
+        $ATP_TYPE \
+        -db="$db" \
+        $i
+    done
+fi
+
+for i in $c_dirs; do
+    echo "Applying replacements to $i"
+    pushd $i
+    "$llvm/bin/clang-apply-replacements" .
+    popd
+done
+
+# Ensure every c file was modified
+# Alternatively, we could just check that at least one file was modified
+for this_c_file in $c_files; do
+    if ! grep -q "pirate_mark_lava.h" $this_c_file; then
+        echo "FATAL ERROR: LAVA queries missing from source files!"
+        exit 1
+    fi
+done
+unset IFS
+
+progress "queries" 0  "Done inserting queries. Time to make and run actuate.py on a 64-BIT machine!"
+
+tock
+echo "add queries complete $time_diff seconds"
+

scripts/arg_parse.sh

@@ -0,0 +1,183 @@
+#!/bin/sh
+. `dirname $0`/funcs.sh
+digit_re='^[0-9]+$'
+
+function parse_args {
+    echo
+    progress "everything" 0 "Parsing args"
+    if [ "$#" -eq 1 ]; then # With no arguments run everything, else try matching args
+        # If the single argument is a  flag, e.g., --help, handle that instead
+        if ! [[ $1 == *"-"* ]]; then
+            reset=1
+            reset_db=1
+            add_queries=1
+            make=1
+            taint=1
+            inject=1
+            num_trials=3
+            progress "everything" 0 "All steps will be executed"
+            project_name=$1
+            return 0
+        fi
+    fi
+    while :; do
+        case $1 in
+            -h|-\?|--help)
+                USAGE
+                exit
+                ;;
+            -a|--all)
+               reset=1
+               reset_db=1
+               add_queries=1
+               make=1
+               taint=1
+               inject=1
+               num_trials=3
+               progress "everything" 0 "All steps will be executed"
+               ;;
+            -k|--force)
+               ok=1
+               progress "everything" 0 "--force: Forcing through deletes"
+               ;;
+
+           -ak) # Backwards compatability with everyone's favorite lava1 option
+               reset=1
+               reset_db=1
+               add_queries=1
+               make=1
+               taint=1
+               inject=1
+               num_trials=3
+               progress "everything" 0 "All steps will be executed"
+               ok=1
+               progress "everything" 0 "--force: Forcing through deletes"
+               ;;
+
+            # Individual steps
+            -r|--reset)
+               reset=1
+               progress "everything" 0 "Reset step will be executed"
+               ;;
+            -c|--clean)
+               reset_db=1
+               progress "everything" 0 "Reset (clean) just databse step will be executed"
+               ;;
+            -q|--add-queries)
+               add_queries=1
+               progress "everything" 0 "Add queries step will be executed"
+               ;;
+            -m|--make)
+               make=1 # TODO: what does this mean? Make queries?
+               progress "everything" 0 "Make step will be executed"
+               ;;
+            -t|--taint)
+               taint=1
+               progress "everything" 0 "Taint step will be executed"
+               ;;
+
+            # Expert only options- Dev/testing flags that may be broken
+            --demo)
+               demo=1
+               progress "everything" 0 "-d: demo mode"
+               ;;
+            --test-data-flow) # For testing- inject 0 bugs, but add data_flow
+               inject=1
+               many=0
+               num_trials=1
+               progress "everything" 0 "[TESTING] Inject data_flow only, 0 bugs"
+               ;;
+
+            # Arguments that take options
+            -i|--inject)
+                if [ "$2" ]; then
+                    inject=1
+                    num_trials=$2
+                    shift
+                    progress "everything" 0 "Inject step will be executed: num_trials = $num_trials"
+                else
+                    die "ERROR: --inject requires [num_trials], got $@"
+                fi
+               ;;
+            -n|--count)
+                if [ "$2" ]; then
+                    many="$2"
+                    if ! [[ $many =~ $re ]] ; then
+                        die 'ERROR: --many requires numeric argument'
+                    fi
+                    progress "everything" 0 "Number of injected bug at the same time: $many"
+                    shift
+                else
+                    die 'ERROR: --many requires argument'
+                fi
+               ;;
+
+            --enable-knob-trigger)
+                if [ "$2" ]; then
+                    knob=$2
+                    kt="--knobTrigger $knob"
+                    progress "everything" 0 "Inject step will be executed with knob trigger: knob = $knob"
+                    shift
+                else
+                    die "--knobTrigger requires knob argument"
+                fi
+                ;;
+            --curtail)
+                if [ "$2" ] && [[ $2 =~ ^[0-9]+$ ]]; then
+                    curtail="$2"
+                    shift
+                else
+                    # default curtail=1000
+                    curtail=1000
+                fi
+                progress "everything" 0 "Curtailing FBI after $curtail"
+               ;;
+            -y|--bug-types)
+                if [ "$2" ]; then
+                    bugtypes="$2" # TODO: a single arguments must be passed as 'arg1,'
+                    progress "everything" 0 "Injecting bugs of type(s): $bugtypes"
+                    shift
+                else
+                    die 'ERROR: --bug-types requires comma-seperated list of bug types'
+                fi
+               ;;
+            -b|--atp-type )
+                # -b [bugType] : use this to specify attact point type: [mem_write|mem_read|fn_arg]
+                # TODO: should allow combinations of atp types
+                if [ "$2" ]; then
+                    ATP_TYPE="$2"
+                else
+                    die 'ERROR: --atp-types requires a single atp-type'
+                fi
+
+                if [ "$ATP_TYPE" != "mem_read" -a "$ATP_TYPE" != "fn_arg" -a "$ATP_TYPE" != "mem_write" ]; then
+                    echo "ATP Type ($ATP_TYPE) is not valid must specify:"
+                    echo "    --atp-type [mem_write|mem_read|fn_arg]"
+                    echo "Exiting . . ."
+                    exit 1
+                fi
+                progress "everything" 0 "Query step will be executed with bug type: atp = $ATP_TYPE"
+                ;;
+
+            #TODO: enable --inject=1 instead of just --inject 1 with something like:
+            #--file=?*)
+            #    file=${1#*=} # Delete everything up to "=" and assign the remainder.
+            #    ;;
+            --)              # End of all options.
+                shift
+                break
+                ;;
+            -?*)
+                printf 'ERROR: Unknown option: %s\n' "$1" >&2
+                USAGE
+                ;;
+            *)               # Default case: No more options, so break out of the loop.
+                break
+        esac
+
+       shift
+    done
+
+    project_name=$1
+}
+