API Testing with Swagger / OpenAPI

Document created by John Delaroderie Employee on Mar 23, 2020Last modified by John Delaroderie Employee on Apr 27, 2020
Version 4Show Document
  • View in full screen mode

The Qualys Web Application Scanning module allows users to scan APIs in addition to traditional web applications.  This article will examine testing an API that adheres to the OpenAPI Specification through the use of a Swagger or OpenAPI 3.0 file.


Swagger / OpenAPI Basics

What is the OpenAPI Specification?

Unlike a traditional web application, an API has no link structure to allow users to navigate from one resource to another.  Instead of links, an API is best defined as one or more endpoints.  A common challenge developers have faced in developing APIs is how to describe these endpoints in a meaningful manner that will allow other developers to write code that can interact with them.  The OpenAPI specification was created to address this challenge by providing a standardized description of the various expectations of a RESTful API.  For example, the OpenAPI specification provides a specific file structure to define the different HTTP verbs, paths, parameters, and authentication methods allowed by the API.  By adhering to this specification, developers can easily create applications or other APIs to interact with the endpoints defined by the OpenAPI specification.


The file created to define the structure of the API was originally called a Swagger file.  The first version, Swagger 1.0, was released in August of 2010.  Swagger 2.0 was released in September 2014.  In July 2017, OpenAPI specification rebranded this file structure with their latest release, OpenAPI 3.0


Qualys OpenAPI File Support

Currently Qualys WAS supports both Swagger 2.0 and OpenAPI 3.0 files.


A sample Swagger 2.0 file can be found here: https://petstore.swagger.io/v2/swagger.json

A sample OpenAPI 3.0 file can be found here: http://petstore.swagger.io:8080/api/v3/openapi.json


In this tutorial, Swagger 2.0 and OpenAPI 3.0 can be used interchangeable within WAS. 


Using a Swagger / OpenAPI file in WAS

Currently WAS does not support the direct uploading of a Swagger 2.0 or OpenAPI 3.0 file.  Instead, you must use the online location of the Swagger/OpenAPI file as your "Target Definition" in your web application configuration file.  It much be reachable over the HTTP protocol (http or https) for Qualys to use it for testing APIs.



Crawl Scope for Swagger / OpenAPI Files and APIs

It is important to ensure you have the correct crawl scope defined for the API based on the Swagger/OpenAPI file host entry.  For example, if we are using the Swagger 2.0 file located at https://petstore.swagger.io/v2/swagger.json, we can see the host is also located at the domain petstore.swagger.io. 



Because the domain for the Swagger 2.0 file is the same domain as the domain for the host (the API itself), you can leave the crawl scope as the default "Limit at or below URL hostname" setting as seen below.



However, the Swagger 2.0 file is not required to be at the same domain as the API, and in such cases you will need to modify your crawl scope to "Limit to URL hostname and specified sub-domain" or "Limit to URL hostname and specified domains" as appropriate.  For example, let's take a look at a Swagger 2.0 file with a different host domain:



Here we can see the host domain is now petstore.webservice.io.  Since our Swagger 2.0 file is located at https://petstore.swagger.io/v2/swagger.json and the API is located at a different domain, we will need to adjust our crawl scope.  This is necessary so that the endpoints (URLs) identified in the Swagger 2.0 file are still within scope for Qualys to test.  Without this change, only the Swagger 2.0 file itself will be crawled.  All the API endpoints will be rejected as out-of-scope.  To prevent this, our new crawl scope settings will need to add the additional domain the API is located at:



Authentication Considerations

Authentication and the Swagger / OpenAPI File

If the Swagger 2.0 or OpenAPI 3.0 file is hosted behind authentication, you can configure a Qualys Browser Recorder script (i.e. Selenium Script) to handle form based authentication.  Standard and custom form-based authentication is not recommended.  The reason is that the Qualys WAS engine handles QBR scripts differently than other form-based authentication methods.  Specifically, if we are redirected to a form-based login and you attempt to use standard or custom form authentication, you are now including every link on those login pages as part of your links crawled, and our engine will continue to crawl all links it can find.  This can result in testing much more than you intended.  Using the QBR script instead essentially allows the WAS engine to "skip over" these pages as it executes the script and only crawl the Swagger file.


If your Swagger 2.0 or OpenAPI 3.0 file requires server authentication, Basic, NTLM, and Digest authentication are all fully supported.


