// Copyright 2012 The Plaso Project Authors.
// Please see the AUTHORS file for details on individual authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// Author: Kristinn Gudjonsson <kristinn at log2timeline dot net>>

// This is the main protobuf for event storage in plaso.o

syntax = "proto2";

package plaso_storage;

// Each EventObject can contain any attribute
// as long as it can be expressed in any of the supported
// formats (eg, string, int, array, dict).
// This can be looked as a hash or a dict object, with a key
// and a value values.
message Attribute {
  // The key to the dict object, something like 'username'.
  required string key = 1;

  // If the value is a string.
  optional string string = 2;
  // If the value is an integer.
  optional int64 integer = 3;
  // If the value is an array.
  optional Array array = 4;
  // If the value is a dictionary.
  optional Dict dict = 5;
  // If the value is a boolean value.
  optional bool boolean = 6;
  // If we have a "raw" byte value.
  optional bytes data = 7;
  // If we have a "float" value.
  optional float float = 8;
  // If there is a None value (happens).
  optional bool none = 9;
};

// A list of of Attributes, to build up a dictionary.
message Dict {
  repeated Attribute attributes = 1;
};

// A value, used for lists or arrays.
message Value {
  optional int64 integer = 1;
  optional string string = 2;
  optional bytes data = 3;
  optional Array array = 4;
  optional Dict dict = 5;
  optional bool boolean = 6;
  optional float float = 7;
  optional bool none = 8;
};

// A list of values, either integers or strings, to make up an array.
message Array {
  repeated Value values = 1;
};

