x-42c extensions

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 instructions to other features in 42Crunch API Security Platform.

Extension scope

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.

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
                    # ...

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
            # ...

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
            # ...

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

You can use the following vendor extensions in your API definitions to provide additional instructions to API Security Audit or API Conformance Scan. These extensions are not used by API Protection when it builds the protection sequences for protection configurations.

Extensions for Security Audit

Allow using empty security requirements (security: []) to indicate that an API operation does not require authentication. Security Audit runs authentication checks normally, but any empty security requirements found are not flagged as issues and do not reduce the audit score.

Pay attention that security requirements are left empty only where authentication really is not needed: if you allow empty security requirements, Security Audit treats all of them as intentional omissions, not mistakes, so you cannot rely on the audit to catch any that you simply forgot to fill.

The default value is false, meaning that Security Audit considers all empty security requirements as errors.

Although somewhat similar to x-42c-no-authentication, this extension offers several benefits that make it the recommended option for relaxing authentication checks where needed:

  • You can use the standard method, as defined by the OAS itself, to control when authentication is not needed: by explicitly defining and empty security object as you design your API operations, you explicitly state that no authentication is required here. Using the standard OAS way also means that, for example, third party scripts correctly recognize it.
  • Because the security objects now control when authentication is not needed and when it is, you only need to apply x-42c-accept-empty-security to your API once on the global level, not individually to every operation that you want to exclude.
  • Because the extension is applied only on global level, you can define it in an audit rule instead of hard-coding it to your API definition. This makes it easier to see which APIs it has been applied to.
  • More control over security: security in your API in general stays active, and is only explicitly deactivated where the empty security object is declared in an API operation.

This extension is always applied to the whole API, so it affects all operations in it. You can define this extension in an audit rule in 42Crunch Platform (see Customizations), or apply it on the global level directly in your OpenAPI definition. Extensions applied directly to API definitions override extensions from audit rules.

openapi: 3.0.0
...
x-42c-accept-empty-security: true
...
post:
    description: Creates a new pet in the store. Duplicates are allowed.
    operationId: createPets
    security: []
    tags:
    - pets
...

You cannot apply both x-42c-accept-empty-security and x-42c-no-authentication (either from audit rules or as extensions directly in the API definition) to same API. This would lead to Security Audit getting conflicting directives for authentication checks so that it could not reliably process the API.

The empty security requirement (security: []) cannot be declared on the global level in the API, it must be declared in API operations.

For more details, see Allow empty security requirements.

Declare that your API is using mutual TLS (mTLS) authentication for incoming requests, so that the audit algorithm can take it into account when calculating your audit score.

The default value is false, meaning that Security Audit assumes that mTLS is not used.

You can add the extension to your API globally at the top level, or locally to individual operation objects if the whole API is not using mTLS. 

post:
    description: Creates a new pet in the store. Duplicates are allowed.
    operationId: createPets
    x-42c-mtls: true
    tags:
        - pets
    # ...

For more details, see Declare mTLS for audit score.

Switch off authentication checks completely in Security Audit. The default value is false, meaning that the authentication checks are on.

Switching the authentication checks off completely can be a big security risk down the line, and is not recommended. If unavoidable, remember to switch the back on as soon as possible.

Although somewhat similar to x-42c-accept-empty-security, this extension has some significant drawbacks:

  • You have to completely remove security on the global level of the API, because the extension x-42c-no-authentication has no effect if the API or API operation has a security object defined. This means that you need to remember to define authentication separately for any operations that require it if you want to use x-42c-no-authentication in even an operation.
  • Because security objects need to be removed where you want to use this extension, indicating that authentication is not needed is less explicit and more ambiguous: is the authentication not needed, or did you simply forget to define it.
  • If your API has some operations that require the authentication checks, you need to define the extension separately in each operation where you want to exclude the authentication checks.
  • Applying this extension through an audit rule may be difficult, so you likely need to hard-code it to your API definition, which makes it harder to see which APIs it has been applied to.
  • The extension does not quite follow the standard way of indicating if authentication is needed or not. This means that there are more things to remember when designing your API and which could lead to problems with third party scripts.

