Sign inSign up

binaryanalysisplatform/bap-toolkit

By binaryanalysisplatform

•Updated over 4 years ago

Image
0

10K+

binaryanalysisplatform/bap-toolkit repository overview

⁠Introduction

This repository provides a collection of ready to use binary analysis tools, as well as a framework and a conventional repository structure for developing new tools. Think of it as BAP on Rails. This repository should be seen as a collaboration platform encouraging everyone to fork it, implement an analysis, and share it back with the community. PRs are very welcomed and accepted with no questions asked.

⁠Table of Contents

⁠Installation

The build and installation system is currently querying the opam tool for all the necessary information, therefore make sure that opam 2.x is installed on your system, and a switch is activated, with

    eval $(opam env)

Next, to install all tools in the repository to the default share folder just do

    make
    make install

To install a specific tool, run the same commands but pass the tool name to them, e.g.,

    make TARGET=primus-checks
    make install TARGET=primus-checks

⁠Usage

Tool are packed as BAP recipes, therefore to run a tool just pass its name to the --recipe option, e.g.,

   bap ./exe --recipe=av-rule-3

To get a detailed description of a recipe, use the --show-recipe option, e.g.,

   bap --show-recipe=av-rule-3

You can also list all available using the --list-recipes option,

   bap --list-recipes

⁠Results

The results of the checks from this repository applied to bap-artifacts⁠ can be seen here⁠

⁠Developing

⁠Creating a new tool

To create a new tool clone this repository,

  https://github.com/BinaryAnalysisPlatform/bap-toolkit.git

Then create a new folder inside the newly cloned bap-toolkit folder,

  cd bap-toolkit
  mkdir my-first-tool
  cd my-first-tool

All files in this folder will form the body of your tool. They may contain input files, scripts for pre and post processing, BAP plugins and libraries, etc. The only required file is the recipe.scm file which is the entry point of your tool. This file contains a list of options which are passed to bap, for example, to create a tool that just dumps a file in multiple formats, create a recipe.scm file with the following contents

  (option dump asm:out.asm)
  (option dump bir:out.bir)

After the tool is built and installed⁠, you can run it with

  bap ./test-file --recipe=my-first-tool

And this would essentially the same as running bap with the following command line arguments

  bap ./test-file --dump=asm:out.asm --dump=bir:out.bir

Not a big deal so far, but typical bap invocation may contain lots of command line option. You may also need to pass files, header files, BAP Lisp scripts, etc. This is where the recipe system shines. In general, the recipe specification contains a list of recipe items in an arbitrary order. Each item is either a command line option, a parameter, or a reference to another recipe. All items share the same syntax - they are flat s-expressions, i.e., a whitespace separated list of strings enclosed in parentheses. The first string in the list denotes the type of the item, e.g.,

    (option run-entry-points malloc calloc free)

The option command requires one mandatory parameter, the option name, and an arbitrary number of arguments that will be passed to the corresponding command line option. If there are more than one argument then they will be concatenated with the comman symbol, e.g.,

    (option opt a b c d)

will be translated to

    --opt=a,b,c,d

Option arguments may contain substitution symbols. A subsitution symbol starts with the dollar sign, that is followed by a named (optionally delimited with curly braces, to disambiguate it from the rest of the argument). There is one built in parameter prefix, that is substituted with the path to the recipe top folder.

The parameter command introduces a parameter to the recipe, i.e., a variable ingredient that could be changed when the recipe is used. The parameter command has 3 arguments, all required. The first argument is the parameter name, the second is the default value, that is used if the parameter wasn't set, and the last argument is the parameter description. The substitution symbol will be replaced with the default value of a parameter, if a value of the parameter wasn't passed through the command line. Example,

(parameter depth 128 "maximum depth of analysis")
(option analysis-depth $depth)

If the parameter is not set through the command line, then it will be substituted with 128 otherwise it will receive whatever value a user has passed.

Finally, the extend command is like the #include statement in the C preprocessor as it includes all the ingredients from another recipe. (Make sure that you're not introducing loops!). The command has one mandatory argument, the name of the recipe to include.

⁠The recipe file grammar

The grammar is specified below, but for the details and up-to-date information, please refer to bap recipe --help

       recipe ::= {<recipe-item>}
       recipe-item ::= <option> | <parameter> | <extend> | <command>
       option ::= (option <atom> {<atom>})
       parameter ::= (parameter <atom> <atom> <atom>)
       extend ::= (extend <atom>)
       command ::= (command <atom>)

Tag summary

Content type

Image

Digest

Size

274.9 MB

Last updated

over 4 years ago

docker pull binaryanalysisplatform/bap-toolkit