THOR structure definitions

Introduction

This library provides definitions of structures used in the output of the THOR APT Forensic Scanner. These structures can be used for different use cases:

• generate schemas for THOR JSON logs and the THOR audit trail
• convert JSON logs into text logs
• parse JSON logs

Versions

There are three versions of the THOR log format:

• v1: The original THOR log format, used up to and including THOR version 10.7. This is equivalent to the THOR text format, simply serialized as JSON.
• v2: The format used in THOR version 10.7 with the --jsonv2 flag. This format introduced a more structured approach to logging, with subobjects for reasons, files, and other entities. It is largely open-ended and allows for custom fields.
• v3: The format used in THOR 11 and later. This format is more strict and versioned, with a defined schema. It introduces the concept of reportable objects.

Parsing Events

There is a parser in the thorlog/parser package which can be used to parse an event. This parser is version aware and can handle all versions of the THOR log format. The result of the parsing is a common.Event object, which is a version-agnostic representation of a THOR event. It can be cast to the version-specific implementation of this interface, e.g. thorlog.Finding for a finding in version 3.

Textlog Conversion

The jsonlog.TextlogFormatter type provides a way to convert an object to a text log format.

This formatter can be used to convert findings and messages to a human-readable format. However, the text log format is not as rich as the JSON format and may not contain all fields. When in doubt, use the JSON format for analysis.

Objects in JSON Log Version 3

Each object in the THOR log contains a type field that indicates the object type. This type determines how the object should be interpreted and what fields it contains.

Event Types

The object types contained in a THOR log are THOR finding and THOR message:

• Findings are the results of THOR's analysis, such as detected threats or anomalies.
• Messages are informational or status updates from THOR, such as progress updates.

Both findings and messages are together called events.

Audit Entry Types

The THOR audit trail is a separate log that documents which objects a scan examined, regardless of whether THOR reported anything about them. The object types contained in this log are THOR audit record and THOR audit message:

• Audit records document a single object that THOR observed, together with the timestamps known for it, any indicators that matched on it, and its relations to other audit records.
• Audit messages are the messages that THOR printed during the scan, in a less verbose form than the THOR message events.

Both audit records and audit messages are together called audit entries.

Reportable Objects

Findings may contain more objects, e.g. as a subject that they report. Object types that can appear as subjects are called reportable objects. The most common reportable objects are:

• file
• process

Reportable objects should contain only fields that relate directly to the object itself. E.g. when extracting a file from an archive, the file object should contain only fields that relate to the file itself, not to the archive. The archive data will instead appear in the context of the finding.

Schema

There are two schemas for the version 3 format:

• thor-event.json describes the events in a THOR log.
• thor-audit-entry.json describes the entries in the THOR audit trail.

The schemas are attached to each release. They can also be generated using the thorlog/jsonschema package. The generator takes the schema to generate as its only argument and must be run from within its directory:

cd thorlog/jsonschema
go run . log > thor-event.json
go run . audittrail > thor-audit-entry.json