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

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

Example 1

We want to scan the REST API https://api.example.com/, which uses a name/api-key pair for authentication, and we have a Swagger file describing this API.

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 - this is good practice.

2. Give the scanner a description of the API

This is a REST API, and we have a Swagger 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 weren't hosted online we could paste the entire contents, in either JSON or YALM, into the Seeded Targets box above.

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.

Example 2

We want to scan the REST API https://api2.example.com/, which does not use a name/api-key pair for authentication, but logging in to the application at 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.

1. Add the API as the scan target

The first thing to do is add https://api2.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://awesome-app.example.com as a second scan target.

3. Set up authentication

This API doesn't use a name/api-key pair for authentication so we can't use Seeded API Access Keys.  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

Conclusion

And that's it, we now have two scans, one scanning the API https://api.example.com/ based on its swagger file, and one scanning the API https://api2.example.com and the application https://awesome-app.example.com together.

Further Reading

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 well 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