Hitman

Hitman is a web fuzzer written in Ruby for Grape APIs. You can use it to check the robustness of your parameter validations by targeting your own server.

Purpose

Did you ever have to create a server API but were not sure if you had covered all possible and impossible inputs? If not, users might sooner or later fill your database with invalid data and your application might break. In practice, it’s almost impossible to anticipate all possibilities of usage of your API.

Hitman simulates malicious API usage by first analysing the endpoints of your API and then hitting it with random requests and trying to tickle a server error out of your API. If you can escape the hands of Hitman, you are ready for the wild.

The practice of Fuzz testing is very common in client-side applications but not so for server APIs. Hitman fills this gap with unexpected consequence and persistence.

Installation

Add this line to your application’s Gemfile:

{% highlight ruby %} gem ‘hitman’ {% endhighlight %}

And then execute:

$ bundle

Or install it yourself as:

$ gem install hitman

Usage

At the moment, Hitman can only auto-analyse Grape APIs, but if you have any other API, you can still use it by supplying the configuration manually.

First, define a target to attack. It is best to run your API locally, for speed reasons.

{% highlight ruby %} t = Hitman::Target.new(‘my api’, ‘http://localhost:9292’) {% endhighlight %}

Hitman needs the name and the address of its target. He’s gonna find out the rest. No need for a picture.

If your API uses param authentication, you can supply postfix data which will be attached to every request made, e.g. if you need to authenticate:

{% highlight ruby %} t.postfix = { email: ’[email protected]’, password: ‘12345678’ } {% endhighlight %}

Hitman first needs to analyse the target to find the best possible strategy to attack. Load your API class and pass it, along with a reference to your target, to Hitman:

{% highlight ruby %} scanner = Hitman::Scanner.new target = scanner.scan_grape(t, API) {% endhighlight %}

Hitman is ready and armed now. Start the fuzzer and watch chaos unfold.

{% highlight ruby %} fuzzer = Hitman::Fuzzer.new fuzzer.start(target) {% endhighlight %}

Not using a Grape API? No problem.

You just manually need to supply some secret information to Hitman.

First, create a target:

{% highlight ruby %} t = Hitman::Target.new(‘my api’, ‘http://localhost:9292’) {% endhighlight %}

Then, for every endpoint of your API, you need to supply the HTTP method, the path and possible parameters in the form

{% highlight ruby %} route = Hitman::Route.new(‘post’, ‘/api/users’) t.routes « route route.params « Hitman::Param.new(’email’, ‘string’) route.params « Hitman::Param.new(‘password’, ‘string’) route.params « Hitman::Param.new(‘password_confirmation’, ‘string’) {% endhighlight %}

You can use this example:

{% highlight ruby %} my_api_routes.each do |api_route| route = Hitman::Route.new(api_route.method, api_route.path) t.routes « route api_route.params.each do |name, type| route.params « Hitman::Param.new(name, type) end end {% endhighlight %}

After that, you’re ready to run the Fuzzer.

Check out the Bitbucket-Repo for more information.