368 lines
14 KiB
Protocol Buffer
368 lines
14 KiB
Protocol Buffer
// 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;
|
|
};
|