Linter rulesSwagger 2.0safe-markdown

safe-markdown

Since 0.9.0 · fixed by --fix

This rule ensures that the GFM descriptions of a Swagger 2.0 document do not contain unsafe constructs like script elements or eval() calls.

Rule Details

Unsafe constructs embedded in descriptions can pose security risks when the documentation is rendered, for example by a documentation portal or an API console.

The safe-markdown rule checks the description field of the info object, operations, parameters, responses (but not response references), headers, schemas, security definitions, tags and external documentation objects. It reports:

  • Markdown contains <script> tag when a description contains a script element (an opening tag followed by a closing tag),
  • Markdown contains eval() function when a description contains eval followed by a parenthesized argument list.

Both checks are case-insensitive, and skip code spans and code blocks.

Configuration

None.

Examples

Good.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
  description: Manages the pets of a shelter and their adoptions.
paths: {}

Bad.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
  description: "Manages the pets of a shelter. <script>alert('Unsafe')</script>"
paths:
  /pets:
    get:
      description: Evaluates eval(filter) on the server.
      responses:
        '200':
          description: The list of pets.

Automatic fixes

When invoked with --fix, the rule rewrites the affected descriptions: the < of the opening and closing script tags is replaced with &lt;, and the ( after eval with &#40;. The rest of the description, including code spans and code blocks, is preserved.

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x and AsyncAPI documents are linted by the OpenAPI and AsyncAPI linters, which have their own safe-markdown rules.

Related rules

Further reading