Bishop Fox named “Leader” in 2024 GigaOm Radar for Attack Surface Management. Read the Report ›

Introducing Swagger Jacker: Auditing OpenAPI Definition Files

Dark purple and black background with white and purple letters. Swagger Jacker logo on right side and is two white papers with blue and white round target.


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.

Automating the analysis of response codes for defined API routes.

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.

Generate a list of curl commands with Swagger Jacker.

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:

Using the endpoints command to generate output

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!

Subscribe to Bishop Fox's Security Blog

Be first to learn about latest tools, advisories, and findings.

Tony West

About the author, Tony West

Operator III

As a member of the Bishop Fox Cosmos team, Tony focuses on the continuous testing of clients' public-facing attack surfaces. Prior to joining Bishop Fox, Tony served in the U.S. Air Force as a Senior Operator and Technical Lead of a Department of Defense Red Team. In 2023, Tony successfully transitioned from military service to the civilian workforce through the Skillbridge program. He holds a B.S. in Cybersecurity from University of Maryland Global Campus.

More by Tony

This site uses cookies to provide you with a great user experience. By continuing to use our website, you consent to the use of cookies. To find out more about the cookies we use, please see our Privacy Policy.