# safe-markdown

Source: https://apigenie.pl/docs/linter/swagger/rules/safe-markdown

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**.

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

**Bad**.

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