REST API Introduction

This documentation section is a user guide for w3af’s REST API service, its goal is to provide developers the knowledge to consume w3af as a service using any development language.

We recommend you read through the w3af users guide before diving into this REST API-specific section.

Starting the REST API service

The REST API can be started by running:

$ ./w3af_api
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

Or it can also be run inside a docker container:

$ cd extras/docker/scripts/
$ ./w3af_api_docker
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

Authentication

It is possible to require HTTP basic authentication for all REST API requests by specifying a SHA512-hashed password on the command line (with -p <SHA512_HASH>) or in a configuration file using the password: directive (see the section below for more information about configuration files).

Linux or Mac users can generate a SHA512 hash from a plaintext password by running:

$ echo -n "secret" | sha512sum
bd2b1aaf7ef4f09be9f52ce2d8d599674d81aa9d6a4421696dc4d93dd0619d682ce56b4d64a9ef097761ced99e0f67265b5f76085e5b0ee7ca4696b2ad6fe2b2  -

$ ./w3af_api -p "bd2b1aaf7ef4f09be9f52ce2d8d599674d81aa9d6a4421696dc4d93dd0619d682ce56b4d64a9ef097761ced99e0f67265b5f76085e5b0ee7ca4696b2ad6fe2b2"
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

In the above example, users are only able to connect using HTTP basic authentication with the default username admin and the password secret.

For example, using the curl command:

$ curl -u admin:secret http://127.0.0.1:5000
{
  "docs": "http://docs.w3af.org/en/latest/api/index.html"
}

Please note that even with basic authentication, traffic passing to and from the REST API is not encrypted, meaning that authentication and vulnerability information could still be sniffed by an attacker with “man-in-the-middle” capabilities.

When running the REST API on a publicly available IP address we recommend taking additional precautions including running it behind an SSL proxy server (such as Pound, nginx, or Apache with mod_proxy enabled).

Config file format

Using a configuration file is optional and is simply a convenient place to store settings that could otherwise be specified using command line arguments.

The configuration file is in standard YAML format and accepts any of the options found on the command line. A sample configuration file would look like this:

# This is a comment
host: '127.0.0.1'
port: 5000
verbose: False
username: 'admin'
# The SHA512-hashed password is 'secret'. We don't recommend using this.
password: 'bd2b1aaf7ef4f09be9f52ce2d8d599674d81aa9d6a4421696dc4d93dd0619d682ce56b4d64a9ef097761ced99e0f67265b5f76085e5b0ee7ca4696b2ad6fe2b2'

In the above example, all values except password are the defaults and could have been omitted from the configuration file without changing the way the API runs.

Serve using TLS/SSL

w3af’s REST API is served using Flask, which can be used to deliver content over TLS/SSL. By default w3af will generate a self signed certificate and bind to port 5000 using the https protocol.

To disable https users can set the --no-ssl command line argument.

Advanced users who want to use their own SSL certificates can:

  • Start w3af in HTTP mode and use a proxy such as nginx to handle the SSL traffic and forward unencrypted traffic to the REST API.
  • Copy the user generated SSL certificate and key to /.w3af/ssl/w3af.crt and /.w3af/ssl/w3af.key and start ./w3af_api without --no-ssl.

Note

Using nginx to serve w3af’s API will give the user more configuration options and security than running SSL in w3af_api.

REST API Source code

The REST API is implemented in Flask and is pretty well documented for your reading pleasure.

REST API clients

Wrote a REST API client? Let us know and get it linked here!