x-42c extensions for API Protection and API Firewall
The x-42c
vendor extensions by to the OpenAPI Specification (OAS) enable you to enrich your OpenAPI definitions with security information for API Firewall and provide additional operation instructions to API Firewall.
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
Extensions can have different scope depending on which level in your OpenAPI definition you add them:
- Global level: The extension applies to the whole API: all paths, operations, and responses.
- Path level: The extension applies to a specific path, including all operations and responses defined in it.
- Operation level: The extension is applied to a specific operation and its responses.
- Response level: The extension is applied to all responses defined for an operation.
- Status level: The extension is applied to a specific HTTP status code or the
default
response.
# ... paths: /apis: x-42c-local-strategy: x-42c-strategy: protections: - x-42c-request-limiter_0.1: # path level # ... get: x-42c-local-strategy: x-42c-strategy: protections: - x-42c-request-limiter_0.1: # operation level # ... parameters: # ... responses: x-42c-local-strategy: x-42c-strategy: protections: - x-42c-security-headers_0.1: # response level # ... 200: x-42c-local-strategy: x-42c-strategy: protections: - x-42c-security-headers_0.1: # status level # ...
Security extensions
The security extensions control what security measures API Firewall applies to API traffic. For the most part, they define what protections are applied and where. They are used by API Protection when it builds the sequences of actions for incoming requests and outgoing responses in the protection configurations.
For more details on security extensions, see Protections and security extensions. For instructions on how to use these extensions in your OpenAPI definitions, see Apply additional protections. For the descriptions of available protections and their x-42c
extensions, see Protections.
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
x-42c-local-strategy
The extension x-42c-local-strategy
defines a list of protections that API Firewall applies to a particular API operation or response, in the order in which they are listed. The protections are applied as strategies, so x-42c-strategy
is always nested inside this extension.
You can choose when a local strategy is applied depending where in your API definition you add it. The scope of the extension changes as follows:
Location in your API definition where you add the extension | Impact |
---|---|
Directly under paths |
The local strategy is applied only to requests to all paths and operations (methods). |
Directly under a specific path | The local strategy is applied to requests to all operations. |
Directly under a specific operation in a path | The local strategy is only applied to requests to this particular operation. |
Directly under responses |
The local strategy is applied to all HTTP status codes and default response. |
Directly under a specific response | The local strategy is only applied to this particular response. |
Local protections override protections applied on a higher level in your API. For example, if you have applied a protection both to a response and a particular HTTP status code, the protection applied to the status code will override the protection applied to the response.
Example
/api/user/info: get: x-42c-local-strategy: x-42c-strategy: protections: - x-42c-request-limiter_0.1: key: req_limiter_login hits: 2 window: 10 # ...
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
x-42c-request-strategies
The extension x-42c-request-strategies
declares protections on a global level, meaning that they are applied to all incoming requests to your API. The protections are applied as strategies, so x-42c-strategy
is always nested inside this extension.
You can further specify which operations (GET
, POST
, DELETE
...) you want to apply the protections to. In this case, the protections are only applied to the listed operations. For more granular control, use the extension x-42c-local-strategy
to apply protections locally to individual paths or operations.
Example
#... x-42c-request-strategies: - operations: - post - put x-42c-strategy: protections: - x-42c-request-limiter_0.1: key: req_limiter_login hits: 3 window: 15 # ...
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
x-42c-response-strategies
The extension x-42c-response-strategies
declares protections on a global level, meaning that they are applied to all responses sent back to the API consumers. This can be useful to prevent data leaks or enhance requests, for example, with security headers. The protections are applied as strategies, so x-42c-strategy
is always nested inside this extension.
You can further specify which responses you want to apply protections to. In this case, the protections are only applied to the responses listed for it. You can define a list of HTTP status codes as explicit codes (200
, 404
, 500
...) or a range (1XX
, 2XX
, 3XX
, 4XX
, 5XX
), or even default
. Protections defined for explicit codes override protections defined for a range.
For more granular control, use the extension x-42c-local-strategy
to apply protections locally to individual responses or statuses.
Example
#... x-42c-response-strategies: - status: - default - 200 - 5XX x-42c-strategy: protections: - x-42c-security-headers_0.1: hsts.max_age: 7200 csp.policy: 'default-src: ''self''; upgrade-insecure-requests; block-all-mixed-content' mode: add-replace # ...
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
x-42c-strategy
The extension x-42c-strategy
contains the list of protections that API Firewall applies to requests or responses, in the order in which they are listed. The extension indicates where a section on security measures begins. Protections are applied as strategies, so you always define them under this extension.
The extension x-42c-strategy
is always nested inside the extensionx-42c-local-strategy
, x-42c-request-strategies
, or x-42c-response-strategies
. This way, API Firewall always knows if the protections apply on a global level to all requests and responses, or locally to a particular API operation or response. You never use x-42c-strategy
on its own.
For the descriptions of available protections and their x-42c
extensions, see Protections.
Example
/api/user/info: get: x-42c-local-strategy: x-42c-strategy: protections: - x-42c-request-limiter_0.1: key: req_limiter_login hits: 2 window: 10 # ...
The basic rules for the extension syntax apply to references to the reusable protections:
/api/user/info: get: x-42c-local-strategy: x-42c-strategy: protections: - $ref: '#/x-42c-components/x-42c-protections/my-reusable-ratelimiting' - $ref: '#/x-42c-components/x-42c-protections/my-reusable-jwt' # ...
Other extensions for API Firewall
You can use the following vendor extensions in your API definitions to provide additional instructions to API Firewall. These extensions are not used by API Protection when it builds the protection sequences for protection configurations, but they can change how API Firewall treats the data it receives.
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
x-42c-caseless-paths
Define should API Firewall treat file paths exposed in the OpenAPI definition of the protected API as case-sensitive or not. The default value is false
.
Different systems take different approach to the case of paths in a file system:
- If file paths are case-sensitive, this means paths like
/Sample
,/sample
, and/SAMPLE
are all treated as three separate paths. - If file paths are caseless (not case-sensitive), this means that
/Sample
,/sample
, and/SAMPLE
are treated as one and the same path.
If your API exposes caseless paths of a file system (for example, client-side, server-side, or from a cdn) in its OpenAPI definition, you can use this extension in your API definition to indicate to API Firewall how the case in paths should be treated:
- If set to
false
, API Firewall considers file paths in the API to be case-sensitive. This is the default option. - If set to
true
, API Firewall considers file paths in the API to be caseless.
You can apply this extension to the global level in your API definition:
openapi: 3.0.0 info: # ... x-42c-caseless-paths: true servers: # ...
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
x-42c-forward-options
Set API Firewall to allow OPTIONS
calls to proceed even if the API does not explicitly define the OPTIONS
method. The default value is false
.
Cross-origin resource sharing (CORS) allows a server to indicate to browsers to load resources from another origin (such as domain or port) than the one that the server itself exposes. As part of CORS, browsers can send an OPTIONS
request to query the supported methods before sending the actual request to access the resources.
To simplify CORS handling, you can use this extension to direct API Firewall to let these pre-flight OPTIONS
requests proceed to the protected API even if the OPTIONS
method was not explicitly defined in its OpenAPI definition. When enabled, API Firewall allows the incoming OPTIONS
request to pass through to the API and then forwards the outgoing response from the API back to the API consumer without the processing them in any way.
You can add the extension to your API globally at the top level, or locally to individual operation
objects as required.
openapi: 3.0.0 info: # ... x-42c-forward-options: true servers: # ...