schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Version",
  "description": "Event is the complete structure that Polycorder (Polyverse-hosted zero-day detection service) understands. This structure is also the reference schema/format for all detect-efforts.\n\nAs such, it is encouraged to have many detectors that emit data in this structure.\n\nDifferent implementations of the structure may very. Various fields may come or go.\n\nAll parsers are encouraged to first test the \"Version\" field and then parse the correct structure. The field `version` is guaranteed to exist on ALL versions and instances of Event. Any structure/data that does not contain the version field, is considered invalid.",
  "anyOf": [
    {
      "description": "Version is guaranteed to exist. All other fields may change or not exist, and it is recommended to use a different version when making breaking changes to all other fields. It allows parsers to test on version and determine if they know what to do with the rest. For this particular variant, set DeviceVersion to a fixed value \"V1\"",
      "type": "object",
      "required": [
        "event",
        "timestamp",
        "version"
      ],
      "properties": {
        "event": {
          "description": "Platform records fields specific to a specific mechanism/platform.",
          "allOf": [
            {
              "$ref": "#/definitions/EventType"
            }
          ]
        },
        "hostname": {
          "type": [
            "string",
            "null"
          ]
        },
        "timestamp": {
          "description": "This is universal and important for all events. They occur at a time.",
          "type": "string",
          "format": "date-time"
        },
        "version": {
          "type": "string",
          "enum": [
            "V1"
          ]
        }
      }
    }
  ],
  "definitions": {
    "EventType": {
      "description": "The Platform this event originated on.",
      "anyOf": [
        {
          "description": "An analytics-detected internal event based on other events",
          "type": "object",
          "required": [
            "justification",
            "message",
            "procname",
            "register",
            "type"
          ],
          "properties": {
            "justification": {
              "description": "The raw events which justify this analytics event.",
              "allOf": [
                {
                  "$ref": "#/definitions/RegisterProbeJustification"
                }
              ]
            },
            "message": {
              "description": "What does this probe mean? What interpretation could this particular register probe have?",
              "type": "string"
            },
            "procname": {
              "type": "string"
            },
            "register": {
              "description": "Which register was being probed?",
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "RegisterProbe"
              ]
            }
          }
        },
        {
          "description": "The Linux platform and event details in the Linux context A Kernel Trap event - the kernel stops process execution for attempting something stupid",
          "type": "object",
          "required": [
            "errcode",
            "facility",
            "ip",
            "level",
            "pid",
            "procname",
            "sp",
            "trap",
            "type"
          ],
          "properties": {
            "errcode": {
              "description": "The error code for the trap",
              "allOf": [
                {
                  "$ref": "#/definitions/SegfaultErrorCode"
                }
              ]
            },
            "facility": {
              "description": "A Log-facility - most OSes would have one, but this is Linux-specific for now",
              "allOf": [
                {
                  "$ref": "#/definitions/LogFacility"
                }
              ]
            },
            "file": {
              "description": "(Optional) File in which the trap occurred (could be the main executable or library).",
              "type": [
                "string",
                "null"
              ]
            },
            "ip": {
              "description": "Instruction Pointer (what memory address was executing)",
              "type": "integer",
              "format": "uint",
              "minimum": 0.0
            },
            "level": {
              "description": "The type of kernel trap triggered A Log-level for this event - was it critical?",
              "allOf": [
                {
                  "$ref": "#/definitions/LogLevel"
                }
              ]
            },
            "pid": {
              "description": "Process ID",
              "type": "integer",
              "format": "uint",
              "minimum": 0.0
            },
            "procname": {
              "description": "Name of the process in which the trap occurred",
              "type": "string"
            },
            "sp": {
              "description": "Stack Pointer",
              "type": "integer",
              "format": "uint",
              "minimum": 0.0
            },
            "trap": {
              "$ref": "#/definitions/KernelTrapType"
            },
            "type": {
              "type": "string",
              "enum": [
                "LinuxKernelTrap"
              ]
            },
            "vmasize": {
              "description": "(Optional) The Virtual Memory Size of this file's mapping.",
              "type": [
                "integer",
                "null"
              ],
              "format": "uint",
              "minimum": 0.0
            },
            "vmastart": {
              "description": "(Optional) The Virtual Memory Address where this file (main executable or library) was mapped (with ASLR could be arbitrary).",
              "type": [
                "integer",
                "null"
              ],
              "format": "uint",
              "minimum": 0.0
            }
          }
        },
        {
          "description": "A Fatal Signal from the process because the process did something stupid",
          "type": "object",
          "required": [
            "facility",
            "level",
            "signal",
            "stack_dump",
            "type"
          ],
          "properties": {
            "facility": {
              "description": "A Log-facility - most OSes would have one, but this is Linux-specific for now",
              "allOf": [
                {
                  "$ref": "#/definitions/LogFacility"
                }
              ]
            },
            "level": {
              "description": "A Log-level for this event - was it critical?",
              "allOf": [
                {
                  "$ref": "#/definitions/LogLevel"
                }
              ]
            },
            "signal": {
              "description": "The type of Fatal triggered",
              "allOf": [
                {
                  "$ref": "#/definitions/FatalSignalType"
                }
              ]
            },
            "stack_dump": {
              "description": "An Optional Stack Dump if one was found and parsable. Do not place these in CEF format since ArcSight/Microfocus needs explicit field mappings. No telling what a real dump of registers/values might be contained here. Best to be safe. If you care about these values, use JSON/Text logging.",
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "type": {
              "type": "string",
              "enum": [
                "LinuxFatalSignal"
              ]
            }
          }
        },
        {
          "description": "Information about a suppressed callback i.e. when a particular type of error happens so much it is suppressed 'n' times.\n\nThis captures what the log was, and how many times it was suppressed.\n\nThis is a crucial data point because under Blind ROP attacks an error might happen thousands of times but may only be logged once, with all the remaining attempts being suppressed.",
          "type": "object",
          "required": [
            "count",
            "facility",
            "function_name",
            "level",
            "type"
          ],
          "properties": {
            "count": {
              "description": "Number of times it was suppressed.",
              "type": "integer",
              "format": "uint",
              "minimum": 0.0
            },
            "facility": {
              "description": "A Log-facility - most OSes would have one, but this is Linux-specific for now",
              "allOf": [
                {
                  "$ref": "#/definitions/LogFacility"
                }
              ]
            },
            "function_name": {
              "description": "Name of the function being suppressed/folded.",
              "type": "string"
            },
            "level": {
              "description": "A Log-level for this event - was it critical?",
              "allOf": [
                {
                  "$ref": "#/definitions/LogLevel"
                }
              ]
            },
            "type": {
              "type": "string",
              "enum": [
                "LinuxSuppressedCallback"
              ]
            }
          }
        },
        {
          "description": "This is a zerotect-internal event. zerotect can be commanded to set and ensure certain configuration settings to capture events, such as enabling kernel fatal-signals, or core dumps.\n\nThis event is triggered when, after zerotect has configured a machine as commanded, the configuration later mismatched. It means someone attempted to undo those changes.\n\nThis event usually tells an observer they may not be seeing other events because they may be disabled.",
          "type": "object",
          "required": [
            "expected_value",
            "key",
            "observed_value",
            "type"
          ],
          "properties": {
            "expected_value": {
              "description": "The value zerotect configured and thus expected.",
              "type": "string"
            },
            "key": {
              "description": "The key in question whose values mismatched.",
              "type": "string"
            },
            "observed_value": {
              "description": "The value zerotect observed.",
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "ConfigMismatch"
              ]
            }
          }
        }
      ]
    },
    "FatalSignalType": {
      "description": "The type of Fatal Signal detected Comprehensive list of POSIX signals in the linux kernel can be found int he kernel source tree: https://github.com/torvalds/linux/blob/master/include/linux/signal.h#L339\n\nA bit more detail may be found in the man-pages: http://man7.org/linux/man-pages/man7/signal.7.html",
      "type": "string",
      "enum": [
        "SIGHUP",
        "SIGINT",
        "SIGQUIT",
        "SIGILL",
        "SIGTRAP",
        "SIGIOT",
        "SIGBUS",
        "SIGFPE",
        "SIGKILL",
        "SIGUSR1",
        "SIGSEGV",
        "SIGUSR2",
        "SIGPIPE",
        "SIGALRM",
        "SIGTERM",
        "SIGSTKFLT",
        "SIGCHLD",
        "SIGCONT",
        "SIGSTOP",
        "SIGTSTP",
        "SIGTTIN",
        "SIGTTOU",
        "SIGURG",
        "SIGXCPU",
        "SIGXFSZ",
        "SIGVTALRM",
        "SIGPROF",
        "SIGWINCH",
        "SIGIO",
        "SIGPWR"
      ]
    },
    "KernelTrapType": {
      "description": "The types of kernel traps understood",
      "anyOf": [
        {
          "description": "This is type zerotect doesn't know how to parse. So it captures and stores the string description.",
          "type": "object",
          "required": [
            "description",
            "type"
          ],
          "properties": {
            "description": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "Generic"
              ]
            }
          }
        },
        {
          "description": "Segfault occurs when an invalid memory access is performed (writing to read-only memory, executing non-executable memory, etc.)",
          "type": "object",
          "required": [
            "location",
            "type"
          ],
          "properties": {
            "location": {
              "type": "integer",
              "format": "uint",
              "minimum": 0.0
            },
            "type": {
              "type": "string",
              "enum": [
                "Segfault"
              ]
            }
          }
        },
        {
          "description": "Invalid Opcode occurs when the processor doesn't understand an opcode. This usually occurs when execution jumps to an otherwise data segment, or in the wrong byte within an instruction.",
          "type": "object",
          "required": [
            "type"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "InvalidOpcode"
              ]
            }
          }
        },
        {
          "type": "object",
          "required": [
            "type"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "GeneralProtectionFault"
              ]
            }
          }
        }
      ]
    },
    "LogFacility": {
      "description": "Linux kmesg (kernel message buffer) Log Facility.",
      "type": "string",
      "enum": [
        "Kern",
        "User",
        "Mail",
        "Daemon",
        "Auth",
        "Syslog",
        "Lpr",
        "News",
        "UUCP",
        "Cron",
        "AuthPriv",
        "FTP"
      ]
    },
    "LogLevel": {
      "description": "Linux kmesg (kernel message buffer) Log Level.",
      "type": "string",
      "enum": [
        "Emergency",
        "Alert",
        "Critical",
        "Error",
        "Warning",
        "Notice",
        "Info",
        "Debug"
      ]
    },
    "RegisterProbeJustification": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "FullEvents"
          ],
          "properties": {
            "FullEvents": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Version"
              }
            }
          }
        },
        {
          "type": "object",
          "required": [
            "RegisterValues"
          ],
          "properties": {
            "RegisterValues": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        {
          "type": "object",
          "required": [
            "EventCount"
          ],
          "properties": {
            "EventCount": {
              "type": "integer",
              "format": "uint",
              "minimum": 0.0
            }
          }
        }
      ]
    },
    "SegfaultAccessMode": {
      "description": "The context under which the Segmentation Fault was triggered",
      "type": "string",
      "enum": [
        "Kernel",
        "User"
      ]
    },
    "SegfaultAccessType": {
      "description": "The type of Access that triggered this Segmentation Fault",
      "type": "string",
      "enum": [
        "Read",
        "Write"
      ]
    },
    "SegfaultErrorCode": {
      "description": "Segmentation Fault ErrorCode flags parsed into a structure See more: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/x86/include/asm/traps.h#n167 See more: https://utcc.utoronto.ca/~cks/space/blog/linux/KernelSegfaultMessageMeaning",
      "type": "object",
      "required": [
        "access_mode",
        "access_type",
        "instruction_fetch",
        "protection_keys_block_access",
        "reason",
        "use_of_reserved_bit"
      ],
      "properties": {
        "access_mode": {
          "description": "The mode under which access was performed",
          "allOf": [
            {
              "$ref": "#/definitions/SegfaultAccessMode"
            }
          ]
        },
        "access_type": {
          "description": "The type of access causing the fault",
          "allOf": [
            {
              "$ref": "#/definitions/SegfaultAccessType"
            }
          ]
        },
        "instruction_fetch": {
          "description": "fault was an instruction fetch, not data read or write",
          "type": "boolean"
        },
        "protection_keys_block_access": {
          "description": "Memory Protection Keys related. Not sure what exactly triggers this. See more: https://lore.kernel.org/patchwork/patch/633070/",
          "type": "boolean"
        },
        "reason": {
          "description": "The reason for the segmentation fault",
          "allOf": [
            {
              "$ref": "#/definitions/SegfaultReason"
            }
          ]
        },
        "use_of_reserved_bit": {
          "description": "use of reserved bits in the page table entry detected (the kernel will panic if this happens)",
          "type": "boolean"
        }
      }
    },
    "SegfaultReason": {
      "description": "The reason for the Segmentation Fault",
      "type": "string",
      "enum": [
        "NoPageFound",
        "ProtectionFault"
      ]
    },
    "Version": {
      "description": "Event is the complete structure that Polycorder (Polyverse-hosted zero-day detection service) understands. This structure is also the reference schema/format for all detect-efforts.\n\nAs such, it is encouraged to have many detectors that emit data in this structure.\n\nDifferent implementations of the structure may very. Various fields may come or go.\n\nAll parsers are encouraged to first test the \"Version\" field and then parse the correct structure. The field `version` is guaranteed to exist on ALL versions and instances of Event. Any structure/data that does not contain the version field, is considered invalid.",
      "anyOf": [
        {
          "description": "Version is guaranteed to exist. All other fields may change or not exist, and it is recommended to use a different version when making breaking changes to all other fields. It allows parsers to test on version and determine if they know what to do with the rest. For this particular variant, set DeviceVersion to a fixed value \"V1\"",
          "type": "object",
          "required": [
            "event",
            "timestamp",
            "version"
          ],
          "properties": {
            "event": {
              "description": "Platform records fields specific to a specific mechanism/platform.",
              "allOf": [
                {
                  "$ref": "#/definitions/EventType"
                }
              ]
            },
            "hostname": {
              "type": [
                "string",
                "null"
              ]
            },
            "timestamp": {
              "description": "This is universal and important for all events. They occur at a time.",
              "type": "string",
              "format": "date-time"
            },
            "version": {
              "type": "string",
              "enum": [
                "V1"
              ]
            }
          }
        }
      ]
    }
  }
}