schemes-secure

Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error

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.

The OpenAPI linter has server-urls for OpenAPI 3.x documents.

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

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.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        schemes-secure: off

Related rules

Further reading

Was this helpful?