artifacts package

Subpackages

• artifacts.scripts package
  • Submodules
  • artifacts.scripts.stats module
    • ArtifactStatistics
      • ArtifactStatistics.BuildStats()
      • ArtifactStatistics.PrintOSTable()
      • ArtifactStatistics.PrintSourceTypeTable()
      • ArtifactStatistics.PrintStats()
      • ArtifactStatistics.PrintSummaryTable()
      • ArtifactStatistics.__init__()
    • Main()
  • artifacts.scripts.validator module
    • ArtifactDefinitionsValidator
      • ArtifactDefinitionsValidator.CheckDirectory()
      • ArtifactDefinitionsValidator.CheckFile()
      • ArtifactDefinitionsValidator.GetUndefinedArtifacts()
      • ArtifactDefinitionsValidator.LEGACY_PATH
      • ArtifactDefinitionsValidator.__init__()
    • Main()
  • Module contents

Submodules

artifacts.artifact module

The artifact definition.

class artifacts.artifact.ArtifactDefinition(name, aliases=None, description=None)

Bases: object

Artifact definition interface.

aliases

aliases that identify the artifact definition.

Type:

list[str]

description

description.

Type:

str

name

name that uniquely identifiers the artifact definition.

Type:

str

sources

sources.

Type:

list[SourceType]

supported_os

supported operating systems.

Type:

list[str]

urls

URLs with more information about the artifact definition.

Type:

list[str]

AppendSource(type_indicator, attributes)

Appends a source.

If you want to implement your own source type you should create a subclass in source_type.py and change the AppendSource method to handle the new subclass. This function raises FormatError if an unsupported source type indicator is encountered.

Parameters:

• type_indicator (str) – source type indicator.

• attributes (dict[str, object]) – source attributes.

Returns:

a source type.

Return type:

SourceType

Raises:

FormatError – if the type indicator is not set or unsupported, or if required attributes are missing.

AsDict()

Represents an artifact as a dictionary.

Returns:

artifact attributes.

Return type:

dict[str, object]

__init__(name, aliases=None, description=None)

Initializes an artifact definition.

Parameters:

• name (str) – name that uniquely identifiers the artifact definition.

• aliases (Optional[str]) – aliases that identify the artifact definition.

• description (Optional[str]) – description of the artifact definition.

artifacts.definitions module

Constants and definitions.

artifacts.errors module

The error objects.

exception artifacts.errors.CodeStyleError

Bases: Error

Error that is raised when code formatting fails style checks.

exception artifacts.errors.Error

Bases: Exception

The error interface.

exception artifacts.errors.FormatError

Bases: Error

Error that is raised when the format is incorrect.

exception artifacts.errors.MissingDependencyError

Bases: Error

Artifact references artifact that is undefined.

artifacts.reader module

The artifact reader objects.

class artifacts.reader.ArtifactsReader

Bases: BaseArtifactsReader

Artifacts reader common functionality.

ReadArtifactDefinitionValues(artifact_definition_values)

Reads an artifact definition from a dictionary.

Parameters:

artifact_definition_values (dict[str, object]) – artifact definition values.

Returns:

an artifact definition.

Return type:

ArtifactDefinition

Raises:

FormatError – if the format of the artifact definition is not set or incorrect.

ReadDirectory(path, extension='yaml')

Reads artifact definitions from a directory.

This function does not recurse sub directories.

Parameters:

• path (str) – path of the directory to read from.

• extension (Optional[str]) – extension of the filenames to read.

Yields:

ArtifactDefinition – an artifact definition.

ReadFile(filename)

Reads artifact definitions from a file.

Parameters:

filename (str) – name of the file to read from.

Yields:

ArtifactDefinition – an artifact definition.

abstractmethod ReadFileObject(file_object)

Reads artifact definitions from a file-like object.

Parameters:

file_object (file) – file-like object to read from.

Yields:

ArtifactDefinition – an artifact definition.

Raises:

FormatError – if the format of the artifact definition is not set or incorrect.

__init__()

Initializes an artifacts reader.

class artifacts.reader.BaseArtifactsReader

Bases: object

Artifacts reader interface.

supported_os

supported operating systems.

Type:

set[str]

abstractmethod ReadArtifactDefinitionValues(artifact_definition_values)

Reads an artifact definition from a dictionary.

Parameters:

artifact_definition_values (dict[str, object]) – artifact definition values.

Returns:

an artifact definition.

Return type:

ArtifactDefinition

Raises:

FormatError – if the format of the artifact definition is not set or incorrect.

abstractmethod ReadDirectory(path, extension=None)

