⚡ Custom Tests

As you already know, Escape's built-in tests are pretty extensive and cover a lot of security vulnerabilities and concerns. But we know that you might have very specific use-cases, and that's why we've made it possible for you to create your own custom tests.

These will enable you to build your own governance and apply it at scale, in a simple language that is powerful thanks to Escape's inference engine.

Format

A custom test is a YAML file that defines the following blocks:

• Alerting is used define the alert format, it's severity…
• Detectors are used to detect if an alert must be raised by inspecting queries.
• Transformations are used to mutate the requests (optional).
• Mutators are used inside the transformations.
• Seeders are used to seed the scan with requests (optional).

Examples

Minimal example

alert:
  name: Deletion successful
  context: >
    For compliance reasons, the non admin user must not be able to delete some
    data via the API.
  severity: HIGH
detect:
  - if: helpers.request.crud
    is: DELETE
  - if: request.user
    is_not: admin
  - if: helpers.response.is_successful
    is: true

Mutated example

If you want to improve the above example, you can force escape to try to delete the resource by adding a mutation block:

transform:
  trigger:
    - if: helpers.request.crud
      is: CREATE
    - if: schema.path_ref
      is: /record
    - if: request.user
      is_not: admin
  mutate:
    - key: request.method
      value: DELETE
    - key: request.body.json
      jq: '{"id": .id}' # only keep the id in the delete body
alert:
  name: Deletion successful forced
  context: >
    For compliance reasons, the non admin user must not be able to delete some
    data via the API.
  severity: HIGH
detect:
  - if: helpers.request.crud
    is: DELETE
  - if: request.user
    is_not: admin
  - if: helpers.response.is_successful
    is: true

Seeded example

seed:
  - protocol: http
    raw: |
      @Host: https://backend-api.escape.tech
      GET /data HTTP/1.1
      Host: backend-api.tools.escape.tech
alert:
  name: Environment isolation
  context: >
    Tested API may call the backend API, but customers must not be able to
    access the backend API directly.
  severity: MEDIUM
detect:
  - if: helpers.response.is_successful
    is: true

Seeded

transform:
  trigger:
    - if: helpers.response.is_successful
      is: true
    - if: request.headers
      key:
        is: X-API-Version
      value:
        is: V2
  mutate:
    - key: request.headers
      name: X-API-Version
      value: V1

alert:
  name: V2 API with V1 tokens
  context: >
    Your current API seems to be confused between V1 and V2 endpoints.
    For compliance reasons, an API must only be deployed with one version.
  severity: LOW
detect:
  - if: helpers.response.is_successful
    is: true

Properties

• id: The unique identifier of the custom check. It is provided by Escape, do not set it manually.
• seed: A list of requests to seed the scan. See Seeders
• transform: Defines lists of triggers and mutations (combined with AND operators).See Transformations
• detect: The conditions to trigger the alert. See Detectors
• alert: The alert to raise if the detection conditions are met. See Alerting