We recommend using x-42c-accept-empty-security instead of x-42c-no-authentication. However, as the empty security requirement (security: []) cannot be declared on the global level in the API, in some cases using x-42c-no-authentication may make sense.

You can apply this extension to operation objects in your API definition, or on the global level if no operations in your API need authentication. Defining this as an audit rule in 42Crunch Platform (see Customizations) always applies the extension on the global level in the API definition, so all operations are affected. Extensions applied directly to API definitions override extensions from audit rules.

The extension x-42c-no-authentication has no any effect if your API definition or operation includes the security field. Security Audit keeps running the authentication checks as long as the field is present.

You cannot apply both x-42c-accept-empty-security and x-42c-no-authentication (either from audit rules or as extensions directly in the API definition) to same API. This would lead to Security Audit getting conflicting directives for authentication checks so that it could not reliably process the API.

post:
    description: Creates a new pet in the store. Duplicates are allowed.
    operationId: createPets
    x-42c-no-authentication: true
    tags:
        - pets
    # ...

For more details, see Run audit without authentication checks.

Set audit score to 0 if Security Audit finds any semantic issues in the API definition, to highlight that it is not a valid OpenAPI definition. The default value is false, meaning that Security Audit calculates the audit score for APIs even if they were not semantically valid OpenAPI definitions.

You can apply this extension to the global level in your API definition:

openapi: 3.0.0
info:
    # ...
x-42c-no-score-on-semantic: true
  servers:
    # ...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Define how sensitive API operations in your API definition are and how severe security risk is involved. Specifying a sensitivity level affects how the audit score is calculated for your API: an issue occurring in an operation marked to be more sensitive weighs more in the audit and reduces more points from the audit score than the same issue occurring in a less sensitive operation. This lets you to fine-tune Security Audit to better reflect the associated risks.

You can apply this extension to operation objects in your API definition. The following values for sensitivity are possible:

  • Not sensitive: 1
  • Low: 2
  • Medium: 3
  • High: 4
  • Critical: 5

If no other value is specified, the property defaults to 3.

The sensitivity of API operations depends on the data they process: the more sensitive the data, the more sensitive the operation. For example, a GET operation providing a list of a bank's ATM locations would not be very sensitive:

get: 
    description: Retrieves a list of ATM locations.
    operationId: getATMs
    x-42c-sensitivity: 1
    # ...

In contrast, a GET operation for a bank account would process highly sensitive information and thus be very sensitive:

get:
    description: Retrieves the details of the bank account.
    operationId: getAccountDetails
    x-42c-sensitivity: 5
    # ...

You can also add the extension on the top level of your API to define the sensitivity level for the whole API. This global sensitivity can be overridden locally in operations or responses. For example, if you have an API that is overall very sensitive, you can add x-42c-sensitivity on the top level and set its value to 4. You can then further refine the sensitivity levels for operations:

openapi: 3.0.1,
  info:
    description: Very sensitive banking API
    x-42c-sensitivity: 4
    # ...
    
    get: 
    description: Retrieves a list of ATM locations.
    operationId: getATMs
    x-42c-sensitivity: 1
    # ...
    
    get:
    description: Retrieves the details of the bank account.
    operationId: getAccountDetails
    x-42c-sensitivity: 5
    # ...

Defining this as an audit rule in 42Crunch Platform(see Customizations) always applies the extension on the global level in the API definition. Because audit rules override extensions applied directly to API definitions, it may make more sense to define this only locally in API definition rather than as an audit rule.

For more details, see Specify sensitivity level.

Define how sensitive data the schema or parameter definitions for API operations include and how severe security risk is involved.

Specifying a sensitivity level affects how the audit score is calculated for your API: an issue involving a schema marked to be more sensitive weighs more in the audit and reduces more points from the audit score than the same issue occurring in a less sensitive schema. This lets you to fine-tune Security Audit to better reflect the associated risks.

You can add this extension to schema objects or parameter objects (OAS v2 only) in your API definition. The following values for sensitivity are possible:

  • Not sensitive: 1
  • Low: 2
  • Medium: 3
  • High: 4
  • Critical: 5