Authentication and the API

The Swagger 2.0 or OpenAPI 3.0 specification allows for three different security types:

  1. Basic Authentication
  2. API Key
  3. OAuth2


Basic Authentication

Basic Authentication is set up and handled with a server authentication record exactly the same way you would configure Basic Authentication for a web application.


API Key or OAuth 2 Authentication

For an API Key or OAuth 2, you will need to manually extract a valid session cookie or token and use the Qualys WAS header injection to perform authenticated scans.  Please see Viewing Web Application Response Headers For Validating QIDs  for additional assistance in retrieving session cookies or tokens from response headers.


Per the Swagger 2.0 / OpenAPI 3.0 specification, API Keys can be passed in either through the header or as a query parameter.  In both cases you will need to pass in the appropriate API Key through the Header Injection setting in you API configuration.  However, if passing in as a query parameter, you will be required to use a different format so that the WAS engine can parse it out correctly.


API Key TypeFormatExample
Request Header<name>: <value>X-API-Key: abcdef12345
Query Parameter#X-Swagger-Input-Query-Parameters:<name>=<value>#X-Swagger-Input-Query-Parameters:api_key=abcdef12345


Request Header Example

Query Parameter Example


If using OAuth 2, you will use header injection as outlined above for the request header. 


OAuth2 TokenFormatExample
Bearer TokenAuthorization: Bearer <value>

Authorization: Bearer abcdef12345


Miscellaneous Configuration Settings

Most of the remaining configuration settings can use the default settings.


  1. Progressive Scanning - As needed.
  2. Crawl Settings - N/A.
  3. Redundant Links - Can be leveraged as needed.
  4. Path Fuzzing Rules - N/A (Parsed out of Swagger 2.0 or OpenAPI 3.0 file automatically).
  5. Exclusions - As needed.
  6. DNS Override - As needed.
  7. Form Training - N/A.
  8. Malware Monitoring - N/A.


Scanning Option Profile

Most of the default settings from the "Initial WAS Option" profile can be used here as well, although we do recommend some modifications.


  1. Maximum links to crawl in scope - Set to the maximum value of 8000 links.
  2. Enhanced Crawling - For Swagger/OpenAPI-based API scans, it is recommended to disable this feature.

   3. Smart Scan - N/A.

   4. Brute Force Settings - N/A.

   5. Search Criteria - Core (only applicable tests for APIs will be performed).

   6. Sensitive Content - As needed.


Scanning as API

The steps to launch a scan against an API are identical to scanning a web application.  You can perform a discovery or a vulnerability test using scheduled or on-demand scans.  In most cases you will find that an API vulnerability scan is completed much faster than most of your web application scans.  This is due to the limited number of endpoints most APIs have and the smaller test set performed from the Core detection scope.  Despite shorter scan times, you can rest assured that your API is still being thoroughly tested for vulnerabilities.


QIDs to Review

Once a scan has completed, there are several QIDs in the Information Gathered section of your scan report that should be review to ensure the API scan completed successfully.


150009 - Links Crawled - In addition to the Swagger/OpenAPI file itself, there will be a link crawled for each endpoint path defined in the Swagger 2.0 or OpenAPI 3.0 file. 

150020 - Links Rejected By Crawl Scope or Exclusion List - Any scope issues will be easily identified under this QID.  Remember that the Swagger or OpenAPI file and the API itself do not have to be on the same domain.

150021 - Scan Diagnostics - Always a great resource to review any exclusions loaded, how long each test took, average server response time, total requests made, and other scan details.

150195 - Analysis of Swagger File - This QID will report the entire Swagger 2.0 or OpenAPI 3.0 file found at the Target Definition you specified in the configuration file.  More importantly, it will reveal any problems parsing the Swagger or OpenAPI file as well as any path fuzzing rules defined in the specification.

150197 - Swagger Requests Rejected By Crawl Scope or Exclusion - Similar to 150020, this will list specific API endpoints identified in the Swagger 2.0 of OpenAPI 3.0 file that were not crawled due to an explicit rule to exclude them, such as white listing, black listing, or scope issues. 



Qualys is working to make API testing an integral part of you security testing.  In addition to our Swagger / OpenAPI support, please check out our API Scanning with Postman Collections documentation for additional methods for testing APIs.


API Testing with Postman Collections