Improving Development and Security Collaboration With API Specification Frameworks

September 15, 2021

APIs enable more rapid application development, are integral to microservices environments, and are the core component of the shift left movement. At a high level, shift left means developing and releasing apps quickly while catching security flaws earlier. APIs were originally designed for machine-to-machine communications, and they rely on pointers to achieve the desired functionality or result. APIs were (and are) rarely documented, resulting in lower quality APIs and making it difficult to achieve the goals of catching security flaws earlier. The lack of API documentation impacts security teams equally, making it difficult to test and find security flaws, often until it’s too late.

To help address both the quality and security challenges, organizations are using API specification frameworks like the OpenAPI specification (OAS) to create a centralized API documentation repository. The OAS standardizes API definitions in a language-agnostic and machine consumable format that can be used by development and security teams alike to ensure coding consistency and to uncover potential security gaps before publication or discovery by threat actors.

API Specification Adoption Trends: Slow Adoption, Yet High Perceived Value

In a Pulse survey of 100 executives and CXOs familiar with their API documentation and specifications process, we found that most organizations were in the early stages of specification frameworks adoption, citing numerous barriers including too many priorities. However, the survey does highlight that there is a high value derived from adoption – specifically better quality, security, and group collaboration.

Bridging the Gap with OAS

The OpenAPI specification documents all of the components referenced by the API including servers, methods, endpoints, parameters, requests and their responses. The remainder of the blog will discuss how the documentation of each API component can help developers and security teams improve API coding quality and reduce the number of potential security flaws.

Servers

Depending on the development phase, APIs, like any application are hosted in different environments (e.g., Dev, QA, UAT, Prod). In order to validate functionality and perform initial tests, it is not uncommon to use real customer data in non-production environments. Unfortunately, non-production environments are not subject to stringent testing, resulting in the data being inadvertently exposed to the Internet.

As shown in the code snippet below, the OpenAPI specification allows development teams to document their servers (Development, Staging, Production) and their protocol scheme (HTTPS) to ensure secure communication.

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

As the organizations roll out new servers for an API, they can keep the servers section up-to-date to enable the security teams to properly secure them.

Methods and Paths

Each method and path combination in an API defines the unique business logic or functionality that is going to be exposed to the public as an API endpoint. Examples include account registration or login, updating credit card numbers or user profiles, reviewing past orders, filing an insurance claim, and so on. Quite often developers make mistakes and end up implementing or exposing more methods and endpoints than they intended to, resulting in the introduction of added security risks. For example, in addition to exposing a read only GET endpoint, a developer mistakenly exposes a POST, PUT or DELETE endpoint that can lead to modification or deletion of customer data, an API risk documented as #9 on the OWASP API Security Top 10, Improper Assets Management.

As shown in the code snippet below, the OpenAPI specification has a mechanism to specify all endpoints and methods, which can be used by development and security teams alike to eliminate unintended endpoint exposure.

"paths": {
  "/pets": {
    "get": {
      "summary": "List all pets",
      "operationId": "listPets",
       ...
    },
    "post": {
      "summary": "Create a pet",
      "operationId": "createPets",
      ...
    }
  }
}

Request Parameters

Each resource referenced in an API can take dynamic values from the request using parameters. Just like any other HTTP request, these parameters can be in the path, query or body of the request. The code snippet below shows how an API specification can be used to properly document all required and optional endpoint parameters and lock down all incoming API requests. Any request with additional parameters can be either blocked or stripped out.

"parameters": [

  {
    "name": "limit",
    "in": "query",
    "description": "How many items to return at one time (max 100)",
    "required": false,
    "type": "integer",
    "format": "int32"
  }
]

Like the path and query parameters, dynamic values can be passed in the request body as well. The OAS specifies a way to define the body of the request.

"requestBody":{
  "description":"Create a new pet in the store",
  "content":{
    "application/json":{
      "schema":{
        "$ref":"#/components/schemas/Pet"
      }
    },
    "application/x-www-form-urlencoded":{
      "schema":{
        "$ref":"#/components/schemas/Pet"
      }
    }
  },
  "required":true
}

Response Body

Each API response should be documented with the best practice being to provide as LITTLE information as possible in the response. OpenAPI specification provides a method to specify the response structure and its individual fields. If an undocumented, additional field gets introduced for any reason, it can be flagged by the security tools with the help of this specification.

"responses":{
  "200":{
    "description":"Successful operation",
    "content":{
    "application/xml":{
       "schema":{
          "$ref":"#/components/schemas/Pet"
        }
      },
      "application/json":{
        "schema":{
          "$ref":"#/components/schemas/Pet"
        }
      }
    }
  }
}

Security Schemes

Interestingly, one of the most critical elements in developing an API is one of the flaws that is most commonly exposed or discovered: Broken User Authentication. Classified as #2 on the OWASP API Security Top 10 list, these authentication errors allow attackers to compromise authentication tokens or to exploit implementation flaws to assume other user identities, temporarily or permanently. Compromising a system’s ability to identify the client/user, compromises API security overall.

"securitySchemes":{
  "petstore_auth":{
    "type":"oauth2",
    "flows":{
      "implicit":{
        "authorizationUrl":"https://petstore3.swagger.io/oauth/authorize",
        "scopes":{
          "write:pets":"modify pets in your account",
          "read:pets":"read your pets"
        }
      }
    }
  },
  "api_key":{
    "type":"apiKey",
    "name":"api_key",
    "in":"header"
  }
}

Summary

Shift left critics say that the effort is failing to catch all the security flaws, placing the bulk of the blame on the development team. The reality is that shift left IS working, it IS catching flaws earlier. Even the most perfectly coded API is susceptible to an attack, which is where the security team comes into shield the right. By working with the development team in tandem, the groups can use a specification framework to document the APIs, understand the functionality, collaborate on testing to uncover and remediate possible security gaps before publication or discovery.

Join Shreyans Mehta, Co-founder and CTO of Cequence Security, and Joseph Krull, Senior Cybersecurity Analyst at Aite-Novarica Group for an interactive webinar on how you can leverage API specifications and associated shield right protection mechanisms to improve (not hinder) your shift left efforts.


            
api sentinelAPI Specification ConformanceAPI Specification FrameworksDevOps

About the Author

Shreyans Mehta

CTO & Co-Founder at Cequence Security

It's a wrap on Black Hat 2022
12 August 2022

Black Hat 2022 — End-to-End Fun and API Security

Read More
Network IQ
9 August 2022

Network IQ: How the Largest API Threat Database Protects Your APIs

Read More
Ulta Beauty Reduce Costs - By Blocking API-based Enumeration Attacks
3 August 2022

Ulta Beauty Reduces Costs by Blocking API-based Enumeration Attacks

Read More
Unified API Security Bot Management
29 July 2022

Mergers and Acquisitions in API Security and Bot Management

Read More
API Threat Prevention
26 July 2022

API Threat Prevention and Comprehensive Protection: Part 3

Read More

Subscribe to our blog

Join us for our Weekly Webinar Series: API Best Practices Register now