// Each event read by the tool is stored as an EventObject,
// an EventObject contains certain fixed sets of attributes
// and it can also store any additional attributes.
// This message stores the main attributes inside the each record
// instead of nesting them possibly deep down.
message EventObject {
  // The timestamp is presented as a 64 bit Unix Epoch time,
  // stored in UTC.
  optional int64 timestamp = 1;

  // A short description of the meaning of the timestamp.
  // This could be something as 'File Written', 'Last Written',
  // 'Page Visited', 'File Downloaded', or something like that.
  optional string timestamp_desc = 2;

  // The type of the event data stored in the attributes.
  required string data_type = 3;

  // A list of all the stored attributes within the event.
  repeated Attribute attributes = 4;

  // The timezone of the source where the timestamp came from.
  optional string timezone = 5;

  // The filename from where the event was extracted from.
  optional string filename = 6;
  optional string display_name = 7;

  // The full PathSpec where the file was extracted from.
  optional bytes pathspec = 8;

  // The offset into the original file from where the event came from.
  optional int64 offset = 9;

  // Information about where this object is stored, added by the storage
  // library to make it easier to quickly recover the EventObject from
  // the storage file.
  optional int64 store_number = 10;
  optional int64 store_index = 11;

  // EventTagging is a message that can be added that include information
  // about coloring, tagging or comments that this object contains.
  optional EventTagging tag = 12;

  // Description of the origin of the event in generic terms that
  // mostly adhere to the definition of the TLN format.
  // TODO: Remove this field from the EventObject message.
  enum SourceShort {
    AV = 1; // All Anti-Virus engine log files.
    BACK = 2; // Information from backup points, eg. restore points, VSS.
    EVT = 3; // EventLog entries, both the EVT format and EVTX.
    EXIF = 4; // EXIF information.
    FILE = 5; // FILE related information, mactime information.
    LOG = 6; // Generic log file, most log files should fit this.
    LNK = 7; // Shortcut or link files.
    LSO = 8; // Flash cookies, or Local Shared Objects.
    META = 9; // Metadata information.
    PLIST = 10; // Information extracted from plist files.
    RAM = 11; // Information extracted from RAM.
    RECBIN = 12; // Recycle bin or deleted items.
    REG = 13; // Registry information.
    WEBHIST = 14; // Browser history.
    TORRENT = 15; // Torrent files.
    JOB = 16; // Scheduled tasks or jobs.
  }

  // The category or short description of the source.
  // TODO: Remove this field from the EventObject message.
  optional SourceShort source_short = 13;

  // The short description is not sufficient to describe the source
  // of the event. A longer source field is therefore provided to add
  // more context to the source. The source_long field should not be
  // long, two or three words should be sufficient for most parts.
  // The field is not strictly defined, it should just be short and
  // fully descriptive.
  //
  // Example field names are:
  //    Chrome Browser History
  //    Chrome Download History
  //    Recycle Bin
  //    NTUSER.DAT Registry
  //    Sophos AV Log
  // TODO: Remove this field from the EventObject message.
  optional string source_long = 14;

  /////////////////////////////////////////////////////////////////////
  // Include common attribute names to flatten out the storage.
  /////////////////////////////////////////////////////////////////////

  // The name of the parser used to extract this item.
  optional string parser = 15;
  // The integer value of the inode of the file this entry is extracted from.
  optional int64 inode = 16;
  // The extracted hostname this entry came from.
  optional string hostname = 17;
  // The name of the plugin that was used, if applicable.
  optional string plugin = 18;
  // For Windows Registry files, defines the type of registry, eg: NTUSER, SAM.
  optional string registry_type = 19;
  // Boolean value that indicates whether the file was allocated or not.
  optional bool allocated = 20;
  // For filesystem records, defines the type of filesystem, eg: NTFS, FAT.
  optional string fs_type = 21;
  // Many parsers attempt to recover partially deleted entries, this boolean
  // value is present in those parsers and indicates whether this particular
  // entry is recovered or not.
  optional bool recovered = 22;
  // Contains the record number in log files that contain sequential
  // information, such as Windows EventLog.
  optional int64 record_number = 23;
  // If the file being parsed contains different sources, such as "Security" or
  // other similar source types it can be stored here.
  optional string source_name = 24;
  // Some log files, such as the EventLog, stores information about from which
  // computer this particular entry came from. Often used in log files that can
  // consolidate entries from more than a single host.
  optional string computer_name = 25;
  // Few entries that are specific to Windows EventLog entries, common enough
  // to get specially defined attributes.
  optional int64 event_identifier = 26;
  optional int64 event_level = 27;
  optional string xml_string = 28;
  optional Array strings = 29;
  // Some files contain information about the username that produced the
  // extracted record.
  optional string username = 30;
  // Sometimes the username is not available but a SID or a UID.
  optional string user_sid = 31;
  // A field indicating the size of a cache file.
  optional int64 cached_file_size = 32;
  // Mostly used in browser history plugins referencing the number of times
  // someone visited that particular entry.
  optional int64 number_of_hits = 33;
  // Used in MSIECF to indicate the index name of the cache directory.
  optional int64 cache_directory_index = 34;
  // Mostly used in browser history plugins. Contains the title of the web
  // visited web page (store in <head><title> tag).
  optional string title = 35;
  // Several parsers extract metadata items from events and store them
  // in a dictionary.
  optional Dict metadata = 36;
  // An URL extracted from things like browser history.
  optional string url = 37;
  // Windows registry keyname attribute.
  optional string keyname = 38;
  // Extracted values from a Windows registry key.
  optional Dict regvalue = 39;
  // Some text based parsers define this attribute for their text
  // representation.
  optional string text = 40;

  // The UUID is a hex string that uniquely identifies the EventObject.
  optional string uuid = 41;
};

