8 Things to Provide Your Testers Ahead of an API Penetration Test
If you’re running a business online, you’re likely providing an application program interface (API) on your website that allows your customers or business partners to enter and retrieve data. At Schellman, we primarily see REST-based APIs, but we’ve also tested GraphQL and occasionally SOAP.
In our experience, there are three business justifications for API use:
- Public-facing applications built from the ground up as an API or web service
- Public-facing applications that are not native APIs, but offer an API to access some functionality
- Applications that provide API access to select users (e.g. corporate employees, admins)
But as with everything digital, there are certain risks to operating online, so ensuring these interfaces stay safe is important, which is why you’ve opted for an API penetration test.
In our years conducting these specific tests across multiple industries for multiple organizations, our experienced penetration test team found that, historically, a lot of time is lost just getting the information needed for this type of penetration test before it starts.
You can mitigate this by preparing ahead of time, and in this article, we will explain what your penetration tester will need to know before they can get to work—such as endpoints, examples of calls, documentation, and test cases, among others. By pulling all this together for your chosen assessors, you’ll set up your API test for success from the start.
8 Things to Provide Your Penetration Testers Ahead of Your API Test
1. Your Workflow
Even before they get to the details of your API, your tester needs to understand the typical workflow that the API calls support. (For the layperson: “calls” means the process of your application submitting a request to the API and that API retrieving and delivering the requested data from the external server or program.)
While they can certainly discern some of that functionality, helping your penetration tester understand why a user would make a given call and a background on the use case can be beneficial. Understanding if and how an application also makes use of other third-party APIs—for example, a data pull from a CRM solution—can also be critical.
2. API Endpoints
Another item you should provide your penetration testers is a list of endpoints and servers to where the API calls are being made, which will all need to be scoped and documented. Oftentimes, organizations will provide incomplete information, i.e., not all the endpoints are included.
For example, just the host URL might be provided without the full endpoint path:
- https://run-api.com/
Or sometimes the path is provided with no host information.
- /v1/key
Your testers need both components of the host and path:
- https://run-api.com/v1/key
3. Description of Endpoint Purposes
You need to give the API call a name, as well as a description of what it accomplishes so that your penetration testers understand what data is expected, will be returned, or what the function should be performing.
|
Don’t Just Provide This |
Provide This |
|---|---|
This is vague and could cause confusion and/or delays if your penetration testers only get this limited information. |
Adding a simple name and description lets the tester know the intended function of the API call. |
4. Authentication Credentials
To make authenticated API calls, your tester will also need the means to do that.
While there are different ways to set up authentication for API calls, many use Bearer authentication tokens, where the user needs to have the token and provide the token in the header of the request to make an authenticated call.
No matter what authentication methods you use, ensure your tester has the correct credentials for them before the penetration test commences.
5. Example API Call
Providing an example of the API call can also streamline your penetration test. The example should provide the needed formatting and expected parameters to perform the request.
In the following example, an API call, formatted as a cURL request, is being used to create a user:
curl --location --request POST "https://run-api.com/v1/users" \
--header "Authorization: 2f5c19c5-bc39-4861-89e8-c127ed804f79" \
--data "{\"firstName\":\"Robert\",\"lastName\":\"Smith\",\"email\":\"rsmith@run-api.com\"}"
6. Example of Valid Response
To go with the example call, you should also provide a valid response for each API call. This information helps your tester understand what to expect to see if the request is made successfully.
The following example response is the expected response after creating a user.
{
"status": true,
"result": {
"success": "userId 24 created"
},
"error": false
}
7. Descriptions and Collections
You or your developers should already have processes and methods in place to test the functionality of API calls, and you should share any WSDL files, Swagger files, Postman collections, or other design documentation with your tester.
Many of the same tools used to develop your sites, such as SoapUI or Postman, will also be utilized during a penetration test. By providing these types of files, you’ll empower your tester with an already-built set of valid calls to work with.
8. Valid Test Cases
Even when good documentation and examples are available, there’s one other issue that will commonly delay a test—if the test calls you provide do not work in the environment being tested, you can expect your test to be delayed.
We previously mentioned that you should provide Postman collections—keep in mind that if you submit those that work in the development environment, but the user acceptance testing (UAT) region is the one being tested, these calls may fail. Backend functionality that may be required for an API call to work properly may exist in one environment but not another—to avoid this common pitfall, ensure that your calls work properly in the selected environment to be tested.
Next Steps
More and more applications are being developed as an API, as these allow organizations to provide different user interfaces to their customers, regardless of what type of device is being used to access the data.
When preparing for an API penetration test, remember to provide these 8 items—workflow, endpoints and their purposes, authentication credentials, example calls and responses, documentation, and test cases—so that you’ll avoid common delays and succeed in your testing.
If you’d like to get even more hands-on with your preparation, test out the Schellman example Run-API where you can generate an authorization token, create, update, list, and delete users.
To learn more about different kinds of penetration testing and how to prepare for those, please read our other articles that delve deeper into these different facets:
- How to Prepare for Your Web Application Penetration Test
- A Breakdown of FedRAMP Penetration Test Guidance 3.0
- How to Prepare for Your Internal Network Pen Test
But if you find you still have specific questions, please feel free to also contact us so that we can set up a conversation with our team of experts and address any remaining concerns you may have.
About Rene Guerra
Rene Guerra is a Manager and Penetration Tester with Schellman based in Florida. In this position, Rene leads test efforts against clients' web applications, networks, and employees through social engineering campaigns. Before joining Schellman, Rene worked as an IT Manager and IT Specialist, specializing in networking and infrastructure. Additionally, Rene works very closely with the new Pen Testers to train and mentor them.