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-identfier:
      description: The Description of my new Scalar
      examples:
      - abc-123-xxx
      names:
      - custom_scalar_key
      - scalarKey
      patterns:
      - regex
      sensitivity: NONE | LOW | MEDIUM | HIGH
      strategy: key | value | value_strict | key_or_value | key_or_value_strict | key_and_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.
• patterns: Regular expression patterns used for value validation during security checks.
• sensitivity: Data sensitivity classification. Accepted values are NONE, LOW, MEDIUM, and HIGH. When set to MEDIUM or HIGH, Sensitive Data issues will be raised upon detection.
• detection: The detection strategy employed:
  • key: Scalar is detected when the field name 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 (i.e., ^(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_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_commit: true   # An issue will be raised if the scalar is detected in a git repository
      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
      parents:
      - String
      patterns:
      - SSET-[A-Z0-9]{5}
      sensitivity: HIGH
      strategy: key_or_value_strict

The JWT scalar is defined as follows in the default scanner configuration:

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

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.