Outshift Logo


3 min read

Blog thumbnail
Published on 04/12/2023
Last updated on 04/17/2024

APIClarity: Detecting Shadow APIs


APIClarity_Detecting Shadow APIs

This blog is part of the APIClarity How-To Series.

Detecting Shadow APIs

In this blog, I’ll demonstrate how APIClarity detects and reports shadow APIs for an application. For review, a shadow API is an undocumented API that is accepted by an application and can present a potential attack vector. As mentioned previously, attacks via shadow APIs are on the rise. Therefore, detecting them and either properly documenting and securing them or shutting them down is increasingly important. 

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.

In order to illustrate APIClarity reporting a shadow API, I've uploaded an OpenAPI spec for the catalogue service, but this time I’ve removed one of the catalogue APIs from the spec before uploading it. The missing catalogue API endpoint is "/catalogue/{id}."  

Figure 1 shows the list of uploaded catalogue API endpoints for my setup.

Figure 1: Uploaded Catalogue API Endpoints

Note that "/catalogue/{id}" is not in the list. Compare this to Figure 6 in the upload blog. When I generate traffic that uses this API, APIClarity will report it as a shadow API, because it is unknown in the uploaded OpenAPI spec. See the "Generate Traffic" section of the installation blog for details on how to generate traffic.

Detecting Shadows 

In order to detect shadow APIs, APIClarity first needs to know the list of acceptable APIs for an application. This can either be from an uploaded OpenAPI spec, or a reconstructed one

After an OpenAPI spec is approved, APIClarity will compare incoming API requests against it. If any API requests are for an unknown endpoint, they will be reported as shadow APIs.  

APIClarity displays this symbol for shadow APIs:


Shadow APIs will be reported on the APIClarity dashboard UI (if they happened recently), or from the API Events UI.  Below is an example of a shadow API being reported on the dashboard (circled in green in Figure 2). 

Figure 2: Shadow API Reported on Dashboard UI

And this is an example API event being reported as a shadow API (circled in green in Figure 3). 

Figure 3: Shadow API Reported for API Event

Bringing Shadows into the Light 

If an API that is considered a shadow API by APIClarity is actually expected, you can “legitimize” the API by either uploading an OpenAPI spec that includes that API endpoint, or by accepting the reconstructed spec that includes it. Note that any API calls that occurred before the API became legitimate will still be marked as shadows in the event list. 


We’ve now seen how to detect shadow APIs with APIClarity, and how to mark those APIs as legitimate if needed.  

Next up in the blog series, we’ll take a look at using APIClarity to detect zombie APIs! 

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

Subscribe card background
Subscribe to
the Shift!

Get emerging insights on emerging technology straight to your inbox.

Unlocking Multi-Cloud Security: Panoptica's Graph-Based Approach

Discover why security teams rely on Panoptica's graph-based technology to navigate and prioritize risks across multi-cloud landscapes, enhancing accuracy and resilience in safeguarding diverse ecosystems.

the Shift
emerging insights
on emerging technology straight to your inbox.

The Shift keeps you at the forefront of cloud native modern applications, application security, generative AI, quantum computing, and other groundbreaking innovations that are shaping the future of technology.

Outshift Background