Other x-42c extensions

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

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.

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

Because the OAS v2 or v3.0.x 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. Non-mTLS security issues are reported at severity level Info to avoid false positives failing security quality gates (SQGs).

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.