Skip to main content

⚑ 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​

  • 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