Format of a string schema in a response is unknown

Issue ID: schema-response-string-unknown-format

Average severity: Low

Description

The format you have defined for a string schema does not match formats defined in either the OpenAPI Specification (OAS) or JSON Schema Specification. Unknown formats cannot be enforced to protect your API, so it is like you had not defined a format at all.

For more details, see the OpenAPI Specification and JSON Schema Validation.

Example

The following is an example of how this type of risk could look in your API definition. The format mail for the property userName is unknown and therefore does not restrict the accepted values:

{
    "post": {
        "description": "Creates a new user",
        "operationId": "addUser",
        // ...
        "responses": {
            "200": {
                "description": "success",
                "schema": {
                    "type": "object",
                    "$ref": "#/definitions/User"
                }
            }
        }
    },
    // ...
    "definitions": {
        "User": {
            "type": "object",
            "required": [
                "name",
                "userName"
            ],
            "properties": {
                "name": {
                    "type": "string"
                },
                "userName": {
                    "type": "string",
                    "format": "mail"     
                }
                // ...
            }
        }
    }
}

Possible exploit scenario

Attackers strive to make your APIs behave in an unexpected way to learn more about your system or to cause a data breach. Good data definition quality in the schemas used in API responses allows reliably validating that the contents of outgoing API responses are as expected.

While filtering API responses does not block a specific kind of attack, it is there as a damage control mechanism in the unfortunate event that a successful attack has been conducted: it allows blocking the response and prevent attackers from retrieving data they should not access.

In the vast majority of cases (with the notable exception of Denial of Service (DoS and DDoS) attacks) attacks are conducted because attackers want to access data or resources they should not have access to. Often, this means that the structure or the size of the API response changes as a result of a successful attack, compared to a normal API response.

Validating that API responses are as expected can be achieved through proper schema validation of the API responses. The accuracy of this depends on the quality of the response schemas: the better defined your schemas are, the easier it is to detect when something is not right.

Remediation

Make sure that you only use known formats for strings. This ensures that only parameters of the expected format get passed to the backend.

{
    "post": {
        "description": "Creates a new user",
        "operationId": "addUser",
        // ...
        "responses": {
            "200": {
                "description": "success",
                "schema": {
                    "type": "object",
                    "$ref": "#/definitions/User"
                }
            }
        }
    },
    // ...
    "definitions": {
        "User": {
            "type": "object",
            "required": [
                "name",
                "userName"
            ],
            "properties": {
                "name": {
                    "type": "string"
                },
                "userName": {
                    "type": "string",
                    "format": "email"     
                }
                // ...
            }
        }
    }
}

If you want to use your internal, company-specific format, make sure to also use properties like maximum, minimum, pattern, and maxLenght to constrain the accepted values.