Other x-42c extensions

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

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 x-42c-mtls, x-42c-accept-empty-security, or x-42c-no-authentication (either from audit rules or as extensions directly in the API definition) to the 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, so that Security Audit 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.

Because the OAS v2 or v3.0 do not support mTLS as an authentication method, you cannot define it in security schemes or requirements. This may make it falsely seem that your API is unprotected, while in fact it has strong authentication in place.

The extension x-42c-mtls allows you to indicate to Security Audit that your API is protected with mTLS. In this case, Security Audit considers your API to be fully protected and does not deduct points from your security score, but it still reports any potential security issues it found so that you can take them into account when developing your API further.

Mutual TLS can only be considered secure if connections are over HTTPS, not if traffic is in the clear over HTTP. If you have declared mTLS with x-42c-mtls but server (OAS v3) or schemes (OAS v2) objects define http, Security Audit ignores x-42c-mtls and security issues deduct points normally.

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

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. 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. Audit rules override extensions applied directly to API definitions, in this case it may be better to define this only locally in API definition rather than as an audit rule.

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

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 x-42c-mtls, x-42c-accept-empty-security, or x-42c-no-authentication (either from audit rules or as extensions directly in the API definition) to the 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.

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.

Other x-42c extensions

Extensions for Security Audit

Extensions for Conformance Scan