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. This configuration mechanism enables the extension of the scanner's data type recognition capabilities.

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 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:

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:

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

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.