artifacts package

Submodules

artifacts.artifact module

The artifact definition.

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

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

provides

hints to what information the artifact definition provides.

Type

list[str]

sources

sources.

Type

list[str]

supported_os

supported operating systems.

Type

list[str]

urls

URLs with more information about the artifact definition.

Type

list[str]

AppendSource(type_indicator, attributes)[source]

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()[source]

Represents an artifact as a dictionary.

Returns

artifact attributes.

Return type

dict[str, object]

artifacts.definitions module

Constants and definitions.

artifacts.errors module

The error objects.

exception artifacts.errors.CodeStyleError[source]

Bases: Error

Error that is raised when code formatting fails style checks.

exception artifacts.errors.Error[source]

Bases: Exception

The error interface.

exception artifacts.errors.FormatError[source]

Bases: Error

Error that is raised when the format is incorrect.

exception artifacts.errors.MissingDependencyError[source]

Bases: Error

Artifact references artifact that is undefined.

artifacts.reader module

The artifact reader objects.

class artifacts.reader.ArtifactsReader[source]

Bases: BaseArtifactsReader

Artifacts reader common functionality.

ReadArtifactDefinitionValues(artifact_definition_values)[source]

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')[source]

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)[source]

Reads artifact definitions from a file.

Parameters

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

Yields

ArtifactDefinition – an artifact definition.

abstract ReadFileObject(file_object)[source]

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.

class artifacts.reader.BaseArtifactsReader[source]

Bases: object

Artifacts reader interface.

supported_os

supported operating systems.

Type

set[str]

abstract ReadArtifactDefinitionValues(artifact_definition_values)[source]

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.

abstract ReadDirectory(path, extension=None)[source]

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.

abstract ReadFile(filename)[source]

Reads artifact definitions from a file.

Parameters

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

Yields

ArtifactDefinition – an artifact definition.

abstract ReadFileObject(file_object)[source]

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.

class artifacts.reader.JsonArtifactsReader[source]

Bases: ArtifactsReader

JSON artifacts reader.

ReadFileObject(file_object)[source]

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[source]

Bases: ArtifactsReader

YAML artifacts reader.

ReadFileObject(file_object)[source]

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[source]

Bases: object

Artifact definitions registry.

classmethod CreateSourceType(type_indicator, attributes)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Retrieves the artifact definitions.

Returns

artifact definitions.

Return type

list[ArtifactDefinition]

GetUndefinedArtifacts()[source]

Retrieves the names of undefined artifacts used by artifact groups.

Returns

undefined artifacts names.

Return type

set[str]

ReadFileObject(artifacts_reader, file_object)[source]

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')[source]

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)[source]

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)[source]

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)[source]

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)[source]

Registers source types.

Source types are identified based on their type indicator.

Parameters

source_type_classes (list[type]) – source types.

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)[source]

Bases: SourceType

Artifact group source type.

AsDict()[source]

Represents a source type as a dictionary.

Returns

source type attributes.

Return type

dict[str, str]

TYPE_INDICATOR = 'ARTIFACT_GROUP'
class artifacts.source_type.CommandSourceType(args=None, cmd=None)[source]

Bases: SourceType

Command source type.

AsDict()[source]

Represents a source type as a dictionary.

Returns

source type attributes.

Return type

dict[str, str]

TYPE_INDICATOR = 'COMMAND'
class artifacts.source_type.DirectorySourceType(paths=None, separator='/')[source]

Bases: SourceType

Directory source type.

AsDict()[source]

Represents a source type as a dictionary.

Returns

source type attributes.

Return type

dict[str, str]

TYPE_INDICATOR = 'DIRECTORY'
class artifacts.source_type.FileSourceType(paths=None, separator='/')[source]

Bases: SourceType

File source type.

AsDict()[source]

Represents a source type as a dictionary.

Returns

source type attributes.

Return type

dict[str, str]

TYPE_INDICATOR = 'FILE'
class artifacts.source_type.PathSourceType(paths=None, separator='/')[source]

Bases: SourceType

Path source type.

AsDict()[source]

Represents a source type as a dictionary.

Returns

source type attributes.

Return type

dict[str, str]

TYPE_INDICATOR = 'PATH'
class artifacts.source_type.SourceType[source]

Bases: object

Artifact definition source type interface.

abstract AsDict()[source]

Represents a source type as a dictionary.

Returns

source type attributes.

Return type

dict[str, str]

TYPE_INDICATOR = None
property type_indicator

type indicator.

Type

str

class artifacts.source_type.SourceTypeFactory[source]

Bases: object

Source type factory.

classmethod CreateSourceType(type_indicator, attributes)[source]

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)[source]

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()[source]

Retrieves the source type indicators.

Returns

source type indicators.

Return type

list[str]

classmethod GetSourceTypes()[source]

Retrieves the source types.

Returns

source types.

Return type

list[type]

classmethod RegisterSourceType(source_type_class)[source]

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)[source]

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)[source]

Bases: SourceType

WMI query source type.

base_object

WMI base object.

Type

str

query

WMI query.

Type

str

AsDict()[source]

Represents a source type as a dictionary.

Returns

source type attributes.

Return type

dict[str, str]

TYPE_INDICATOR = 'WMI'
class artifacts.source_type.WindowsRegistryKeySourceType(keys=None)[source]

Bases: SourceType

Windows Registry key source type.

AsDict()[source]

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)[source]

Validates this key against supported key names.

Parameters

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

Raises

FormatError – when key is not supported.

class artifacts.source_type.WindowsRegistryValueSourceType(key_value_pairs=None)[source]

Bases: SourceType

Windows Registry value source type.

AsDict()[source]

Represents a source type as a dictionary.

Returns

source type attributes.

Return type

dict[str, str]

TYPE_INDICATOR = 'REGISTRY_VALUE'

artifacts.writer module

The artifact writer objects.

class artifacts.writer.ArtifactWriter[source]

Bases: BaseArtifactsWriter

File artifacts writer.

abstract FormatArtifacts(artifacts)[source]

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)[source]

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[source]

Bases: object

Artifacts writer interface.

abstract FormatArtifacts(artifacts)[source]

Formats artifacts to desired output format.

Parameters

artifacts (list[ArtifactDefinition]) – artifact definitions.

Returns

formatted string of artifact definition.

Return type

str

abstract WriteArtifactsFile(artifacts, filename)[source]

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[source]

Bases: ArtifactWriter

JSON artifacts writer interface.

FormatArtifacts(artifacts)[source]

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[source]

Bases: ArtifactWriter

YAML artifacts writer interface.

FormatArtifacts(artifacts)[source]

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.