API Custom Payloads 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:

1. Custom Security Tests
2. Hotstart Parameter
3. 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¶

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, 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_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 matches one of the names.
  • value: Detect scalar where the value matches one of the regex patterns.
  • value_strict: Detect scalar where the value fully matches one of the regex patterns (i.e., ^(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 these fields are optional 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 be 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

Modifying Current Attacks¶

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