APIClarity Overview Series: Introduction

Anne McCormick
Anne McCormick

Tuesday, February 28th, 2023

Read Time
5 min read

This blog is part of the APIClarity Overview Series. 

APIClarity Introduction

In this blog, I’ll give an introduction to APIClarity – what it is, what it does, and what it can do for you. Let’s start by looking at the problem set in the API world. 

API Security Breaches

API security breaches are an ever-present threat in today’s cloud-first application world. You don’t have to look far to find one in the news. I created a blog post in the beginning of the year detailing the top five breaches in 2022, and in just those five breaches alone, the data for over 27 million customer accounts was exposed. Some of this data was sold on the dark web or used for ransom or extortion attempts. Some could have even been used for espionage. Direct damage aside, there’s also an incalculable impact on company reputations and branding when data breaches occur. 

The cat is out of the bag in terms of API vulnerabilities being used as attack vectors, but what can we proactively do to protect our cloud-native applications? Read on! 

APIClarity To The Rescue

APIClarity is a cloud API observability open-source project that provides functionality to discover and monitor any API traffic that interacts with modern applications and report suspected security weaknesses or possible abuses. It includes a UI dashboard for easy API management and monitoring. 

How It Works

Another blog in this series will cover the architecture of APIClarity in depth, but for now, let’s explore a high-level overview of how it works. 

APIClarity_K8s Cluster

APIClarity runs as a pod deployment in a Kubernetes cluster, shown on the right of the diagram (in green) above. The user can upload OpenAPI specifications (referred to as OpenAPI specs in this blog) from the UI to APIClarity and approve reconstructed OpenAPI specs from the UI. API events, security findings, reconstructed API specs and spec differences that are reported by APIClarity are all visible in the UI. 

To capture API traffic to an application (i.e. external API calls), APIClarity integrates with API gateways and external traffic sources to tap the traffic and send it to the APIClarity pod. Tyk and Kong API gateways are shown in the diagram above with an APIClarity plugin for this purpose. 

To capture API traffic within an application (i.e. internal API calls between microservices), APIClarity integrates with service meshes at the envoy proxy level (shown as a purple square in the diagram representing a WebAssembly filter) to forward traffic to APIClarity. Istio and Kuma service meshes are currently supported. 

What It Does

Let’s take a look at the functionality of APIClarity. 

API Discovery 

The first step to securing application APIs is to properly catalog and document them, and the de facto standard for API documentation is the OpenAPI spec. 

If an application already has valid OpenAPI specs for all of its APIs, those specs can be uploaded into APIClarity. However, many applications that are currently deployed to the cloud do not have OpenAPI specs for all the APIs that have access to the applications and the data. In this case, APIClarity will monitor API traffic and reconstruct OpenAPI specs based on the observed calls. The reconstructed specs can then be reviewed, approved and downloaded.  

Once valid OpenAPI specs are available by either uploading or reconstructing and approving them, APIClarity compares ongoing API calls against the specs and reports any discrepancies. This leads us to the next section: monitoring. 

API Monitoring 

The initial discovery of APIs is important, especially if OpenAPI specs need to be reconstructed, but it is paramount that API usage is continuously observed and monitored in real-time within the cloud environment, and that any suspected abnormalities are flagged and reported. 

There are many kinds of API usage abnormalities that can be detected and reported by APIClarity. 

Shadow APIs 

Shadow APIs are undocumented APIs that are allowed to gain application access. Because they are undocumented, they aren’t controlled and thus can’t be adequately secured.  

Shadow API attacks are on the rise and represent a significant attack vector for cloud-native applications. 

In order to detect shadow APIs in an application, APIClarity uses the approved OpenAPI specs for comparison with ongoing API traffic and reports any API calls that aren’t found in the specs as shadow APIs. If the reported APIs are valid, they can be added to the specs. If not, support for them can be removed from the application, thus closing the security vulnerability. 

Zombie APIs 

Zombie APIs are older, deprecated versions of APIs that are still functional and accepted by an application. Thus, even if newer API versions are tightened up and secured, zombie APIs can circumvent the newer requirements. This can weaken an application’s security posture, leaving a potential threat landscape unguarded indefinitely. 

Similar to shadow API detection, APIClarity compares API traffic against the approved specs, and reports any deprecated API usage as zombie APIs. These “undead” APIs can then be made obsolete, and access to the application and data removed. 


BFLA (Broken Function-Level Authorization) occurs when an API call gains access to application functionality that it’s not authorized to access. This can cause sensitive data, such as Personally Identifiable Information, or PII, to be leaked. A major API data breach in 2022 was due to a BFLA exposure. 

APIClarity includes a BFLA detector that can learn and build an authorization model, which can then be used to detect unauthorized access to application functionality in real-time. 


BOLA (Broken Object-Level Authorization) occurs when an API call gains access to application data that it is not authorized to access. Like BFLA, this can lead to PII or other sensitive data breaches. Several major breaches in 2022 were due to BOLA (for example, this major social media breach). 

APIClarity has a trace analyzer that can be used to detect potential BOLA issues and sensitive data leaks in API requests/responses. It includes Non-Learnt Identifier (NLID) capabilities that detect if an object identifier is given in a request without first being provided in a response, suggesting that the identifiers are being guessed external to the application. 

Weak Authentication 

The APIClarity trace analyzer, mentioned above, can be configured to detect weak authentication in API call traces, such as short passwords, passwords that are well-known or easily guessed, weak/guessable object identifiers, etc. The trace analyzer can perform API scoring, reporting any low, medium or high-level security concerns.  

Sensitive Data Leaks 

The trace analyzer can also help detect sensitive data leaks in APIs, such as PII. Think name, address, email, phone number, social security number, bank account numbers, passwords, etc.

Data Injection Risks 

Data injection attacks involve feeding unauthorized data into an API as input, which could in turn be processed and alter the execution of an application. The malicious data could be code, a script, SQL statements, security tokens, etc. If API input is not sufficiently validated, this can create a huge security risk. 

APIClarity includes fuzzer technology that can be used to test API endpoints for any weaknesses in input validation and processing. 

Traffic Sources 

As mentioned, APIClarity integrates with many types of traffic sources to monitor API traffic. The current list includes: 


APIClarity can be used to discover, document, monitor and harden APIs, which is essential in our cloud-first, always-available world of modern applications. And as an open-source project, you’re free to use it, contribute and help us make it even better. Join us! 

Next up in the overview series, we’ll talk about the architecture of APIClarity.

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