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> tagwhen a description contains ascriptelement (an opening tag followed by a closing tag),Markdown contains eval() functionwhen a description containsevalfollowed 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 <, and the
( after eval with (. 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