Skip to content

docs: explain log versions #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
secDre4mer merged 1 commit into from
Oct 10, 2025
Merged

docs: explain log versions #40

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 27 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,31 @@ This library provides definitions of structures used in the output of the THOR A
- convert JSON logs into text logs
- parse JSON logs

## Usage
## 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.
Expand All @@ -20,11 +44,6 @@ The object types contained in a THOR log are `THOR finding` and `THOR message`:

Both findings and messages are together called _events_.

### Parsing Events

There is a parser in the `thorlog/parser` package which can be used to parse an event independently of its type.
This parser is also version aware, meaning it can handle different versions of the THOR log format.

### Reportable Objects

Findings may contain more objects, e.g. as a subject that they report.
Expand All @@ -38,14 +57,7 @@ E.g. when extracting a file from an archive, the file object should contain only
that relate to the file itself, not to the archive.
The archive data will instead appear in the _context_ of the finding.

### 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.

## Schema

A schema for the THOR log format can be generated using the `thorlog/jsonschema` package.
A schema for the version 3 format is attached to each release.
It can also be generated using the `thorlog/jsonschema` package.