schemes-secure (Swagger 2.0 linter rule)

Since 0.9.0 · fixed by --fix

This rule checks whether a Swagger 2.0 document serves its API over secure transfer protocols only, and whether its host is written in lower case.

Rule Details

The root schemes list, and the schemes lists of operations that override it, name the transfer protocols of the API. http and ws send requests, credentials and responses unencrypted, so production APIs should use https and wss instead.

The schemes-secure rule reports:

Insecure scheme (http) or Insecure scheme (ws) for every insecure scheme in the root schemes list and in the schemes list of every operation,
Host is not lower case when the root host contains upper case letters. Host names are case-insensitive, and lower case is their canonical form.

Insecure schemes are allowed when host is a loopback address: localhost (in any letter case), 127.0.0.1 or [::1], with or without a port. When host is missing, insecure schemes are reported.

Configuration

The rule accepts an object with one option:

upgradeInsecure: whether --fix replaces insecure schemes with their secure variants. Default: false.

Configuration Example

version: "1.0"
commands:
  lint:
    swagger:
      rules:
        schemes-secure:
          - error
          - upgradeInsecure: true

Examples

Good.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
host: api.example.com
schemes: [https, wss]
paths: {}

Good. A local development server may use http.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
host: localhost:8080
schemes: [http]
paths: {}

Bad. The root object allows http, an operation uses ws, and the host is not lower case.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
host: API.Example.com
schemes: [http, https]
paths:
  /pets/events:
    get:
      schemes: [ws]
      responses:
        '101':
          description: Switching to the event stream.

Automatic fixes

When invoked with --fix, the rule always converts the root host to lower case.

With upgradeInsecure: true, it also rewrites every root and operation schemes list that contains an insecure scheme, unless the host is a loopback address: http becomes https, ws becomes wss, and duplicates are removed while the order is kept. For example, [http, https, ws] becomes [https, wss]. Without this option the insecure schemes are reported, but not changed, because switching protocols requires the server to support them.

When Not to Use It

You may disable this rule for documents that describe APIs that are only reachable in a trusted network, or for an operation with x-lint-disable: [schemes-secure].

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, whose server-urls rule checks the URLs of servers.

schemes-secure