safe-markdown

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

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.

The OpenAPI and AsyncAPI linters have rules of the same name, safe-markdown and safe-markdown.

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.

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:
        safe-markdown: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?