Skip to main content

Directing Your Scan: Blacklist, Whitelist & Hotstart 🎯

Gain finer control over how Escape interacts with your API by employing the Blacklist, Whitelist, and Hotstart features.

Blacklist 🚫​

Identify the operations that you'd like Escape to skip during its security tests. By blacklisting certain operations, you can ensure these won't be evaluated during the scan.

GraphQL​

The blacklist parameter is part of the global scan keys, referenced here.

scan:
  blacklist:
    mutation:
    - '**operationName**'
    objects:
    - '**objectName**'
    query:
    - '**queryName**'

REST​

The blacklist parameter in REST is a list of path and methods used to identify the routes to blacklist. The path is a valid OpenAPI path and the method is an HTTP method (GET, POST, PUT, DELETE, etc.).

scan:
  blacklist:
    routes:
    - path: /a/path/to/blacklist
      method: GET
    - path: /another/path/to/blacklist
      method: POST

You can also blacklist some routes using regexes on the path. If we found a fullmatch between the path and the regex, the route will be blacklisted.

scan:
  blacklist:
    routes:
    - path: /user/.*
      method: POST

Whitelist ✅​

By employing a whitelist, you instruct Escape to focus its exploration phase solely on the specified operations. This can make the scan process faster, as Escape narrows its evaluation to just these queries.

scan:
  whitelist:
  - 'query { child(parentId: "b63f4020-45f6-4f33-9747-32ac8f270097" ) { id name birthdate
    }}'
  - 'query { bank(account: 1337) { id address }}'

Hotstart 🚀​

Enhance the potency of your scans! By providing legitimate requests via the Hotstart feature, you arm Escape with deeper insights into your application's business logic. This enables Escape to operate with increased efficiency and precision.

The operations you provide should be listed under the hotstart key. You have the freedom to provide multiple requests.

GraphQL​

In graphql, the hotstart key is a list of strings, each string representing a graphql query. The query can be as simple as a query with no parameters, or as complex as a query with multiple parameters and nested objects.

scan:
  hotstart:
  - 'query { child(parentId: "b63f4020-45f6-4f33-9747-32ac8f270097" ) { id name birthdate
    }}'
  - 'query { bank(account: 1337) { id address }}'

REST​

In REST, the hotstart is a list of HTTP document to execute.

scan:
  hotstart:
  - 'POST /register HTTP/1.1

    Host: example.com

    Content-Type: application/json

    Content-Length: 194


    {"my": "data"}'
  - 'GET /users HTTP/1.1

    Host: example.com

    Content-Type: application/json

    Content-Length: 194


    '

To easily encode your raw request located in a req.txt file, execute the following Python command:

cat req.txt | python -c "import sys; print(''.join(sys.stdin).replace('\n', '\\\\n').replace('\\\\\"', '\\\\\\\\\"').replace('\"', '\\\\\"'))"