Enforcing API Schema Specifications in Imperva

By Peter Klimek posted 20 days ago

Space pic...

APIs are designed to expose certain functionality to be used by automated programs.  An API’s schema serves as a “contract” for how an API’s clients should interact with an API making it a valuable tool to an organization’s customers.  Unfortunately, this usefulness also makes it extremely valuable to attackers as well, especially when the underlying API does not appropriately enforce the parameters that are defined in the API schema.  With Imperva, it is possible to enforce the terms of this contract, protecting the API against attack.

What is an API Schema?

An API schema is a design document of an API.  It outlines exactly what the API is designed to do and what are considered legitimate API operations.  Different APIs have different options for schemas, some common API schema types for REST APIs are Swagger and OpenAPI.  An API schema is optional, but it can provide a very useful structure to an API as it defines what types of operations are permitted (create, read, update, and delete) and on what resources.  In RESTful APIs, the operations typically correspond to the HTTP methods (e.g. GET, POST, PUT, PATCH, and DELETE) and the resources correspond to the endpoint (e.g. /user, /accounts, /user/123)

Depending on the organization, API specifications can be written manually or automatically based upon code.  Having a schema created for an API makes it possible to enforce this schema as a contract between the API server and its clients allowing developers to leverage a “Design by Contract” (https://en.wikipedia.org/wiki/Design_by_contract) design pattern.

By defining an API schema and loading it into Imperva, it is possible to automatically block any traffic to an API that does not match the schema definition, which allows this contract to be enforced.

Watch this video on The Differences Between API Security Schema Types

Enforcing an API Schema in Imperva

Imperva enables users to enforce the terms of their API schema with a high level of granularity.  Initially, it is possible to define a general enforcement action that is applied to all requests to a particular API if they violate the schema specification.  After defining this general rule, it is possible to modify the enforcement actions for each endpoint within the API to better meet its unique security requirements.

Setting Up Schema Enforcement

On a website’s page within the Imperva dashboard, open the APIs view.  If APIs have already been added to this webpage in Imperva, they will appear here.  If so, select the More menu (three vertical dots) within the appropriate API’s row and click Edit.  Otherwise, click the Add API button.

Whether adding a new API or editing an existing one, you should see the window shown above.  This window has a few different input fields:

  • Import API: Click the Choose File button and select the schema associated with this API.
  • Swagger Description: This provides a description of the API from a Swagger schema file.
  • API Specification Violation Action: This determines what action should be taken if a request is detected that violates the API schema.

After importing the API schema, select an API specification violation action.  The options are:

  • Alert Only: If a request violates the schema definition, an alert will be raised.  However, the request will be permitted to continue on to the API.  This is best when testing new rules in development but should not be used in production as it provides no real protection.
  • Block Request: This action will block any request that violates the API schema.  This is the right choice in most cases since it blocks misuse of the API.
  • Block User: If a request is detected that violates the API schema, the user will be blocked from making any further requests.  This essentially revokes the user’s API key and should only be used in situations where this is appropriate, such as a violation of the API’s user agreement.
  • Block IP: If a request violates the API schema definition, then this action will block any further requests from the source IP address.  This option is designed to deal with the case of a compromised endpoint, blocking any traffic from the system (regardless of the API key used) while continuing to permit the use of the same API key from other endpoints.  A logical use case for this action would be if a system was observed performing a credential stuffing attack against an API.
  • Ignore: This action does nothing if a request violates the API schema.  It provides no benefit but can be used to disable a rule without deleting it.

In most cases, we recommend starting out in an “Alert Only” mode to ensure the development team has not made any unintentional errors in their schema.  Once the team is confident that the API is operating as expected without unintended errors, we recommend using the Block Request option as the best choice for a general schema enforcement action.  More specific actions can be applied to particular pages within a site.

Modifying Enforcement Actions

The actions defined at the API level apply to the entire API.  However, it may be desirable to have different enforcement actions for different endpoints within the API.  To modify the API schema enforcement actions at the endpoint level, click the arrow button at the left of the API’s row in the main API view.

The image above shows the API view for a sample API.  As shown, it includes seven different API endpoints.  By default, each of these endpoints have the Block Request enforcement actions enabled by default, except the /social endpoint which has been changed to “Alert Only”.

From this view, it is possible to modify the enforcement actions for each individual endpoint.  This makes it possible to define actions based upon the importance of the particular endpoint.  For example, including a Block IP action might make sense for login pages that are potentially the target of credential stuffing attacks but not for the rest of the API.

Enforcing API Schema Specifications with Imperva

An API schema outlines the terms by which an API client should interact with an API.  Defining such a schema enables an organization to ensure that sensitive or vulnerable functionality is only accessible to legitimate users in certain ways.

However, simply writing an API schema specification provides little benefit if it is not enforced.  Imperva enables organizations to enforce their API schemas by blocking requests (or taking other actions) that do not meet the schema specification.  This provides an easy and accessible way to dramatically reduce an API’s attack surface and exposure to potential exploitation.

Learn More with Imperva Community 

The Imperva Community is a great place to learn more about how to use Imperva cyber security technologies like API Security,  Cloud WAF,  Advanced Bot ProtectionDDoS Protection, and more to establish efficient, secure processes for enterprise networks. Rely on the expertise of Imperva partners, customers and technical experts.

Related Content: 
Creating Custom Error Responses for APIs