# schemes-secure

Source: https://api-genie.dev/docs/linter/swagger/rules/schemes-secure

A rule of the Swagger 2.0 linter, which reads Swagger 2.0 documents; OpenAPI 3 documents go to the OpenAPI linter. 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](/docs/linter/openapi/rules/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**

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

## Examples

**Good**.

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

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

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