What is OpenAPI & Does It Improve API security?

The OpenAPI specification framework is one of several tools organizations can adopt to improve API security through higher quality, more consistent coding. At the heart of API specification frameworks is an emphasis on documentation. Documenting topics like how the API should function, what field inputs should be, what type of authentication should be used will go a long way in helping your team deliver more secure APIs. While popular open source standards such as the market-leading OpenAPI specification framework will help organizations adopt API specifications more quickly, IT leaders should understand what the security and development teams are committing to.

Documentation via an API specification framework helps businesses develop consistent, high-quality and secure code. With that said, this practice is far from universal — only 24% of companies use API specifications for every API they work with.

To achieve stronger API quality, easier developer collaboration and a stronger security posture, it’s worth adopting a consistent API specification framework. Popular open source standards such as the market-leading OpenAPI are useful options for companies hoping to adopt specifications. With that said, IT leaders should understand what they’re committing to and make sure their API security options are prepared.

OpenAPI Definition & History

When talking about API specification standards, the discussion needs to start with OpenAPI, because it’s the most common choice of tool for API developers: 63% of teams surveyed by Pulse use this standard — among other schema options, No. 2 is a tie between RAML and API Blueprint, tied at 16%, while 27% of companies have no standard at all.

The OpenAPI Specification (OAS) was formerly known as the Swagger Specification and is designed to provide both human- and machine-readable lists of traits for APIs, in one OpenAPI document or more. The specification has evolved as more tech companies have committed to the related OpenAPI initiative. This process was most intense between 2013 and 2015, and the Swagger Specification evolved into the current, market-leading OAS as Swagger donated its spec to the OpenAPI Initiative.

Now, with more organizations than ever working with this machine-readable and human-readable API specification, it’s a natural choice for companies seeking to standardize their own API documentation in one API description format. Leaders should be aware, however, that the popularity of OpenAPI has also led to a proliferation of common threats specifically targeting the framework and applications that use it.

Pros & Cons of Development with OpenAPI

There is ample potential value in adopting an API specification framework in general, or the OpenAPI Specification specifically. The standardization of API documentation can lead to higher-quality and more secure production code, as well as a streamlined development process.

Within the OpenAPI document, there are a variety of standardized objects that can make it easier to use and test the API in question. For instance, a components object that can be called back to prevent repetitive code, while a security requirement object describes a protective feature in place.

The fact that many development teams haven’t added frameworks is largely due to internal conflicts rather than a lack of perceived worth: Among respondents to the Pulse survey, 57% said they had too many priorities to deal with, while 24% lacked the skillset for implementation. Together, that accounts for nearly four-fifths of non-adopters.

Keeping in mind that there is widespread interest in using OAS and related frameworks, but that this movement hasn’t yet reached critical mass, it’s worth breaking down just how an API development process can change with standardized documentation.

Pros: Five Pillars of Value

There isn’t just one main reason to adopt a standardized documentation framework such as OAS. In the Pulse survey, tech leaders identified five main reasons why they’re interested in using these methods to track APIs. In order of popularity, these are:

• Better API quality: It’s simply easier to release error-free code when the API is described by a clear document that can be understood by both automated tools and human developers.
• Stronger API security posture: Security is one of the major reasons to conform to a standard — it’s easier to assess and enforce security when APIs are being developed to meet specifications.
• Easier collaboration: Standardization and documentation allow team members to contribute to software development with less confusion or need for detailed debriefs.
• Greater consistency: The consistent nature of APIs in production is a major benefit of using OAS to document each one.
• Clear communication of contracts: With OAS standardizing API documentation, it’s simple to share this documentation, knowing the recipient will understand it.

Cons: Not a Silver Bullet

The essential argument against OAS and similar specifications isn’t so much that companies shouldn’t use them, but rather that they should not assume such a schema will allow them to take their API design and development processes for granted. Even with OAS in place, developers must watch out for code mistakes and security threats — especially attacks specifically targeting the APIs’ standardized elements.

The fact is that even if an API’s code contains no obvious mistakes or glaring vulnerabilities, it could still be susceptible to issues, including attacks by bad actors hoping to steal sensitive data transmitted via the API. Developers should understand that no matter how comprehensive, collaborative and standardized their efforts become with the aid of OAS, they will still have to follow API security best practices before and after the code goes live.

Security & OpenAPI

Using OAS can help close security loopholes by creating a readily available and easily readable set of documentation for every API. Understanding each API endpoint and capability helps developers foresee security risks and prevent vulnerabilities from going live, both through manually scanning the contracts and using an automated API testing tool.

This is the good side of API security with OAS, and is a compelling reason to adopt such a standard. On the other side of the coin is the new class of security gaps associated with bad actors actively using centralized API documentation against companies. Having a plan to cope with this new class of threats is an important consideration for any business that has adopted OAS.

Scanning Tools Become Attack Enablers

Some of the same innovations that have made API testing and discovery easier can also become weapons in the hands of bad actors. When companies use API specifications to store documentation in a centralized location, attackers can scan those repositories using basic discovery tools, checking to see if there are any exploitable vulnerabilities among the businesses’ APIs.

Attackers who are looking for specific API endpoints may find it in an organization’s standard documentation, then drill down to see if they can exploit any of the common parameters they find. This type of attack can be quick but devastating. If bad actors find an unsecured directory or command, they can exfiltrate large quantities of sensitive data in a matter of minutes.

Despite the threat posed by this new attack type, the moral of the story is not “don’t use standard API specifications.” The benefits of OAS and similar frameworks — security benefits included — are too great to ignore. Rather, companies have to acknowledge the latest wave of attacks and implement adequate security measures.

Defending Documented APIs

A comprehensive API security strategy can account for a wide variety of possible attack types, negating the new types of avenues attackers may try and take when dealing with centralized API documentation. Modern best practices include:

• Active use of an API spec: Publishing a standardized API spec, stating an application’s goals and operations, is a valuable and increasingly common move. Organizations should store those specs securely, generating less detailed specs for the public if needed. The spec can be used to audit the API’s performance and make sure it’s secure.
• Changing default pathways: If companies don’t keep their admin pages and other data installed alongside a framework in the default locations, it’s harder for attackers to find and exploit those resources.
• Actively guard against scanners: When IT security leaders understand that API scanning tools can be used by attackers, it’s possible to work those utilities into an API security strategy. Guarding against scans as if they were attacks is a way to stave off this class of exploit.

Making Your API Strategy Work

API use is only growing in prevalence today, which means every organization needs to think about how it is using APIs and what it could be doing better. In many cases, this will mean adopting OAS or an equivalent specification framework, which should be accompanied by API security upgrades to make sure that the update doesn’t open new vulnerabilities.

An organization with specifications in its toolset can reap the benefits of easy collaboration and well-documented development processes leading to more stable code in production. While these specifications aren’t universally used yet, their advantages are well known.

As long as API developers are aware of the modern security needs that come with OAS and similar frameworks, they can use them to their advantage, performing automated API testing to make sure their APIs are free of vulnerabilities or suspicious interactions resulting in a stronger API security posture.

Accelerate Your Organization with API Sentinel

To help organizations accelerate the adoption of API specifications, API Sentinel can automatically generate an OpenAPI specification for any of the APIs it discovers. In addition, API Sentinel continuously assesses all APIs, performing specification conformance validation, and flagging out-of-spec APIs for development to fix. To find out where your organization stands in API use and API security and to determine your ideal next steps, request a free API security assessment and demo from Cequence Security.