Skip to main content

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:

  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

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\nHost: example.com\nContent-Type: application/json\nContent-Length: 194\n\n{\"my\": \"data\"}",
"GET /users HTTP/1.1\nHost: example.com\nContent-Type: application/json\nContent-Length: 194\n\n",
]
}
}

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": (optional) "float"
}
}
}
}

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 Discord. 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.