1. API recon and documentation

API recon

To start API testing, we first need to find out as much info about the API as possible, to discover its attack surface. To begin, we should identify API endpoints. These are locations where an API receives requests about a specific resource on its server. For example, consider the following GET request:

The API endpoint for this request is /api/books. This results in an interaction with the API to retrieve a list of books from a library. Another API endpoint might be, for instance, /api/books/mystery, which would retrieve a list of mystery books.

Once we have identified the endpoints, we need to determine how to interact with them. This enables us to construct valid HTTP requests to test the API. For example, we should find out info about the following:

• The input data the API processes, including both compulsory and optional parameteres.
• The types of requests the API accepts, including supported HTTP methods and media formats.
• Rate limits and authentication mechanisms.

API documentation

APIs are usually documented in both human-readable and machine-readable formats. The former is designed for developers to understand how to use the API and the latter to be processed by software for task automation, such as API integration and validation. API documentation is written in structured formats, like JSON or XML, and is often publicly available. If this is the case, we should always start our recon by reviewing the documentation.

Even if API documentation isn’t openly available, we may still be able to access it by browsing apps that use the API. To do this, we can use Burp Scanner to crawl the API. We can also browse apps manually using Burp’s browser. We should look for endpoints that may refer to API documentation, for example:

• /api
• /swagger/index.html
• openapi.json

If we identify an endpoint for a resource, we must investigate the base path. For instance, if we identify the resource endpoint /api/swagger/v1/users/123, then we should investigate:

• /api/swagger/v1
• /api/swagger
• /api

We could also use a list of common paths to directy fuzz for documentation.

Lab: Exploiting an API endpoint using documentation

Objective: To solve the lab, find the exposed API documentation and delete carlos. You can log in to your own account using the following credentials: wiener:peter.

1. Upon logging in as wiener and updating his email we have the following request:

   

2. We should now investigate the base path:

   

   

   

3. The API is interactive: we can click on the DELETE row and delete user carlos:

   

   

Using machine-readable documentation

We can use a range of automated tools to analyze any machine-readable API documentation that we find, such as Burp Scanner to crawl and audit OpenAPI documentation, or any other documentation in JSON or YAML format. We can also parse OpenAPI documentation using the OpenAPI Parser BApp. We may also be able to use a specialized tool to test the documented endpoints, such as Postman or SoapUI.

Resources

• API testing.