Detecting new API endpoints with oasdiff

One of the complaints I hear from new bug bounty hunters is that they often don’t know where to look for security vulnerabilities in APIs. I get that. It can be a daunting task. 

What if I told you that one of the best ways is to capture evidence of endpoint additions and changes that are probably much more brittle and unknown to other hunters, and test those first? Would that be helpful to know how to do?

Of course it would.

Let me show you a technique for finding new API endpoints in design-first APIs.

It all starts by abusing their API documentation

So here’s the thing. Modern APIs usually follow the OpenAPI Specification (OAS). It is a standardized format for defining and documenting RESTful APIs, allowing both humans and machines to understand the capabilities and structure of a web service.

It’s well formed. And easy for software to parse. Developers use this to stay in sync with API contracts, maintain a changelog, and detect breaking changes.

This has led to the creation of dedicated tools to make this easier on developers. One such tool is called “oasdiff”.   

What is oasdiff?

oasdiff is an open-source tool designed to detect and highlight differences between two versions of an OpenAPI Specification (OAS) document. 

This tool is essential for developers and API designers who need to manage changes in their API definitions efficiently. By providing a detailed comparison between OAS files, oasdiff helps identify breaking changes, new additions, and modifications in API endpoints, parameters, and schemas. 

This capability is particularly useful for maintaining version control, ensuring backward compatibility, and communicating updates to API consumers. 

Of course, as API hackers, we can weaponize oasdiff to work as an early detection system to alert us of new endpoints that get published.

Let me show you how.

How to use oasdiff

The basic usage of oasdiff is easy. You simply need to collect two versions of the API documentation and compare them. A typical command might looks something like this:

oasdiff diff base_file revision_file

The base_file represents the original/known version of the API documentation. This should be a well-formed OpenAPI specification document, and can be in either a JSON or YAML format.

The revision_file is the latest version of that same file.

A trick to obtaining different versions of API documentation

If you are investing any sort of time on target, you should try to regularly obtain the latest version of the API documentation. But if you are just beginning your recon on a new target, all is not lost. There are several ways to find older versions of the documentation in varying caches. This could be anything from search engine caches to the WayBack Machine.  

However, by far the easiest way is to locate the OAS YAML or JSON file in a source code repository like GitHub.

Let me give you a real example. 

Let’s say you want to conduct security testing against the OpenAI API as part of it’s bug bounty program. I mean, who doesn’t like to play with AI and API at the same time. Right? 

We can find the latest version of their API documentation on GitHub here. If you click on the “Raw” button, you can get a direct URL to the latest version.

Let’s download the latest API docs so we have a copy locally:

http https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml > openai-latest.yaml

Now to get an older version. If you look above the “Raw” button, there is a link to the file History. If you click that, you can see a history of commits to this file as it’s changed over time.

On the right side is an option to “View code at this point”, which is basically letting you look at the older version of the file as it was being committed. Click on that, hit the “Raw” button and download that version of the file:

http https://raw.githubusercontent.com/openai/openai-openapi/6e397e802c47e1e01c1bf080d34eb9e74a339404/openapi.yaml > openai-2weeks-ago.yaml

Now run oasdiff against it:

oasdiff diff openai-2weeks-ago.yaml openai-latest.yaml

There you can see the differences. I’ll admit, it’s kinda ugly, and we can do better.

Let me show you how to clean that output up so it’s easier to know where to do your security testing.  

Detecting API changes with oasdiff

If you look closely at the help docs for oasdiff, you will notice it includes an ability to generate the output in several formats. While the default output is in YAML, you can generate the output in other formats such as text, markup, JSON, and even HTML.

I want you to use HTML. It will give you an easy to read and follow HTML file. Try this:

oasdiff diff openai-2weeks-ago.yaml openai-latest.yaml -f html > diff.html

Now open the diff.html file in your favorite browser.

As you can see, oasdiff has generated an easy-to-follow layout showing you new, deleted, and modified endpoints. In my example here, we can see that the /chat/completions endpoint has recently been changed in its POST operation. It even outlines what the schema change was in the modified body payload, allowing us to better understand what has gone on.

If we look further in the API doc history and pull down a few versions, we can determine exactly when endpoints have been added, deleted, and modified.  

Advanced oasdiff usage

The HTML formatted output is great. It’s easy to follow and understand what is going on. However, knowing WHEN to look for such changes is important, and something we can automate.

This is where I like to combine scheduled tasks to pull down changed files with the oasdiff output using JSON format. You can then pipe that through jq to parse for what you want. If you don’t know what I am referring to, consider checking out my article on How to extract artifacts from OpenAPI docs to help attack APIs.

Why do I do that? I want to immediately know when NEW endpoints are introduced to an API. These endpoints will likely have the least amount of security test coverage, and have a less chance of me getting a dupe finding.

It might look something like:

oasdiff diff openai-2weeks-ago.yaml openai-latest.yaml -f json | jq -r ‘.paths.added’

In the targets I run this on regularly, I actually pipe any non-null output to a python script that then pushes that into a dedicated Slack channel to notify me of what endpoints to go look at.

Conclusion

By leveraging tools like oasdiff, you can significantly enhance your bug bounty hunting efforts by detecting new and modified API endpoints quickly and efficiently. This approach allows you to focus on the parts of an API that are likely less tested and more susceptible to security vulnerabilities. 

By regularly monitoring API changes, you can gain a competitive edge by identifying potential attack vectors before other researchers do. Automated tasks and smart parsing of oasdiff output keep you informed and ensure you’re always one step ahead.

As you continue to refine your API security testing skills, remember that staying proactive and informed is key to uncovering those elusive security vulnerabilities that others might miss. 

Happy hunting!

One last thing…

Have you joined The API Hacker Inner Circle yet? It’s my FREE weekly newsletter where I share articles like this, along with pro tips, industry insights, and community news that I don’t tend to share publicly. If you haven’t, subscribe at https://apihacker.blog.