plugin.json

{
   "pluginmetadataversion": 2,
   "name": "bncov",
   "author": "Mark Griffin",
   "type": [
      "helper"
   ],
   "api": [
      "python3"
   ],
   "description": "Scriptable code coverage analysis and visualization plugin",
   "longdescription":"# bncov - Scriptable Binary Ninja plugin for coverage analysis and visualization\n\nbncov provides a scriptable interface for bringing together coverage\ninformation with Binary Ninja's static analysis and visualization. Beyond\nvisualization, the abstractions in bncov allow for programmatic reasoning\nabout coverage. It was designed for interactive GUI use as well as for\nfactoring into larger analysis tasks and standalone scripts.\n\n![Demo Overview](https://github.com/ForAllSecure/bncov/raw/master/pictures/bncov_demo.png)\n\nThis plugin is provided as a way to give back to the community,\nand is not part of the Mayhem product.  If you're interested in Mayhem, the\ncombined symbolic execution and fuzzing system, check us out at\n[forallsecure.com](http://forallsecure.com).\n\n## CHANGELOG\nFeb 2023: drcov format version 3 now supported.\nOct 2021: Some changes in the API:\n\n- Added a `ctx` object that is keyed off the Binary View and helpers\n  `bncov.get_ctx` and `bncov.get_covdb` to support multibinary use case in the\n  UI, so now you can interactively use bncov across tabs!\n- Changed old helpers `bncov.get_bv`/`bncov.get_covdb` to\n  `bncov.make_bv`/`bncov.make_covdb` for making a Binary View from a target file\n  and covdb from a binary and a coverage directory, respectively\n- All function-related covdb member functions now default to keying off of\n  function start addresses rather than names since function starts are unique\n  and more usable for many applications. Extra optional args or helper functions\n  implement the existing behavior.\n- Abandoning Python2 suport\n- Added `download_dynamorio.py` for the sloths\n- Minor quality-of-life fixes\n\n## Installation\n\nThe easiest way is to install via the Binary Ninja plugin manager!\nThe only difference when installing via plugin manager is that wherever\nyou see `import bncov`, you may have to do `import ForAllSecure_bncov as bncov`.\n\nAlternatively:\n\n - Clone or copy this directory into your binja plugins folder.\n([More detailed instructions here](https://docs.binary.ninja/guide/plugins/index.html#using-plugins))\n - (Optional) pip install msgpack if you want to enable loading/saving\ncoverage database files.\n\n## Usage\n\nCheck out the [tutorial](/tutorial/) for a complete walkthrough or how to get\nstarted right away using data that's already included in this repo!\n\nFirst collect coverage information in DynamoRIO's drcov format\n([example script](/dr_block_coverage.py)).\n\nTo use in Binary Ninja GUI:\n\n1. Open the target binary, then import coverage files using one of\nthe commands in `bncov/Coverage Data/Import *`\neither from the Tools menu or from the context (right-click) menu.\n2. Explore the coverage visualization and explore additional analyses from\nthe right-click menu or with the built-in interpreter and `import bncov`\nfollowed by `covdb = bncov.get_covdb(bv)`.\n\nScripting:\n\n1. Ensure bncov's parent directory is in your module search path\nOR add it to sys.path at the top of your script like this:\n`sys.path.append(os.path.split(os.path.normpath('/path/to/bncov'))[0])`\n2. `import bncov` and write scripts with the CoverageDB class in\n`coverage.py`, check out the `scripts` folder for examples.\n\n## Screenshots\n\nImport a coverage directory containing trace files to see blocks colored in\nheat map fashion: blocks covered by most traces (blue) or by few traces\n(red). Additional context commands (right-click menu) include frontier\nhighlighting and a per-function block coverage report.\n\n* Watch a directory to have new coverage results get automatically highlighted\nwhen new coverage files appear\n* See at a glance which blocks are only covered by one or a few traces\n(redder=rarer, bluer=more common)\n* Quickly discover rare functionality visually or with scripting\n* Identify which blocks have outgoing edges not covered in the traces\n* See coverage reports on functions of interest or what functionality may not\nbe hit, or write your own analyses for headless scripting.\n\n![Block Coverage Report](https://github.com/ForAllSecure/bncov/raw/master/pictures/Coverage-Report.png)\n\n## Notes\n\nCurrently the plugin only deals with block coverage and ingests files in the\ndrcov format or module+offset format. Included in the repo is\n`dr_block_coverage.py` which can be used for generating coverage files, just\nspecify your DynamoRIO install location with an environment variable (or\nmodify the script) and it can process a directory of inputs. DynamoRIO binary\npackages can be found\n[here](https://github.com/DynamoRIO/dynamorio/wiki/Downloads) or you can use the\nincluded `download_dynamorio.py` script. See the\n[tutorial](/tutorial/) for a complete walkthrough.\n\nPlease file any feature requests/bugs as issues on GitHub, we welcome any input\nor feedback.\n\n## Scripting\n\nbncov was designed so users can interact directly with the data structures\nthe plugin uses. See the `scripts/` directory for more ideas.\n\n* Helpful CoverageDB members:\n    * trace_dict (maps filenames to set of basic block start addresses)\n    * block_dict (maps basic block start addresses to files containing it)\n    * total_coverage (set of start addresses of the basic blocks covered)\n\n* Helpful CoverageDB functions:\n    * get_traces_from_block(addr) - get files that cover the basic block\n      starting at addr.\n    * get_rare_blocks(threshold) - get blocks covered by <= 'threshold' traces\n    * get_frontier() - get blocks that have outgoing edges that aren't covered\n    * get_functions_from_blocks(blocks, by_name=False) - return dict mapping\n      function starts/names to blocks they contain\n    * get_traces_from_function(function_start) - return set of traces that have\n      coverage in the specified function\n    * get_traces_from_function_name(function_name, demangle=False) - return set\n      of traces that have coverage in the specified function\n\n* You can use Binary Ninja's python console and built-in python set operations with\nbncov.highlight_set() to do custom highlights in the Binary Ninja UI.\n",
   "license": {
      "name": "MIT",
      "text": "Copyright 2023 ForAllSecure, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."
   },
   "platforms": [
      "Darwin",
      "Windows",
      "Linux"
   ],
   "installinstructions": {
      "Darwin": "No installation necessary, but you may need tools to collect block coverage information.\n\nSee the [Github page](https://github.com/ForAllSecure/bncov) for usage instructions and a [tutorial](https://github.com/ForAllSecure/bncov/tree/master/tutorial).",
      "Windows": "No installation necessary, but you may want to download [DynamoRIO](https://github.com/DynamoRIO/dynamorio/wiki/Downloads) or other tools to collect block coverage information.\n\nSee the [Github page](https://github.com/ForAllSecure/bncov) for usage instructions and a [tutorial](https://github.com/ForAllSecure/bncov/tree/master/tutorial).",
      "Linux": "No installation necessary, but you may want to download [DynamoRIO](https://github.com/DynamoRIO/dynamorio/wiki/Downloads) or other tools to collect block coverage information.\n\nSee the [Github page](https://github.com/ForAllSecure/bncov) for usage instructions and a [tutorial](https://github.com/ForAllSecure/bncov/tree/master/tutorial)."
   },
   "version": "1.4.2",
   "minimumbinaryninjaversion": 1470
}