Custom Payload Injection 💉

Escape provides users with the capability to inject custom payloads in its security scanner to ensure precision and thoroughness in testing. There are two main methods for this:

Custom Security Tests
Hotstart Parameter
Defining Custom Scalars (Data Types)

These customization methods improve scan quality by tailoring tests specifically to an application's needs. Let's dive into the details.

Method 1 - Using custom security tests

Beta

We provide a tool that allows you to send custom requests to any URLs within your organization. This utility is particularly useful for running static security assessments on your web applications, identifying regression bugs, or investigating specialized in-house security concerns.

Configuring a Static Security Assessment

Custom security checks send a user-provided HTTP request, and run a set of matchers on the response. If a match is successful on a response, the test will raise an alert.

To initiate a new static security assessment, navigate to the Expert tab in your application settings.

Below is a sample configuration that illustrates a static security assessment aimed at sending a request to a specified endpoint. The assessment will then validate if the server's response status is 200.

custom_checks:
- name: Example-1
  severity: high
  http:
  - user: public
    raw: "@Host: https://[REDACTED]\nPOST / HTTP/1.1\nHost: [REDACTED]\nContent-Type:\
      \ application/json\nContent-Length: 194\n\n{\"query\":\"query {\n    debug(test:\
      \ \\\"y\\\") {\n        id\n        username\n        credit_card {\n      \
      \      belong_to {\n                id\n            }\n        }\n    }\n}\"\
      ,\"variables\":{}}"
    matchers:
    - status:
      - 200
      part: status

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('\"', '\\\\\"'))"

API

The api is inspired by the Nuclei template engine.

Custom check configuration example

{
    "custom_checks": {
        "name": "**value**", // The name of the check
        "severity": "high | medium | low | info", // The severity of the alert found
        "http": {
            "raw": "GET /users HTTP/1.1\nHost: example.com\nContent-Type: application/json\nContent-Length: 194\n\n",// The raw request to send
            "user": "some-user", // The user to use for the request
            "matchers": {
                "part": "status | body | headers | headers_keys | headers_values", // The part of the response to match
                "regex": [".*", "\d+", "**other regex**"], // Regexes to use for the match
                "status": ["503", "502"], // Statuses to match
                "words": ["foo"] // Words to match
            }
        }
    }
}

Matchers

You can attempt to match a specific part of the response using the part parameter. The following parts are available:

status: The status code of the response
body: The body of the response
headers: The headers (key and values) of the response
headers_keys: The keys of the headers of the response
headers_values: The values of the headers of the response

You can use the following parameters to match the response:

regex: A list of regexes to match
status: A list of status codes to match
words: A list of words to match

If one of the matchers is successful, an alert will be raised, based on the severity of the check.

Special Commands

Special commands should be placed at the beginning of the RAW request body.

@Host: Allows you to manually set the host for the request. Useful for forcing an HTTPS connection.
@timeout: Allows you to manually set the timeout duration for the request. The default timeout is 5 seconds.

Method 2 - Using the Hotstart feature

The hotstart parameter allows users to provide specific requests. This not only gives Escape more insight into the application's business logic but also aids in faster and more accurate scanning.

Examples

Hotstarting a GraphQL scan

In GraphQL, only the GraphQL document is required to declare operations to run at the beginning of the scan.

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

Hotstarting a REST scan

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('\"', '\\\\\"'))"

Method 3 - Defining Custom Data Types (Scalars)

Escape operates on a comprehensive scalar architecture, granting users the power to define their own data types or override existing ones via the escaperc

Structure for custom scalars:

scan:
  scalars:
    custom_scalar_identifier:
      description: value
      examples:
      - value
      names:
      - value
      parents:
      - ID
      - Int
      - String
      - Boolean
      - Float
      patterns:
      - regex
      sensitivity: NONE | LOW | MEDIUM | HIGH
      detection: key | value | value_strict | key_or_value | key_or_value_strict |
        key_and_value_strict
      entropy: float # optional

Fields

Here is the list of the fields :

description: Brief description for the scalar.
examples: Sample values for the scalar (used in the explore phase as default values).
names: Possible names for the scalar.
parents: default type the scalar is compatible with.
patterns: Potential regex-friendly values for the scalar (utilized for the checks).
sensitivity: Data sensitivity level. Allowed values are NONE, LOW, MEDIUM and HIGH. Values MEDIUM and HIGH will serve to raise Sensitive Data issues in Escape.
detection: The detection strategy:
- key : detect scalar where the key match one of the names.
- value : detect scalar where the value match one of the regexes patterns.
- value_strict : detect scalar where the value full match one of the regexes patterns (ie. ^(regex)$).
- key_or_value : detect scalar based on the key or value strategy.
- key_or_value_strict : detect scalar based on the key or value_strict strategy.
- key_and_value_strict : detect scalar based on the key and value_strict strategy.
entropy: The minimum shannon entropy of the matched value. (Optional)

All of this fields are optionals and can be omitted.

Example

Let's say you want to add a new scalar for the Super Secret Example Token inside your company :

scan:
  scalars:
    SSET:
      description: The Super Secret Example Token is internal to our company and should
        never been exposed by any APIs.
      examples:
      - SSET-ABC12
      names:
      - SSET
      - super_secret_example_token
      - SuperSecretExampleToken
      parents:
      - String
      patterns:
      - SSET-[A-Z0-9]{5}
      sensitivity: HIGH
      detection: key_or_value_strict
      entropy: 2.0

This is how JWT is defined by default in Escape's engine:

jwt:
  description: JSON Web Token
  examples:
    - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
  names:
    - jwt
    - Token
    - Authorization
    - Authorisation
    - Bearer
  parents:
    - String
  patterns:
    - eyJ(?:[a-zA-Z0-9_=]+)\.eyJ(?:[a-zA-Z0-9_=]+)\.(?:[a-zA-Z0-9_\-\+\/=]*)
    - (?i)\b(ey[0-9a-z]{30,34}\.ey[0-9a-z-\/_]{30,500}\.[0-9a-zA-Z-\/_]{10,200}={0,2})(?:['|\"|\n|\r|\s|\x60|;]|$)
  sensitivity: 3

🤖 Community Sharing

If you've crafted some useful custom scalars, feel free to share them with our community on Slack. Your contributions can assist others in refining their security checks.

Modifying current attacks

Every security checks comes with various parameters that can be used to customize their default behaviours. All those parameters are detailed in the Vulnerabilities Reference section.

Custom Payload Injection 💉

Method 1 - Using custom security tests​

Configuring a Static Security Assessment​

API​

Matchers​

Special Commands​

Method 2 - Using the Hotstart feature​

Examples​

Hotstarting a GraphQL scan​

Hotstarting a REST scan​

Method 3 - Defining Custom Data Types (Scalars)​

Structure for custom scalars:​

Fields​

Example​