Reads artifact definitions from a directory.

This function does not recurse sub directories.

Parameters:

• path (str) – path of the directory to read from.

• extension (Optional[str]) – extension of the filenames to read.

Yields:

ArtifactDefinition – an artifact definition.

abstractmethod ReadFile(filename)

Reads artifact definitions from a file.

Parameters:

filename (str) – name of the file to read from.

Yields:

ArtifactDefinition – an artifact definition.

abstractmethod ReadFileObject(file_object)

Reads artifact definitions from a file-like object.

Parameters:

file_object (file) – file-like object to read from.

Yields:

ArtifactDefinition – an artifact definition.

Raises:

FormatError – if the format of the artifact definition is not set or incorrect.

__init__()

Initializes an artifacts reader.

class artifacts.reader.JsonArtifactsReader

Bases: ArtifactsReader

JSON artifacts reader.

ReadFileObject(file_object)

Reads artifact definitions from a file-like object.

Parameters:

file_object (file) – file-like object to read from.

Yields:

ArtifactDefinition – an artifact definition.

Raises:

FormatError – if the format of the JSON artifact definition is not set or incorrect.

class artifacts.reader.YamlArtifactsReader

Bases: ArtifactsReader

YAML artifacts reader.

ReadFileObject(file_object)

Reads artifact definitions from a file-like object.

Parameters:

file_object (file) – file-like object to read from.

Yields:

ArtifactDefinition – an artifact definition.

Raises:

FormatError – if the format of the YAML artifact definition is not set or incorrect.

artifacts.registry module

The artifact definitions registry.

class artifacts.registry.ArtifactDefinitionsRegistry

Bases: object

Artifact definitions registry.

classmethod CreateSourceType(type_indicator, attributes)

Creates a source type object.

Parameters:

• type_indicator (str) – source type indicator.

• attributes (dict[str, object]) – source attributes.

Returns:

a source type.

Return type:

SourceType

Raises:

FormatError – if the type indicator is not set or unsupported, or if required attributes are missing.

DeregisterDefinition(artifact_definition)

Deregisters an artifact definition.

Artifact definitions are identified based on their lower case name.

Parameters:

artifact_definition (ArtifactDefinition) – an artifact definition.

Raises:

KeyError – if an artifact definition is not set for the corresponding name.

classmethod DeregisterSourceType(source_type_class)

Deregisters a source type.

Source types are identified based on their type indicator.

Parameters:

source_type_class (type) – source type.

Raises:

KeyError – if a source type is not set for the corresponding type indicator.

GetDefinitionByAlias(alias)

Retrieves a specific artifact definition by alias.

Parameters:

alias (str) – alias of the artifact definition.

Returns:

an artifact definition or None if not available.

Return type:

ArtifactDefinition

GetDefinitionByName(name)

Retrieves a specific artifact definition by name.

Parameters:

name (str) – name of the artifact definition.

Returns:

an artifact definition or None if not available.

Return type:

ArtifactDefinition

GetDefinitions()

Retrieves the artifact definitions.

Yields:

ArtifactDefinition – artifact definition.

GetUndefinedArtifacts()

Retrieves the names of undefined artifacts used by artifact groups.

Returns:

undefined artifacts names.

Return type:

set[str]

ReadFileObject(artifacts_reader, file_object)

Reads artifact definitions into the registry from a file-like object.

Parameters:

• artifacts_reader (ArtifactsReader) – an artifacts reader.

• file_object (file) – file-like object to read from.

ReadFromDirectory(artifacts_reader, path, extension='yaml')

Reads artifact definitions into the registry from files in a directory.

This function does not recurse sub directories.

Parameters:

• artifacts_reader (ArtifactsReader) – an artifacts reader.

• path (str) – path of the directory to read from.

• extension (Optional[str]) – extension of the filenames to read.

Raises:

KeyError – if a duplicate artifact definition is encountered.

ReadFromFile(artifacts_reader, filename)

Reads artifact definitions into the registry from a file.

Parameters:

• artifacts_reader (ArtifactsReader) – an artifacts reader.

• filename (str) – name of the file to read from.

RegisterDefinition(artifact_definition)

Registers an artifact definition.

Artifact definitions are identified based on their lower case name.

Parameters:

artifact_definition (ArtifactDefinition) – an artifact definition.

Raises:

KeyError – if artifact definition is already set for the corresponding name or alias.

classmethod RegisterSourceType(source_type_class)

Registers a source type.

Source types are identified based on their type indicator.

Parameters:

source_type_class (type) – source type.

Raises:

KeyError – if source types is already set for the corresponding type indicator.

