Setting up a scan of your API follows much the same process as setting up a web application scan, with just a few extra steps:

1. Your API's root will need adding as a scan target
2. You will need to give the scanner a description of the API, in a language it understands.  This could be by providing an SDL file (eg a Swagger or WSDL file), or by pointing the scanner to an application which uses the API (then by crawling the application the scanner will see the API requests and know how to target them).
3. If your API requires authentication you will need to set this up in the scan configuration

This article will describe several ways to configure a scan for authenticated API scanning.

Your use-case may match exactly one of the examples shown in this guide, or you may need to combine elements from the different techniques.

• Scanning a REST API Which Uses a name/api-key Pair for Authentication and has a Swagger/ OpenAPI File
• Scanning a SOAP API With a Front End Application
• Scanning a REST API Which Uses a JWT Bearer Token for Authentication and has a Swagger/ OpenAPI File
• Further Reading

Scanning a REST API Which Uses a name/api-key Pair for Authentication and has a Swagger File

In this example we want to scan the REST API https://api.example.com/.  The API is described in the Swagger/OpenAPI file https://api.example.com/swagger.json.  Authentication takes the form of a name/api-key pair.

1. Add the API as the scan target

The first thing to do is add https://api.example.com as the scan target:

I'm including the host this API lives on as an infrastructure target too (if in scope) - this is good practice.

2. Give the scanner a description of the API

This is a REST API, and we have a Swagger/OpenAPI file describing it which is hosted at https://api.example.com/swagger.json, so we add this in

• Web Application Scanner Settings
  • API Scanning
    • Swagger / OpenAPI
      • Seeded Targets Remote

You can see this in the screenshot on the following step.

If it wasn't hosted online we could paste the entire content, in either JSON or YAML, into the Seeded API Targets box.

If you have no Swagger/OpenAPI file you will need to scan the API along with a front-end application, as shown with the SOAP API example below.  That process will work just as well with a REST API (and indeed you can combine the two methods, a Swagger file and a front-end application, for maximum coverage).

3. Set up authentication

This API uses a name/api-key pair for authentication, so we'll add our key in Seeded API Access Keys:

That's all that's needed for this API.  Now let's look at a more complex example.

Scanning a SOAP API With a Front End Application

In this example we want to scan the SOAP API https://api2.example.com/.  There is no way to authenticate with the API directly, but logging in to the front end application https://awesome-app.example.com produces the relevant authentication headers to grant you access to the API.  We do not have any sort of SDL file describing this API, but crawling the front end application will expose the API's endpoints to the scanner.

1. Add the API as the scan target

The first thing to do is add https://api.example.com as the scan target. 

2. Give the scanner a description of the API

We do not have an SDL file, but crawling the application will expose the the API requests to the scanner, so we will add https://app.example.com as a second scan target.

3. Set up authentication

We cannot authenticate with this API directly, so instead we will set up authentication with the application (just as though we were running an ordinary authenticated application scan).  We'll do this by writing a GoScript and including it in

• Web Application Scanner Settings
  • Authenticated Scanning
    • GoScript

Now, we have two separate application targets in this scan, https://api2.example.com/ and https://awesome-app.example.com.  Ordinarily these would be scanned in separate processes, so the authentication session for the application would not be present in the process scanning the API.  Therefore we want to tell the scanner to scan both of these targets in a single process.  To do so we tick the option:

• Web Application Scanner Settings
  • Advanced Settings
    • Group URLs

Scanning a REST API Which Uses a JWT Bearer Token for Authentication and has a Swagger/ OpenAPI File

In this example we want to scan a Standalone REST API https://api.example.com. The API is described in the swagger file https://api.example.com/swagger.json.  Authentication takes the form of a JWT bearer token which can be acquired by calling a separate endpoint.

1. Add the API as the scan target

The first thing to do is add https://api.example.com as the scan target:

I'm including the host this API lives on as an infrastructure target too (if in scope) - this is good practice.

2. Give the scanner a description of the API

This is a REST API, and we have a Swagger/ OpenAPI file describing it which is hosted at https://api.example.com/swagger.json, so we add this in

• Web Application Scanner Settings
  • API Scanning
    • Swagger / OpenAPI
      • Seeded Targets Remote

If Swagger/OpenAPI file isn't hosted online we could paste the entire file content, in either JSON or YAML, into the Seeded API Targets box.

If you have no Swagger/OpenAPI file you will need to scan the API along with a front-end application, as shown with the SOAP API example above.  That process will work just as well with a REST API (and indeed you can combine the two methods, a Swagger file and a front-end application, for maximum coverage).

3. Set up authentication

We can use the API Authentication Helper plugin to request the JWT bearer token and use it in the authorization header for the scanner's API calls.

Further Reading

For background and an overview of API scanning with AppCheck see API Scanning with AppCheck.

Scan Scope, Targets and Seeded Targets

We see cases where users add the same API (but with different endpoints) as separate scan targets, eg:

• https://api.example.com/v1/users
• https://api.example.com/v1/admin

This actually results in the entire API being scanned twice.  To understand why that is, please read https://appcheck.zendesk.com/hc/en-us/articles/360020438298-Application-Scan-Targets-Scope-and-Seeded-Targets

GoScript

You may need to write a GoScript to log in to your  application.  We have a Guide to GoScript here: https://appcheck.zendesk.com/hc/en-us/articles/360011325597-A-Guide-to-GoScript