If no other value is specified, the property defaults to 3.

The sensitivity of schemas varies. For example, an object that anyone can view, like an item in an online store, would not be very sensitive:

schemas:
    Pet:
        type: object
        x-42c-sensitivity-data: 1
        required:
            - id
            - name
        properties:
            id:
                type: integer
                format: int64
            name:
                type: string
                tag:
                    type: string

In contrast, a schema including sensitive information, such as personal details, would be very sensitive:

schemas:
    User:
        type: object
        x-42c-sensitivity-data: 5
        properties:
            accountID:
                type: integer
                format: int64
            name:
                type: string
            address:
                type: string
            # ...

Defining this as an audit rule in 42Crunch Platform(see Customizations) always applies the extension on the global level in the API definition. Because audit rules override extensions applied directly to API definitions, it may make more sense to define this only locally in API definition rather than as an audit rule.

For more details, see Specify sensitivity level.

Define which checks Security Audit skips during the audit.

The extension takes an array of issue IDs (keys) as exact strings. You can choose to skip any checks from best practices (warning-) in OpenAPI format, or checks on data validation or security.

You cannot skip structural (validation-) or semantic (semantic-) issues in the audit, as these are required to make sure your OpenAPI definition is valid according to the OpenAPI Specification (OAS).

You can check which issue ID goes with which check from your previous audit reports, or online from API Security Encyclopedia.

Consider carefully which checks are safe to skip, especially in data validation or security. Do not skip checks simply because they take away points from the audit score of your API, because that is merely hiding the problem, not fixing it. Only skip checks after you have run Security Audit several times, investigated the raised issues thoroughly, and confirmed that some of them truly are not relevant in your particular circumstances.

You can apply this extension to the global level in your API definition:

openapi: 3.0.0
info:
    # ...
x-42c-skipIssues:
  - v3-warning-content-type-unknownprefix
  - global-securityscheme-apikey-inheader
servers:
    # ...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Define how much weight (as percentage) the content definitions of API responses get in the audit algorithm. The default value is 80.

This extension pairs with the extension x-42c-weight-headers and their combined values must total 100 (%).

You can apply this extension to response objects in your API definition:

responses:
    '500':
        description: Internal Server Error
        x-42c-weight-headers: 25
        x-42c-weight-content: 75
        headers:
            # ...
        content:
            # ...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Define how much weight (as percentage) the response definitions for HTTP status codes for failure (4XX—5XX) get in the audit algorithm. The default value is 30.

This extension pairs with the extension x-42c-weight-success and their combined values must total 100 (%).

You can apply this extension to responses object in your API definition:

responses:
    x-42c-success: 75
    x-42c-fail: 25
    #...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Define how much weight (as percentage) the response header definitions of API responses get in the audit algorithm. The default value is 20.

This extension pairs with the extension x-42c-weight-content and their combined values must total 100 (%).

You can apply this extension to response objects in your API definition:

responses:
    '500':
        description: Internal Server Error
        x-42c-weight-headers: 25
        x-42c-weight-content: 75
        headers:
            # ...
        content:
            # ...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Define how much weight (as percentage) the input definitions of API operations get in the audit algorithm. The default value is 80.

This extension pairs with the extension x-42c-weight-output and their combined values must total 100 (%).

You can also add further granularity to the weight by using the extensions x-42c-weight-parameters and x-42c-weight-requestBody.

You can apply this extension to operation objects in your API definition:

post:
    description: Creates a new pet in the store. Duplicates are allowed.
    operationId: createPets
    x-42c-weight-input: 75
    x-42c-weight-output: 25
    tags:
        - pets
    # ...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Define how much weight (as percentage) the output definitions of API operations get in the audit algorithm. The default value is 20.

This extension pairs with the extension x-42c-weight-input and their combined values must total 100 (%).

You can also add further granularity to the weight by using the extensions x-42c-weight-content and x-42c-weight-headers.

You can apply this extension to operation objects in your API definition: 