classmethod RegisterSourceTypes(source_type_classes)

Registers source types.

Source types are identified based on their type indicator.

Parameters:

source_type_classes (list[type]) – source types.

__init__()

Initializes an artifact definitions registry.

artifacts.source_type module

The source type objects.

The source type objects define the source of the artifact data. In earlier versions of the artifact definitions collector definitions had a similar purpose as the source type. Currently the following source types are defined: * artifact; the source is one or more artifact definitions; * file; the source is one or more files; * path; the source is one or more paths; * Windows Registry key; the source is one or more Windows Registry keys; * Windows Registry value; the source is one or more Windows Registry values; * WMI query; the source is a Windows Management Instrumentation query.

The difference between the file and path source types are that file should be used to define file entries that contain data and path, file entries that define a location. E.g. on Windows %SystemRoot% could be considered a path artifact definition, pointing to a location e.g. C:Windows. And where C:WindowsSystem32winevtLogsAppEvent.evt a file artifact definition, pointing to the Application Event Log file.

class artifacts.source_type.ArtifactGroupSourceType(names=None)

Bases: SourceType

Artifact group source type.

AsDict()

Represents a source type as a dictionary.

Returns:

source type attributes.

Return type:

dict[str, str]

TYPE_INDICATOR = 'ARTIFACT_GROUP'

__init__(names=None)

Initializes a source type.

Parameters:

names (Optional[str]) – artifact definition names.

Raises:

FormatError – when artifact names is not set.

class artifacts.source_type.CommandSourceType(args=None, cmd=None)

Bases: SourceType

Command source type.

AsDict()

Represents a source type as a dictionary.

Returns:

source type attributes.

Return type:

dict[str, str]

TYPE_INDICATOR = 'COMMAND'

__init__(args=None, cmd=None)

Initializes a source type.

Parameters:

• args (list[str]) – arguments to the command to run.

• cmd (str) – command to run.

Raises:

FormatError – when args or cmd is not set.

class artifacts.source_type.DirectorySourceType(paths=None, separator='/')

Bases: SourceType

Directory source type.

AsDict()

Represents a source type as a dictionary.

Returns:

source type attributes.

Return type:

dict[str, str]

TYPE_INDICATOR = 'DIRECTORY'

__init__(paths=None, separator='/')

Initializes a source type.

Parameters:

• paths (Optional[str]) – paths relative to the root of the file system.

• separator (Optional[str]) – path segment separator.

Raises:

FormatError – when paths is not set or not a list type.

class artifacts.source_type.FileSourceType(paths=None, separator='/')

Bases: SourceType

File source type.

AsDict()

Represents a source type as a dictionary.

Returns:

source type attributes.

Return type:

dict[str, str]

TYPE_INDICATOR = 'FILE'

__init__(paths=None, separator='/')

Initializes a source type.

Parameters:

• paths (Optional[str]) – paths relative to the root of the file system.

• separator (Optional[str]) – path segment separator.

Raises:

FormatError – when paths is not set or not a list type.

class artifacts.source_type.PathSourceType(paths=None, separator='/')

Bases: SourceType

Path source type.

AsDict()

Represents a source type as a dictionary.

Returns:

source type attributes.

Return type:

dict[str, str]

TYPE_INDICATOR = 'PATH'

__init__(paths=None, separator='/')

Initializes a source type.

Parameters:

• paths (Optional[str]) – paths relative to the root of the file system.

• separator (Optional[str]) – path segment separator.

Raises:

FormatError – when paths is not set or not a list type.

class artifacts.source_type.SourceType

Bases: object

Artifact definition source type interface.

abstractmethod AsDict()

Represents a source type as a dictionary.

Returns:

source type attributes.

Return type:

dict[str, str]

TYPE_INDICATOR = None

__init__()

Initializes an artifact definition source type.

Raises:

FormatError – if the indicator is not defined.

property type_indicator

type indicator.

Type:

str

class artifacts.source_type.SourceTypeFactory

Bases: object

Source type factory.

classmethod CreateSourceType(type_indicator, attributes)

Creates a source type.

Parameters:

• type_indicator (str) – source type indicator.

• attributes (dict[str, object]) – source type attributes.

Returns:

a source type.

Return type:

SourceType

Raises:

FormatError – if the type indicator is not set or unsupported, or if required attributes are missing.

classmethod DeregisterSourceType(source_type_class)

Deregisters a source type.

Source types are identified based on their type indicator.

Parameters:

source_type_class (type) – source type.

Raises:

KeyError – if a source type is not set for the corresponding type indicator.

