Uploading an OpenAPI Specification

In this blog, I’ll show you how to upload an OpenAPI spec to APIClarity to bolster your API security. To recap, an OpenAPI spec is a standard way to document an API and APIClarity uses it to compare incoming API traffic against what’s expected and allowed. An OpenAPI spec can either be uploaded, or APIClarity can reconstruct one from observed traffic (we’ll cover this in the next blog). 

Behind the Scenes 

Throughout the APIClarity blog series, we’ve been using Sock Shop as our sample microservice application. See the installation blog for specifics on setting up APIClarity with Sock Shop.

Sock Shop has API specs for each microservice, but they aren’t quite in OpenAPI format.  

Let’s start with this (for the catalogue service): https://github.com/microservices-demo/catalogue/blob/master/api-spec/catalogue.json. 

I converted it to OpenAPI3.0 here: https://editor-next.swagger.io/. Next, I set the version for the catalogue API spec ("1.0.0"). This is what we’ll use for our example. 

Upload the Spec 

In the APIClarity UI, go to the API Inventory tab (circled in green in Figure 1 below).

In the API inventory list, select the one for your microservice application. In this case, we’ll select “catalogue.sock-shop” (circled in green in Figure 2). 

On the next screen, click “browse” (circled in green in Figure 3) to upload your OpenAPI spec file. 

If there are any errors in the spec file, they’ll be reported here. Click Finish (circled in green in Figure 4).

Once the API spec is uploaded, you can either look through the APIs directly on the APIClarity UI or in Swagger. Click on "default-tag" (circled in green in Figure 5) on the APIClarity UI.  

You’ll see a list of API endpoints and parameters. Click the arrow next to one of them (Figure 6). 

If you click on a particular endpoint, you’ll see a “hit count” graph of the number of times the API has been called (e.g. Figure 7). 

To see the API spec in Swagger, click on "see on Swagger" (circled in green in Figure 8 below). Note that no information is leaving your Kubernetes cluster in order to get to the Swagger UI. Everything stays local to the cluster. 

Each API endpoint is listed in Swagger (e.g. Figure 9). 

Click on each endpoint to see example request parameters and an example response (e.g. Figure 10). 

At the bottom, in the Schemas pane, each API response schema is provided (e.g. Figure 11). 

Provided Spec

Now that an OpenAPI spec has been uploaded, you can see it listed as a “Provided Spec” on the API Inventory screen (in Figure 12 below, the “catalogue.sock-shop” APIs are listed as having a provided spec). 

Spec Differences 

Now that the OpenAPI spec for the catalogue application has been uploaded, APIClarity can detect spec differences between the uploaded spec and the observed API traffic.  

APIClarity reports spec differences in the UI with this symbol:  

If you’ve really been paying attention in this blog, you may have seen spec differences being reported in some of the UI screens above. 

In my testing, a spec difference was reported in the API Events tab (circled in green in Figure 13). 

There’s a spec difference warning in the “Spec Diff” column (Figure 14).  

If I click on that row, I can drill down into the specific catalogue API call that had an unexpected spec difference (Figure 15). 

Here, we can see that the "/catalogue/{id}" API was called without specifying an ID, which is a required parameter for the API.  Worse than that, the catalogue API returned a 200 (OK) response and actually listed an object ID. This is a potential Broken Object-Level Authorization (BOLA) attack, because an object ID was given in a response without first being requested. We’ve found our first data leak and BOLA!  We’ll talk about BOLAs in more detail in a future blog on the APIClarity Trace Analyzer. 

The good news is that Sock Shop is just a demo application, but it’s pretty cool that APIClarity found a weakness in its API security. Hopefully you’re not using Sock Shop to sell socks in the cloud. 

Conclusion 

Congrats, you have now uploaded an OpenAPI spec to APIClarity! 

Next up in the blog series: Reconstructing an OpenAPI Spec (for those applications that don’t already have one, which is many of them). 

---

Anne McCormick is a cloud architect and open-source advocate in Cisco’s Emerging Technology & Incubation organization.