Security/CrashSignatures

Draft for a Crash Signature Specification

Purpose

The purpose is to provide a generic crash specification that works platform independent, can be implemented easily in multiple languages and is not specific to Firefox crashes, but generic enough to handle all common crashes.

Introduction

The crash signature is a JSON object that has required and optional/arbitrary fields.

JSON is the format of choice because

• it can easily be implemented in multiple languages such as Python, Java, etc.
• it is human readable/editable if reasonably well formatted

Required top-level fields

• symptoms
  • Type: Array of Objects
  • List of symptoms that characterize the crash (see details below)

Optional top-level fields

• id
  • Type: String
  • ID that the software may assign when generating
• platforms
  • Type: Array of Strings
  • If specified, crash signature only applies to the specified platforms
  • Platforms can be: x86, x86-64, ARM
• products
  • Type: Array of Strings
  • If specified, crash signature only applies to the specified products
  • Variable content, we could use branches, e.g. mozilla-central, ionmonkey, etc.
• operatingSystems
  • Type: Array of Strings
  • If specified, crash signature only applies to the specified operating systems
  • Operating systems can be: linux, macosx, windows, b2g, android

probably should have another field that specifies major/minor version numbers for operating systems so we can know if it is Win7 versus Vista or different revs of Firefox OS. - Good point. This would require refactoring the operatingSystems field to Array of Object and create an OperatingSystem Object.

Symptoms Specification

Symptoms are objects with a "type" field and various additional fields holding the data, depending on the type. Symptom types include:

• output
  • Match specified output
  • Additional fields:
    • value (mandatory)
      • Type: StringMatch (see below)
    • src
      • Type: String
      • If specified, output must occur on the specified source
      • Can be: stdout, stderr, crashdata
        • New in version 1.3: crashdata corresponds to the raw crash data
• stackFrame
  • Match function name in specified stack frame
  • Additional fields:
    • functionName (mandatory)
      • Type: StringMatch (see below)
    • frameNumber
      • Type: NumberMatch (see below)
      • Specifies the frame to match (defaults to 0, which is the crash location)
• stackFrames
  • New in version 1.2
  • Match function names in the crashing stack
  • Additional fields:
    • functionNames (mandatory)
      • Type: Array of StringMatch (see below)
      • Frames are matched in the order of the array
      • Values '?' and '???' have special meanings
        • '?' means zero or one additional frame can be matched at that position
        • '???' means zero or multiple additional frames can be matched at that position
• stackSize
  • Match the size of the call stack (number of frames)
  • Additional fields:
    • size (mandatory)
      • Type: NumberMatch (see below)
      • Specifies the size to match
• crashAddress
  • Match the address that is causing the crash
  • Additional fields:
    • address (mandatory)
      • Type: NumberMatch (see below)
      • Specifies the address to match
• instruction
  • Match crashing instruction
  • Not available for ASan traces
  • Not available for minidump traces
  • Additional fields:
    • registerNames
      • Type: Array of String
      • Specifies the registers that must be involved
    • instructionName
      • Type: StringMatch (see below)
    • Either registerNames or instructionName must be specified
• testcase
  • New in version 1.1
  • Match the testcase as specified
  • Additional fields:
    • value (mandatory)
      • Type: StringMatch

Helper Object/String specification

Purpose of the helper objects and strings is to encapsulate certain logics into own objects or strings, rather than adding all the options to the main objects, duplicating them.

• StringMatch
  • Purpose is to provide an object for matching strings in various ways
  • Fields:
    • value (mandatory)
      • Type: String
    • matchType
      • Type: String
      • Specifies the type of the match
      • Values: contains (default), pcre

NOTE: Instead of a StringMatch with default matchType ("contains"), a String can be used for simplicity and readability.

NOTE: New in version 1.2: Instead of matchType ("pcre"), a String enclosed in forward slashes can be used for simplicity and readability, e.g. "/some regular expression/".

• NumberMatch
  • A special string containing an operator and the number, separated by whitespace
  • Valid operators: >, >=, <, <=, ==
    • e.g. > means the number matched must be greater than "value"
  • Valid numbers: Any numeric value, or hexadecimal value indicated by "0x" in front of the actual value.
  • If no operator is specified, it defaults to ==
    • In this case, a decimal number without operator can be specified as number instead of string.
  • Examples:
    • "< 0x1000" - Matched value must be smaller than hex value 0x1000
    • ">= 300" - Matched value must be larger or equal to 300
    • "1" - Matched value must be exactly 1.