The OpenAPI Specification (OAS) (formerly known as the Swagger specification) provides a way to describe and document REST APIs and their components. It includes details on endpoints, their operations, parameters needed for the operations, expected responses for every operation, authentication methods and even annotations. OAS is an easy format to learn and read, and can be understood by both humans and machines. As you might imagine, this kind of “accessible” documentation is useful and beneficial in a number of different use cases for both development and security teams.

Developer Relationships With OAS

For developers, OAS can be used to generate documentation for APIs. Proper documentation can help other developers figure out how best to integrate and use these APIs with their own application.

Even so, many developers have a love/hate relationship with OAS. Let’s face it, documenting is a far cry from developing. Although it is easy to learn, the actual act of documenting is tedious, manual and time consuming. Frankly, it’s probably one of the least glamorous parts of a developer’s job, and, therefore, many developers only do the absolute minimum. As a result, OAS can be incomplete or, in some cases, missing entirely. Not to mention, when the API is updated, how often is the OAS updated, too?

In the case of incomplete or nonexistent documentation, developers will muddle through with trial and error, even though this can slow down the development process.

If out-of-date OAS proves an annoyance for dev teams, what’s the impact on security?

Security’s Relationship With OAS

OAS can be consumed by both humans and machines, and both are critical for security’s use of OAS.

OAS helps security teams (humans) become aware that the API exists, since its documentation is often part of the CI/CD process.

By examining an OAS file, a security team can understand what the API is supposed to do and, from that, determine if it conforms to or violates the organization’s security policy. As an example, security teams might use the OAS to make sure that authentication and authorization are being implemented correctly, and that sensitive data, like PII, is not being exposed.

Security teams might also deploy tools (machines) that use the OAS to enforce policy based on what’s in the documentation. As an example, the OAS may specify that, for a particular parameter, a string should be expected; it should be no more than four characters and it should contain only letters and numbers with no special characters. By validating input based on what is defined in the OAS, security tools can check that the API does what developers intend it to do.

This plan sounds great on paper, but …

Perception versus Reality

Imagine a perfect world, in which every API is well-documented as part of the development process. As that API makes its way through the development pipeline, it does so hand-in-hand with an associated OAS. At the appropriate time, before production, security is made aware of the API and the OAS, the team evaluates the details, validates that the API matches policy, gives the thumbs up and the API goes into production. Security and development teams live in harmony and everyone is happy.

We don’t live in a perfect world. Instead, we must deal with questions such as:

• Does the OAS exist? In the most extreme cases, the OAS doesn’t even exist. It was never created as part of the development process, so it can’t be used for any sort of awareness. These misses happen more often than you think, giving rise to the problem known as shadow APIs. These APIs slip through the cracks, and make it into production with no documentation at all. While you might be saying to yourself, “Our company would never let this happen!” you should also consider that numerous APIs are stood up by development teams as a test, as part of a beta or as a quick-and-dirty way to get something done. There are more of them than you think, and these shadow APIs create unrealized risk.
• Is the OAS complete? In slightly less-scary territory, let’s consider an incomplete OAS. You might be saying to yourself, “We have a top-notch development team, well-defined development processes and strict policies around documentation. No API makes it into production without an OAS!” Perhaps, but the devil is in the details, and those details are often missed. I’ve worked with countless customers who have happily and confidently produced an OAS in which critical details don’t match the reality of the API. Sometimes they’re not complete. Sometimes they’re missing all together. The industry calls these missing details shadow endpoints. Yes, someone did produce an OAS, and security was aware of the API, but a lot of critical detail is missing.
• Is it being kept up-to-date? Development cycles seem to be moving faster and faster, and as documentation is one of the least glamorous parts of a developer’s job, updates can be missed, dismissed or, at the very least, lag behind. We commonly see multiple versions of an API, and the OAS does not reflect the new capabilities of the latest version.

While a non-existent or outdated OAS presents a modest concern for API visibility, it creates a substantial concern when trying to serve as the foundation for API security.

You take a huge risk if you depend solely on OAS for security. More often than not, an OAS is not accurate, lacks critical details and is only as useful as the data you feed into it. Gaps, including shadow APIs, leave out critical details, making enforcement impractical.

The inaccuracy of OAS leaves customers with two choices. You can either enforce security policies based on strict adherence, and risk blocking legitimate traffic, or you can enforce based on loose adherence and risk letting attacks through. In either scenario, your organization is unduly vulnerable, and significantly less secure than your dev teams intended or your security teams would like.

OAS is Only a Starting Point

OAS provides a great starting point for documenting your APIs. Don’t make the mistake, however, of basing your API security strategy on what’s in your OAS. It’s simply not accurate enough. Taking that approach will leave your company’s vital data and services at the mercy of API attackers who will quickly know more about your APIs and what they expose than your OAS does.