Create a Custom Upload Add-on

If your answer is not here the Community Forums are your best bet.

Introduction to upload add-ons

Before you get started with this guide, make sure you are running the latest version of Dradis. Install it from Git with these instructions before moving on.


In this guide we're going to walk through the process to create a custom upload add-on. An upload add-on will allow you to import to your Dradis instance the output of your desired tool.


1. Clone an existing Add-on

The easiest way to start building is to clone one of the existing upload add-ons to use as a working guide as you customize your upload add-on.

We recommend picking a simple one, like:


To clone the add-on:

  1. Pick an upload plugin from the list above to use as a template.

  2. Click the link above to open the plugin's GitHub repo.

  3. Copy the HTTPS link to clone the repo. In the example below, we're going to clone the dradis-brakeman repo.

    Dradisframework 15
  4. Back on your local system, open the terminal and navigate to the folder where you installed dradis-ce.

  5. Run the following in the terminal:

    $ git clone [repo link]

    Paste in the HTTPS link you copied from GitHub! Example:

    $ git clone https://github.com/dradis/dradis-brakeman.git

2. Rename your add-on

Below is an example of the file structure of a Dradis add-on. Every upload add-on uses this basic file structure.

Dradisframework 16

Rename files and folders

On your local system, rename your folders and files. For the root folder, we recommend using the dradis-[name] naming convention where [name] is a placeholder for your importer type (e.g. brakeman, nmap, ...). In the examples below, we're going to assume we are building an upload add-on for a tool called [name], and we will be working with the dradis-[name] repo.


3. Edit your files

Before you upload the add-on to Dradis, you're going to want to edit files and at least change the references to the old upload add-on name (e.g. Brakeman) and change them to your new name (e.g. [name]).

The instructions below will not cover exactly how to code your specific upload add-on. They are simply a high-level overview of the different files that comprise an upload add-on to help you get started. This is not an exhaustive list of all of the changes you may need to make. After completing the steps below, you should be ready to start your custom coding.

Note: when the instructions say, "update all references to the old name", it means to go through the file and change things like class names to match the new syntax of your custom upload add-on. For example, change brakeman to [name] and Brakeman to [Name]. Remember: in Ruby, capitalization counts!

Start by editing the following files:

Edit depending on your add-on:

In most cases you can ignore all the following files:

You can check that you are not forgetting to rename anything with a terminal command like grep -ri brakeman dradis-[name] or similar.


4. Load the Add-on to Dradis

  1. Open up the dradis-ce folder on your local system and open file dradis-ce/Gemfile.plugins.

  2. Add a reference to your new upload add-on by adding a line to the # -- Export section:

    gem 'dradis-[name]', path: '../dradis-[name]'
    Example:
    gem 'dradis-[name]', path: '../dradis-[name]'
    Note: make sure that your new upload add-on is in the same folder as the other upload add-ons on your system so that it matches the filepath you just added to Gemfile.plugins.

  3. On your local system, open the terminal and navigate to the dradis-ce folder. (Shut down Dradis if it was already running). Then run:

    $ bundle install
    $ bundle exec rails server

  4. Open Dradis in your browser and click Upload output from tool in the header. Check out the new option in the options dropdown! Depending on how much custom coding you've already done (and how much is left to do) you may be able to test out your upload add-on at this point. Otherwise, continue on to the final step.
  5. Dradisframework 17

5. Test, Edit, Repeat

It's almost a guarantee that you'll be spending a lot of time at this step making changes to your code, running into stack traces/errors, searching Google for workarounds, and testing your importer until it does what you need it to do. If you're this far, keep up the great work!

Remember, StackOverflow is your friend and the Dradis Community Forums are here to help.