Is OAS Enough For API Security?
The OpenAPI Specification (OAS) (fka Swagger Specification) is a way to describe and create API documentation for REST APIs along with their components such as details on endpoints, their operations, parameters needed for the operations, expected responses for every operation, authentication methods, and annotations. The OAS is an easy format to learn and read, and both humans and machines can consume its data, making it applicable to a number of use cases. For this post, we’ll cover some of the ways development and security teams use the OAS and why it falls short when it comes to securing your APIs.
How Development Uses the OAS
Developers use the OAS to generate documentation for APIs such as OpenAPI specification files and OpenAPI definition files. This documentation helps others understand the structure of the API and functionality which is useful when another developer wants to integrate an API to add functionality to their application.
Many developers have a love/hate relationship with the OAS since any time spent on documentation is time lost on development. The OAS is easy to learn, but documentation is inherently tedious — it’s manual, time consuming and one of the least glamorous parts of a developer’s job. As a result, developers typically do the absolute minimum, leaving documentation incomplete, inaccurate, or, in the worst of cases, non-existent.
How Security Uses the OAS
OAS documentation helps security teams discover that an API exists and understand what the API is supposed to do. With the documentation, security teams can determine if the API conforms to or violates policy. As an example, security might use API documentation to make sure that the dev team has implemented authentication and authorization correctly and not unnecessarily exposed sensitive data like PII.
Security teams can also use OAS-based security tools to align with what developers intended the API to do by validating API input based on what is defined in an OpenAPI definition file and enforce policy.
Learn why OAS-based security tools address a small fraction of API risks and can't prevent API breaches.
Download NowUsing the OAS for API Discovery and Policy Validation
In a perfect world, every API is well documented as part of the development process. Security is made aware of the documentation and API before it goes into production, so they can evaluate the details, validate the API matches policy, and approve for rollout. Because none of us gets to live in the perfect world, consider the following questions:
Does OAS documentation exist? In the most extreme cases, the documentation doesn’t exist, so it can’t be used for any sort of awareness. The company is left with Shadow APIs and unrealized risk.
Is the OAS documentation complete? Every environment we’ve ever seen? No. Our customers confidently produce their documentation, our platform analyzes the same environment, and the documentation doesn’t match reality. Gaps span everything from documentation not being complete to missing critical details, as the following example highlights, where OAS (Swagger) documentation noted 2 parameters and we found 27:
In addition to missing 25 parameters, the OAS documentation also lacked key insight into where PII was being exposed, leaving the company exposed.
Is the OAS documentation being kept up to date? Rapid development practices mean that APIs are constantly changing, and updating the documentation always lags behind.
Using OAS-based Security Tools to Secure APIs
Companies can also use OAS documentation as a schema to validate API input, applying an OAS-based security tool to ensure the input conforms to what’s defined in the OpenAPI definition file. For example, the OpenAPI definition file may specify that a string should be expected for a specific parameter, that string should be no more than a specified length, and should contain only letters, numbers, and no special characters. Anything that falls outside of that definition will be blocked.
OAS documentation that is non-existent, inaccurate, and out of sync makes API inventory and discovery challenging, but it presents a significant risk when it comes to enforcing security.
Depending solely on OAS documentation for security, even with accurate documentation, will cover only a small percentage of the risk created with APIs and therefore will not prevent API breaches or data loss. Relying on OAS documentation can also negatively impact your customers, partners, and business operations, including revenue streams, by blocking legitimate traffic.
The following are the risks when depending on OAS documentation for securing your APIs:
OAS-based security tools cannot protect against the most common and critical API threats. The OAS lacks understanding of API logic, so it’s impossible to create policy in an OpenAPI definition file to prevent attacks targeting API logic such as the top threats defined in the OWASP API Security Top 10.
OAS-based security tools can be tricked and bypassed. The OAS lacks context of overall attacker activity and therefore can block only a specific API call, not the attacker, allowing attackers to make endless attempts to bypass OAS-based schema validation.
OAS-based security tools documentation risks blocking legitimate traffic. Applying the Strict Validation technique blocks any abnormal API call, including a parameter value pattern mismatch, unknown parameters, or unknown endpoints. This approach will result in blocking legitimate traffic when APIs are improperly documented.
OAS-based security tools risk missing attacks. Applying the Loose Validation technique with a generic and very broad contract, such as having no pattern definitions or using generic data types such as “string,” will allow many malicious API calls to pass through validation.
Conclusion
OAS-based documentation is useful for both development and security teams if it’s accurate, but the OAS and OAS-based security tools have inherent shortcomings that limit protection to only a small percentage API risk. Depending on OAS documentation and OAS-based security tools to protect your APIs will not prevent API breaches or data loss.
Visit https://salt.security/demo/ to learn how Salt Security can help improve your OAS-based API documentation efforts and provide full coverage of API threats.
