Single-Endpoint Walkthrough

Setup walkthrough of scanning a single application endpoint

While HawkScan can work with an existing OpenAPI specification, it's fairly common to not have such a specification for an "internal use only" API. The lack of an Open API spec along with non-auto discoverable API endpoints can mean HawkScan doesn't have enough context to run a thorough scan.

Luckily you don't need to build an entire OpenAPI specification for your application's API to see HawkScan in action. This guide will cover how to setup HawkScan to analyze a web application with one endpoint in the following steps:

Once that single endpoint is set up in HawkScan and scanned, then you have a working pattern for adding more endpoints and a path to getting all of your application's endpoints scanned.

Gather Endpoint Details

HawkScan needs to know a few basic things about an endpoint in order to scan:

  • URI/Path: The path of the endpoint on the server. For a URL like https://test.server.com/api/search, the path would be the /api/search/ part.

  • Protocol scheme: Either http or https

  • The http method: Most commonly POST or GET

  • Optional http parameters: For GET requests, these are either part of the URI or on the URL itself in a URL Encoded name=value syntax. For POST requests, they can be in a payload sent to the server.

If you don't know these offhand, a great way to get them is to use the developer tools of your browser.

GET request in Chrome

Here's what one looks like in the Chrome dev tools window using a sample application:

In this case, we see in the Network window the requests on a timeline. Under that, we see two other panels with the name and details of the request. Based on these items, we can get HawkScan the following details about the endpoint:

  • The URL requested is https://localhost:9000/api/jwt/items/search/item1, so the path is /api/jwt/items/search/item1

  • The http method is GET

  • There are no URL Encoded parameters, but the URL does contain a parameter called item2, a search term. We can't tell this from the URL, but rather looking at the endpoint definition in our server application code. If we search for item2, the URL changes to https://localhost:9000/api/jwt/items/search/item2 - note how the base URI/path stays the same, but the last piece changes.

POST request in Firefox

Other browsers have similar tools. Here's what a similar POST request Firefox looks like in FireFox:

For this POST request, the details HawkScan needs are:

  • Path: /search

  • http method: POST

  • Parameters: POST parameters are passed in via a form data payload, not on the URL like a GET. The browser developer tools capture them too, so in Firefox we need to click on the Params tab to see them:

This tells us that the params for this POST endpoint include a csrf token, and similar to the GET request, a searchText parameter.

Describe the Endpoint

Knowing those details, we need to tell HawkScan about them so it can do its job. Endpoint are described in the stackhawk.yml in the api section. For example, the GET endpoint details from above would translate into the follow stackhawk.yml:

app:
host: ${APP_HOST:https://localhost:9000}
api:
basePath: /api/open
schemes:
- https
paths:
/items/search/{searchText}:
get:
parameters:
- in: path
name: searchText
type: string

The example POST endpoint details in stackhawk.yml look very similar, except the parameters are in the body and for this example we need a antiCsrfParam parameter:

app:
host: ${APP_HOST:https://localhost:9000}
antiCsrfParam: _csrf
api:
basePath: /api/open
schemes:
- https
paths:
/search
post:
parameters:
- in: body
name: searchText
type: string

Run HawkScan

Given either of those stackhawk.yml files, we can run a scan the usual way:

docker run --rm -v $(pwd):/hawk:rw -it stackhawk/hawkscan:latest stackhawk.yml

And now HawkScan has an endpoint to scan against!

Next Steps

Filling out your other application endpoints is just a matter of tacking them onto the api section of the stackhawk.yml. If after a while that gets difficult to manage, the api section can be broken out into a separate and proper OpenAPI spec file.