post:
    description: Creates a new pet in the store. Duplicates are allowed.
    operationId: createPets
    x-42c-weight-input: 75
    x-42c-weight-output: 25
    tags:
        - pets
    # ...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Define how much weight (as percentage) the parameter definitions of API operations get in the audit algorithm. The default value is 50.

This extension pairs with the extension x-42c-weight-requestBody and their combined values must total 100 (%).

You can apply this extension to operation objects in your API definition:

post:
    description: Creates a new pet in the store. Duplicates are allowed.
    operationId: createPets
    x-42c-weight-parameters: 60
    x-42c-weight-requestBody: 40
    tags:
        - pets
    # ...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Define how much weight (as percentage) request body definitions of API operations get in the audit algorithm. The default value is 50.

This extension pairs with the extension x-42c-weight-parameter and their combined values must total 100 (%).

You can apply this extension to operation objects in your API definition:

post:
    description: Creates a new pet in the store. Duplicates are allowed.
    operationId: createPets
    x-42c-weight-parameters: 40
    x-42c-weight-requestBody: 60
    tags:
        - pets
    # ...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Define how much weight (as percentage) the response definitions for HTTP status codes for success (1XX—3XX) get in the audit algorithm. The default value is 70.

This extension pairs with the extension x-42c-weight-fail and their combined values must total 100 (%).

You can apply this extension to responses object in your API definition:

responses:
    x-42c-success: 75
    x-42c-fail: 25
    #...

However, we rather recommend defining it as an audit rule in 42Crunch Platform to customize how Security Audit works and tag your API to apply the rule. Audit rules defined in 42Crunch Platform override customizations done directly in your API definition. For more details, see Customizations.

Extensions for Conformance Scan

You can use the extension x-42c-sample to provide a sample of a complex schema or parameter that Conformance Scan can use in the requests it sends during the scan. This is the preferred property to use for providing samples for Conformance Scan.

The following shows how you can use x-42c-sample in your API definition:

# ...
components:
    schemas:
        pet-age:
            type: integer
            format: int32
            minimum: 0
            maximum: 10
            default: 0
            x-42c-sample: 5   
        pet:
            type: object
            properties:
        age:
            $ref: '#/components/schemas/pet-age'    
        name:
            type: string
            minLength: 3
            maxLength: 20
            pattern: '[a-zA-Z]{3,20}'
            x-42c-sample: 'HelloWorld' 
        animal:
            type: string
            enum: [cat, dog]

In OAS v2, you can use x-42c-sample to provide examples for any parameters and schemas. In OAS v3, parameters must always have either schema or content defined, so you only really apply the extension to schemas.

The following are possible cases when scan might not be able to generate a default value for a parameter and would benefit from an example provided directly in the OpenAPI definition:

  • Arrays: if the property uniqueItems is set to true. Conformance Scan does not generate values for arrays with unique items at all. If no sample is provided, the operation is skipped in the scan. 
    schema:
  type: array
  minItems: 1
  maxItems: 3
  uniqueItems: true
  x-42c-sample:
  - Porkchop
  - Jimmy Chew
  - Bark Twain
  items:
    type: string
    pattern: '[a-z A-Z]{3,20}'
  • Strings: if the property pattern is defined and very specific, the regular expression generator that Conformance Scan uses may fail.

    If you define pattern for a string and have also specified minLength or maxLength for it, ensure that the pattern size reflects these values. If these properties for a string conflict, Security Audit raises an issue on this and scanning the API is prevented, because Conformance Scan cannot create a valid value for the string. For more details, see Conflicts from regular expressions.

For more details, see Generating values for parameters.

What is...

API Protection

API Firewall

API Firewall deployment architecture

Kubernetes Injector for API Firewall

Protections and security extensions

Tags

Customizations

API Security Audit

API Conformance Scan

How to...

Protect APIs

Deploy API Firewall with Kubernetes Injector

Manage API Firewall configuration

Apply additional protections

Deactivate automatic contract enforcement in API Firewall

Tag APIs

Customize platform features

Learn more...

How API Firewall validates API traffic

API Firewall variables

Protections

Automatic contract enforcement

API Firewall log line format for standard output