Introducing Swagger Jacker: Auditing OpenAPI Definition Files

Swagger Jacker, or “sj” for short, is an open-source tool developed to audit OpenAPI definition files. This enables offensive security professionals to identify potential vulnerabilities or misconfigurations in the API routes defined within the definition document.

What is Swagger?

Swagger is a suite of API developer tools created by SmartBear Software. According to SmartBear, Swagger started out as a simple, open-source specification for designing RESTful APIs in 2010. The Swagger specification was donated to the Linux foundation in 2015 and renamed as the OpenAPI specification. These definition files are often hosted on public-facing web servers to be used in combination with Swagger UI applications, allowing developers to perform testing on the associated API.

What’s the big deal about exposed definition files?

While many definition files are intentionally accessible to support development for an API, sometimes these files are unintentionally exposed to end users. If an API definition file is mistakenly exposed to the public, the file may expose routes with sensitive functionality that could be exploited by an attacker with malicious intent. As many of these routes are intended for internal use only, security may not have been considered when developing the associated API. With that in mind, these exposed files could ultimately lead to discovery and exploitation of IDOR and SQL injection vulnerabilities, information disclosure, and many other common vulnerability classes – giving attackers the upper hand and a vulnerable exposure on the attack surface.

Digging into the Specification

Looking at the Open API specification, more explicitly version three, there are several fields within the OpenAPI object that are parsed by Swagger Jacker. The first worth noting is the “Info” field, which is comprised of an Info object. This object provides metadata about the API, such as the API description, a “Terms of Service” URL, and the version of the API document, among other types of information.

Upon running the automate command, you will first be presented with information about the documented API from the Info object. This may give insight into how the developer intended the API to function, what expected values can be passed to test authenticated routes, such as a hard-coded developer API key, and more.

The security field (another field within the OpenAPI object) is made up of a Security Requirement Object. This object defines what authentication mechanisms are allowed for the API, ranging from methods such as HTTP basic authentication to Oauth2 implementations. Thanks to a recommendation by Jon Williams, the tool checks the specification document for authentication mechanisms and depending on the mechanism prompts the user to apply their own value if they choose to do so.

Automated Testing

The biggest factor that drove the development of this tool was the significant amount of time spent auditing API endpoints after the discovery of a publicly hosted specification file. Some APIs will have hundreds of routes defined, and testing each one manually can become a tedious process.

With Swagger Jacker, you can easily automate the process of analyzing response codes for each defined API route.

After the user decides whether to apply an authentication value, the tool will generate requests to each documented endpoint while automatically applying values of the type declared in the specification.

If the tool observes a 200 OK response, the endpoint will be highlighted as accessible. Similarly, if a 401 or 403 status code is observed, the tool will report that authentication is required for the associated endpoint. This significantly reduces the time it may take to test an API for weak authentication issues. However, as with all automation, it is sometimes best to validate manually for the most accurate results.

Preparation for Manual Testing

If the automate command returns some interesting commands that you want to test manually, you can employ the prepare command to quickly generate a list of curl commands.

Once the curl commands have been generated, you can adjust as needed to conduct your manual testing. Plans for future updates to the tool will allow the generation of commands to pass to tools like sqlmap and ffuf to easily test for IDOR and SQL injection flaws.

Word List Generation

Are you more interested in gathering the routes rather than sending requests to the target? This is where the endpoints command comes into play. Simply use the endpoints command to generate output containing the routes as shown below:

Download Swagger Jacker to use for your own pen testing adventures. We would love to hear your feedback via our LinkedIn, YouTube, Twitter, or Discord channels.

Special thanks to Jon Williams and Tom Hudson for providing valuable feedback on the tool during development!