Building REST APIs for hacking tools

What is this post about?

In this post I will talk about how to create REST APIs for hacking tools in 5 minutes.

What is the real problem?

The problem that I present to you today solves several small problems. I expose them as questions:

  • Had you have problems auditing remote services lacking a proxy machine?
  • Do you need to allow access to only specifics commands in a system?
  • Moreover: do you need to delegate access to these commands, or ONLY to certain parameters of the command?
  • Wouldn’t be great to be able to perform a security analysis by calling curl or wget?

Well, a lot of us had this problems. For this reason in the BBVA-Labs department we have been working on a pretty cool toy.

Check out our BBVA-Labs projects

The idea is very simple:

Given a command line script, you can create a REST API in minutes.

We gave this project the name of Kapow! and my colleagues chose a pretty cool logo 🙂

Although the project is still in beta, you can download and use it. We think that the idea is powerful and exciting (and that’s why I’m writing this post :D)

Download Kapow! from Github

Create an API for nmap in 5 minutes

How does it works in one image

Kapow actually does the magic of creating the REST API, given a command:

Defining the API

For Kapow to know how to create the API it needs to create a .pow file with the instructions. Do not be scared, it’s very simple:

# nmap.pow

kapow route add -X GET '/scan/{ip}' -c 'nmap -sL $(request /matches/ip) | response /body'

Let’s analyze the file. You’ll see it’s very simple:

  1. We create a new API with a path: /scan/{ip}, where IP is the target to analyze established as an input parameter.
  2. -c ‘nmap…’: is the way we tells Kapow! the command to run.
  3. $(request /matches/ip): this is the way we tells Kapow! that from the received request, we want to use the variable “ip”.
  4. response /body: this is the way we tells Kapow! how to return the result of execution as HTTP

Building Kapow!

Since the project is still beta, we will need to build Kapow! ourselves. You scare us. It’s easy.

At first we clone the repository:

> git clone -b develop
> cd poc/

Be careful when making the clone. The branch to clone is the develop !!

First of all we will need to add a line to the original Dockerfile, which is located in the /poc/Dockerfile directory. We need to add nmap for installation.

The resulting Dockerfile should look like this:

FROM python:3.7-alpine

COPY Pipfile Pipfile.lock /tmp/

COPY bin/* /usr/bin/


RUN apk upgrade --update-cache;                 \
    apk add                                     \
        bash                                    \
        curl                                    \
        coreutils                               \
        nmap                                    \
        file;                                   \
    pip install pipenv;                         \
    pipenv install --system --deploy;

ENTRYPOINT ["/usr/bin/kapow"]

Finally we will build the image of Kapow! with the Dockerfile that we just modified:

> docker build -t kapow .

Running the API

Once we have built our Docker image, we need our nmap.pow file we created earlier and launch Kapow:

> ls
> docker run -p 8080:8080 -it -v "$(pwd)/":/tmp kapow server /tmp/nmap/nmap.pow
======== Running on ========
(Press CTRL+C to quit)
Route created GET /list/{ip}

What we have done:

  1. Put our service listening at port 8080.
  2. Since the Docker image has not included the nmap.pow file, we need to “mount” it from the host, with the -v command. The first $(pwd) parameter tells Docker mount the current directory in the /tmp directory inside the Docker container.
  3. We run the server with the server command
  4. We indicate Kapow! the definition file which we assembled from outside the Docker container.

Testing the API

Now we’ll try our API. In this case we will use Curl to launch a scan against our loopback:

> curl -v http://localhost:8080/scan/
*   Trying
* Connected to localhost ( port 8080 (#0)
> GET /list/ HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.54.0
> Accept: */*
< HTTP/1.1 200 OK
< Content-Length: 168
< Content-Type: application/octet-stream
< Date: Fri, 21 Jun 2019 13:35:48 GMT
< Server: Python/3.7 aiohttp/3.5.4
Starting Nmap 7.70 ( ) at 2019-06-21 13:35 UTC
Nmap scan report for localhost (
Nmap done: 1 IP address (0 hosts up) scanned in 0.00 seconds
* Connection #0 to host localhost left intact


Although we are aware that the project is at an early stage, the potential it has is enormous.

Imagine performing an entire security audit with a Postman. It sounds great, right?

Finally, I would like to leave you with a question:

What do you think about the idea of Kapow! and what use cases do you think of?