Format of a string header is unknown

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

Average severity: Low

Description

The format you have defined for a string header 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 host is unknown:

{
    "responses": {
        "200": {
            "description": "OK",
            "headers": {
                "x-host": {
                    "type": "string",
                    "format": "host"
                }
            }
        }
    }
}

Possible exploit scenario

Your API has been designed to return specific data. If you define an unknown format for strings, you do not actually limit what can be included in response headers.

Attackers typically want to make the API to change its behavior and return different data than it is supposed to. A particular API failure might leak some other data, such as records or stack trace.

Using your internal, company-specific formats is not currently supported.

Remediation

Define a known format for string headers. This provides an extra layer of safety ensuring that your API only returns data formats that you expect it to return.

{
    "responses": {
        "200": {
            "description": "OK",
            "headers": {
                "x-host": {
                    "type": "string",
                    "format": "hostname"
                }
            }
        }
    }
}

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.