# API Testing Custom Payloads

## Custom Data Type Definition

Custom data types (scalars) can be defined or existing types can be overridden through the scanner's [scalar architecture](<https://docs.escape.tech/documentation/reference/data-types/index.md>). This configuration mechanism enables the extension of the scanner's data type recognition capabilities.

```yaml
inference:
  scalars:
    custom-scalar-identifier:
      description: The Description of my new Scalar
      examples:
      - abc-123-xxx
      names:
      - custom_scalar_key
      - scalarKey
      pattern: regex
      sensitivity: HIGH
      strategy: key_or_value_strict
```

### Configuration Fields

The following fields are available for scalar configuration:

- `description`: A brief description of the scalar type.
- `examples`: Sample values that will be used during the exploration phase as default test values.
- `names`: Possible field or parameter names associated with the scalar.
- `ignored_names`: Field names to ignore. Defaults to an empty list.
- `ignored_pattern`: Regular expression for values to ignore. Defaults to unset.
- `pattern`: Regular expression pattern used for value validation during security checks.
- `raise_on_exposure`: Raise an issue when the scalar is detected in HTTP requests. Defaults to `false`.
- `sensitivity`: Data sensitivity classification. Defaults to `NONE`. Accepted values are `NONE`, `LOW`, `MEDIUM`, and `HIGH`. When set to `MEDIUM` or `HIGH`, **Sensitive Data** issues will be raised upon detection.
- `strategy`: The detection strategy employed. Defaults to `key_or_value`:

  - `key`: Scalar is detected when the field name matches one of the defined names.
  - `key_strict`: Scalar is detected when the field name exactly matches one of the defined names.
  - `value`: Scalar is detected when the value matches one of the regex patterns.
  - `value_strict`: Scalar is detected when the value fully matches one of the regex patterns (using anchors: `^(regex)$`).
  - `key_or_value`: Scalar is detected based on either the `key` or `value` strategy.
  - `key_or_value_strict`: Scalar is detected based on either the `key` or `value_strict` strategy.
  - `key_strict_or_value`: Scalar is detected based on either the `key_strict` or `value` strategy.
  - `key_and_value_strict`: Scalar is detected when both the `key` and `value_strict` strategies match.

All configuration fields are optional and can be omitted as needed.

### Integration with Sensitive Data Scanner

Custom scalar definitions are particularly effective when integrated with the [High Number of Custom Scalars](<https://docs.escape.tech/documentation/reference/vulnerabilities/high_number_of_custom_scalars/>) security test within the Sensitive Data Scanner module.

### Configuration Examples

The following example demonstrates the definition of a custom scalar for an organization-specific token format:

```yaml
inference:
  scalars:
    SSET:
      description: The Super Secret Example Token is internal to our company and should never be exposed by any APIs.
      raise_on_exposure: true # An issue will be raised if the scalar is detected in HTTP requests
      examples:
      - SSET-ABC12
      names:
      - SSET
      - super_secret_example_token
      - SuperSecretExampleToken
      pattern: SSET-[A-Z0-9]{5}
      sensitivity: HIGH
      strategy: key_or_value_strict
```

This custom scalar example illustrates JWT detection. Use `pattern` to define the regular expression:

```yaml
inference:
  scalars:
    jwt:
      description: JSON Web Token
      examples:
        - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
      names:
        - jwt
        - Token
        - Authorization
        - Authorisation
        - Bearer
      pattern: eyJ(?:[a-zA-Z0-9_=]+)\.eyJ(?:[a-zA-Z0-9_=]+)\.(?:[a-zA-Z0-9_\-\+\/=]*)
      sensitivity: HIGH
      strategy: value
```

> [!NOTE]
>
> **Community Contribution**
>
> Custom scalar definitions that may benefit the wider security community can be shared via [Slack](<https://slack.escape.tech/>). Community contributions enhance the collective capability to identify and validate custom data types.

## Security Check Customization

Each security check can be configured through various parameters to modify default behavior. Complete parameter documentation is provided in the `Vulnerabilities Reference` section.