classmethod GetSourceTypeIndicators()

Retrieves the source type indicators.

Returns:

source type indicators.

Return type:

list[str]

classmethod GetSourceTypes()

Retrieves the source types.

Returns:

source types.

Return type:

list[type]

classmethod RegisterSourceType(source_type_class)

Registers a source type.

Source types are identified based on their type indicator.

Parameters:

source_type_class (type) – source type.

Raises:

KeyError – if source types is already set for the corresponding type indicator.

classmethod RegisterSourceTypes(source_type_classes)

Registers source types.

Source types are identified based on their type indicator.

Parameters:

source_type_classes (list[type]) – source types.

class artifacts.source_type.WMIQuerySourceType(base_object=None, query=None)

Bases: SourceType

WMI query source type.

base_object

WMI base object.

Type:

str

query

WMI query.

Type:

str

AsDict()

Represents a source type as a dictionary.

Returns:

source type attributes.

Return type:

dict[str, str]

TYPE_INDICATOR = 'WMI'

__init__(base_object=None, query=None)

Initializes a source type.

Parameters:

• base_object (Optional[str]) – WMI base object.

• query (Optional[str]) – WMI query.

Raises:

FormatError – when query is not set.

class artifacts.source_type.WindowsRegistryKeySourceType(keys=None)

Bases: SourceType

Windows Registry key source type.

AsDict()

Represents a source type as a dictionary.

Returns:

source type attributes.

Return type:

dict[str, str]

TYPE_INDICATOR = 'REGISTRY_KEY'

VALID_PREFIXES = ['HKEY_LOCAL_MACHINE', 'HKEY_USERS', 'HKEY_CLASSES_ROOT', '%%current_control_set%%']

classmethod ValidateKey(key_path)

Validates this key against supported key names.

Parameters:

key_path (str) – path of a Windows Registry key.

Raises:

FormatError – when key is not supported.

__init__(keys=None)

Initializes a source type.

Parameters:

keys (Optional[list[str]]) – key paths relative to the root of the Windows Registry.

Raises:

FormatError – when keys is not set.

class artifacts.source_type.WindowsRegistryValueSourceType(key_value_pairs=None)

Bases: SourceType

Windows Registry value source type.

AsDict()

Represents a source type as a dictionary.

Returns:

source type attributes.

Return type:

dict[str, str]

TYPE_INDICATOR = 'REGISTRY_VALUE'

__init__(key_value_pairs=None)

Initializes a source type.

Parameters:

key_value_pairs (Optional[list[tuple[str, str]]]) – key path and value name pairs, where key paths are relative to the root of the Windows Registry.

Raises:

FormatError – when key value pairs is not set.

artifacts.writer module

The artifact writer objects.

class artifacts.writer.ArtifactWriter

Bases: BaseArtifactsWriter

File artifacts writer.

abstractmethod FormatArtifacts(artifacts)

Formats artifacts to desired output format.

Parameters:

artifacts (ArtifactDefinition|list[ArtifactDefinition]) – artifact definitions.

Returns:

formatted string of artifact definition.

Return type:

str

WriteArtifactsFile(artifacts, filename)

Writes artifact definitions to a file.

Parameters:

• artifacts (list[ArtifactDefinition]) – artifact definitions to be written.

• filename (str) – name of the file to write artifacts to.

class artifacts.writer.BaseArtifactsWriter

Bases: object

Artifacts writer interface.

abstractmethod FormatArtifacts(artifacts)

Formats artifacts to desired output format.

Parameters:

artifacts (list[ArtifactDefinition]) – artifact definitions.

Returns:

formatted string of artifact definition.

Return type:

str

abstractmethod WriteArtifactsFile(artifacts, filename)

Writes artifact definitions to a file.

Parameters:

• artifacts (list[ArtifactDefinition]) – artifact definitions to be written.

• filename (str) – name of the file to write artifacts to.

class artifacts.writer.JsonArtifactsWriter

Bases: ArtifactWriter

JSON artifacts writer interface.

FormatArtifacts(artifacts)

Formats artifacts to desired output format.

Parameters:

artifacts (list[ArtifactDefinition]) – artifact definitions.

Returns:

formatted string of artifact definition.

Return type:

str

class artifacts.writer.YamlArtifactsWriter

Bases: ArtifactWriter

YAML artifacts writer interface.

FormatArtifacts(artifacts)

Formats artifacts to desired output format.

Parameters:

artifacts (list[ArtifactDefinition]) – artifact definitions.

Returns:

formatted string of artifact definition.

Return type:

str

Module contents

ForensicArtifacts.com Artifact Repository.