// The EventTagging is a simple message that describes comments,
// color information or tagging of EventObjects. This information
// is usually manually added by an investigator and can be used
// to add more context to certain events.
message EventTagging {
  // Description of where the EventObject is stored that this
  // tag is describing. It is necessary to either define these
  // two values or the event_uuid, otherwise it will not be
  // possible to locate the event object this belongs to.
  optional int64 store_number = 1;
  optional int64 store_index = 2;

  // An arbitrary string that contains a comment describing
  // observations the investigator has about this EventObject.
  optional string comment = 3;

  // Color information, used in some front-ends to make this
  // event stand out. This should be either a simple description
  // of the color, eg "red", "yellow", etc or a HTML color code,
  // eg: "#E11414".
  optional string color = 4;

  // A short string or a tag that describes that can be used to
  // group together events that are related to one another, eg
  // "Malware", "Entry Point", "Event of Interest", etc.
  message Tag {
    required string value = 1;
  };

  repeated Tag tags = 5;

  // An UUID value of the particular event object that this tag
  // belongs to. This value has to be set if the store_number and
  // store_index are not know at the time of tagging.
  optional string event_uuid = 6;
};

// The EventGroup is a simple mechanism to describe a group of
// events that belong to the same action or behavior. This is
// a simple mechanism to store this information so a front-end
// can collapse all these events into a single source.
message EventGroup {
  // The name of the EventGroup, what is displayed in the front-end
  // as a substitute for the other events, should be descriptive
  // of the events that are grouped together, as in "USB Drive inserted",
  // or "User Logged On".
  required string name = 1;

  // Optional longer description of the group, giving a more detailed
  // description of what the grouping describes or why these events
  // were grouped together.
  optional string description = 2;

  // If these events contain a timestamp it can be beneficial to
  // include the timerange of events this group spans. That time range
  // can be described by the first and last timestamp that is contained
  // within the group.
  optional int64 first_timestamp = 3;
  optional int64 last_timestamp = 4;

  // Optional color information that can be used in the front-end
  // to give color information about the group. This can be described
  // as a simple color, eg: "red", "orange", "green" or as a HTML
  // color code, eg "#E11414".
  optional string color = 5;

  // If this group of events falls into a specific category it can
  // be included here, eg: "User Behavior", "Malware Related", etc.
  optional string category = 6;

  // Information about which EventObjects are included in this group.
  // The information is stored in an attribute called EventDescription
  // that simply defines where the EventObjects are stored so they can
  // be easily identified and recovered.
  message EventDescription {
    // Description of where these events are stored within the storage
    // file.
    required int64 store_number = 1;
    required int64 store_index = 2;
  };

  repeated EventDescription events = 7;
};

// The PreProcess protobuf is a simple message that stores information
// gathered from the preprocessing stage of plaso.
message PreProcess {
  // Storing information about the runtime of the tool.
  optional Dict collection_information = 1;

  // A dict that contains information about counters stored within the
  // the store.
  optional Dict counter = 2;

  // A list value that depicts the range of store numbers this particular
  // PreProcess message applies to.
  optional Array store_range = 3;

  // All attributes that each preprocessing module produces gets stored
  // inside this field.
  repeated Attribute attributes = 4;

  // A dict that contains information about plugin counters.
  optional Dict plugin_counter = 5;
};

// The AnalysisReport object is a simple message describing a report
// created from an analysis plugin.
message AnalysisReport {
  // Name of the analysis plugin that created this report.
  optional string plugin_name = 1;
  // The timestamp of when this report was created.
  optional int64 time_compiled = 2;

  // The actual report content, the free flowing text.
  // The text will have few notations possible:
  //    {image:X} - Where X is an integer, indicating the entry number
  //                inside the images field (counter starting from zero).
  //                This will indicate where images should be included in the
  //                final displayed report.
  //    {heading_start} / {heading_end}: An indication of main header.
  //    {subheading_start} / {subheading_end}: An indication of a subheader.
  // This is no way meant as a "HTML/XML look-alike" in terms of definitions.
  // This is merely a very simple implementation that only contains these
  // "special" tags, meant to make it easier to export the final report in a
  // HTML or any other format for later viewing.
  optional string text = 3;

  // Optional repeated field of images that can be saved as binary data.
  repeated bytes images = 4;

  // Some reports may contain counters, or some statistics that can be
  // retrieved later on for additional analysis or processing.
  optional Dict report_dict = 5;
  optional Array report_array = 6;

  // If a filter string was used on the output, it's saved here.
  optional string filter_string = 7;
};