API Penetration Test – Providing Definitions

A common question we’ve run into over the past several months when scoping out API penetration tests is surrounding the API documentation. Specifically, the API endpoint/function definitions that list all of the available functions within a target API and the required request parameters used to interact with that function. These documents will also usually include the required authentication process, request headers, expected responses, and example requests. If you’re a developer, you’re probably familiar with the OpenAPI specification (formerly known as Swagger) used to define APIs, which is a great example of the type of information that should be included in an API definition. So why are we talking about this in the context of an API penetration test?

API penetration testing is a little unique. It’s very similar to web application penetration testing in the sense that it answers the same kind of questions about security that an organization may have, since APIs are really just abstracted functions that can be called independent of application front-ends. But they are unique in the sense that there is no front-end bundled with them to ease the interaction process. They are created and intended for machine-to-machine communications, usually. So in order to adequately test them as a penetration tester, we need the traditional information we would require for a web app including URL (and/or IP address), authentication credentials, etc. But we also need to understand what the API endpoint is expecting so we can interact with it in a meaningful way.

Why is an API Definition Important?

Let’s think about it like this. If you needed to test the physical security of a building, you want to check that all the doors are locked. But let’s imagine that the target building is massive and you don’t have a map of that building. Then, going one step further, that massive building is invisible so you’ve got no idea where the doors are, what type of doors they are, or what to try to gain access. You may not get in, but did you miss a door? Did you try to pull a door that was a push?

It’s a ridiculous scenario, but it’s a fair parallel to testing an API without a documented definition for it. We can definitely try to gain access from a black box perspective, and there is some value to that. Organizations may have a specific compliance requirement they need to meet or a particular customer asking for assurance that an external attacker can’t take advantage of a private API. But we can perform a much more thorough test and evaluate the security of an API without factoring in its “security through obscurity” by doing a gray-box assessment where we have the documented requests that the API is expecting. Seldom do you want to rely on the secrecy of an endpoint for its security, especially when that endpoint is exposed to the world on the Internet.

Using that target API’s documentation, we can then perform a thorough assessment of the required authentication, token/session management, input validation, error handling, business logic, and other security controls, just to name a few things. Otherwise, we looking for a needle in a haystack, blindly fuzzing a host to find the proper directory/URL structure and then guessing at the parameter names that the function is expecting. If the API is handling errors properly, this would be a futile process.

Ultimately, providing the specification for an API is an organizational decision driven by your threat model and what value you want to get out of an API penetration test you are having performed. If your only concern is a black-box, external adversary or maybe a check-the-box compliance meeting assessment, it may be the way to go as findings will generally be extremely limited. But to maximize the value of your investment in penetration testing and truly understand your risk as it relates to the security posture of an exposed API, providing documentation and having a more gray-box-style assessment performed is certainly a better approach in most cases.

If you still have questions or aren’t sure which approach is right for you when it comes to a possible API penetration test, please reach out and we’d love to have a conversation with you about the pros and cons so we can come up with an assessment approach that is right for your specific situation.