Insight Data Structure

The Insight Agent receives messages in the form of a Protocol Buffer and forwards them to downstream endpoints in the same format or in JSON. An Insight envelope (i.e., message) has the following structure, if viewed as JSON:

{
  "sessions": [
    {
      "frames": [
        {
          "events": [ ],
          "evidences": [ ]
        }
      ]
    }
  ]
}

Each data structure level contains several data points, including various IDs and timestamps. For a complete view of all available data points, refer to the libshield.proto specification file. The following sections summarize the data points relevant to understanding a security check:

Sessions

In its simplest form, a session has the following JSON structure:

"sessions": [
  {
    "header": {
      "hardware": { },
      "software": { },
      "environment": { }
    },
    "frames": [ ]
  }
]

Hardware

The hardware dataset includes the following properties:

Software

The software dataset includes the following properties:

Environment

The environment dataset includes the following properties:

Frames

A frame groups related events and evidences together. Frames also contain a duplicate_count property. If there are several instances with essentially the same information, then only the first one is reported in full. Any additional/duplicate instances simply increment the value of duplicate_count. Thus, a duplicate_count of 4 means there were five instances with the same data (i.e., the original and four duplicates).

Events

In its simplest form, an event has the following JSON structure:

"events": [
  {
    "probe": {
      "e": {
        "result": 2
      }
    }
  }
]

In the above example, e represents the shorthand code for an emulator probe. A result of 2 means the probe returned true (i.e., an emulator was detected).

Security Probes

The following security probes are possible:

Result Codes

Each probe event returns a result code, where the code can be one of the following values:

Evidences

Not every security probe returns corresponding evidences, whether it is because the Insight Client does not yet collect those evidences or the security probe simply does not require further details. When evidences do exist, they appear as one of the following types: