x-42c extensions

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

Allow using empty security requirements (security: []) to indicate that an API operation or even the whole API 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 and its 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.

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.

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.

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.

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