forensicartifacts

README

forensicartifacts for Go

This library is a Go implementation for parsing and validating forensic artifact definition files.

Installation

go get dfir.software/forensicartifacts

Artifact definition files

The following shows an example for an artifact definition file. It defines the location of linux audit log files on a system.

name: LinuxAuditLogFiles
doc: Linux audit log files.
sources:
- type: FILE
  attributes: {paths: ['/var/log/audit/*']}
supported_os: [Linux]

http://forensicartifacts.com/ is the main repository for forensic artifacts definitions, the artifact definition files are located in https://github.com/ForensicArtifacts/artifacts/tree/master/data.

Example

The following example shows how to decode an artifact definition yaml file and print all found validation flaws.

package main

import (
	"fmt"

	"github.com/spf13/afero"
	"dfir.software/forensicartifacts"
)

func main() {
	// parse artifacts
	artifactDefinitions, flaws, err := forensicartifacts.DecodeFiles(false, osfs.New(), []string{"windows.yaml"})
	if err != nil {
		panic(err)
	}

	// print all problems found
	for _, flaw := range flaws {
		fmt.Printf("Problem in %s %s: %s\n", flaw.File, flaw.ArtifactDefinition, flaw.Message)
	}

    // print all artifact definitions found
	for _, artifactDefinition := range artifactDefinitions {
		fmt.Printf("Decoded artifact definition %s\n", artifactDefinition.Name)
	}
}

Changes to the style guide

• The provides and conditions key in the artifacts definition is ignored
• cmd parameter are expanded
• args are optional

Validator

This projects also contains a validator for forensic artifact definition files. It can be installed via go get:

go get dfir.software/forensicartifacts/cmd/forensicartifactsvalidator

To run just provide the location of the forensic artifact definition files:

forensicartifactsvalidator -v -s artifacts/data/*.yaml

The output is a list of potential issues in those files.

Documentation

Overview

Package forensicartifacts is a Go implementation for parsing and validating forensic artifact definition files.

Artifact definition files

The following shows an example for an artifact definition file. It defines the location of linux audit log files on a system.

name: LinuxAuditLogFiles
doc: Linux audit log files.
sources:
- type: FILE
  attributes: {paths: ['/var/log/audit/*']}
supported_os: [Linux]

http://forensicartifacts.com/ is the main repository for forensic artifacts definitions, the artifact definition files are located in https://github.com/ForensicArtifacts/artifacts/tree/master/data.

Example

The following example shows how to decode an artifact definition yaml file and print all found validation flaws.

package main

import (
	"fmt"

	"github.com/spf13/afero"
	"dfir.software/forensicartifacts"
)

func main() {
	// parse artifacts
	artifactDefinitions, flaws, err := forensicartifacts.DecodeFiles(false, osfs.New(), []string{"windows.yaml"})
	if err != nil {
		panic(err)
	}

	// print all problems found
	for _, flaw := range flaws {
		fmt.Printf("Problem in %s %s: %s\n", flaw.File, flaw.ArtifactDefinition, flaw.Message)
	}

	// print all artifact definitions found
	for _, artifactDefinition := range artifactDefinitions {
		fmt.Printf("Decoded artifact definition %s\n", artifactDefinition.Name)
	}
}

Changes to the style guide

Some elements are changed from the official implementation.

1. The `provides` and `conditions` key in the artifacts definition is ignored
2. The `cmd` parameter is expanded
3. `args` are optional

Validator

This projects also contains a validator for forensic artifact definition files. It can be installed via go get:

go get dfir.software/forensicartifacts/cmd/forensicartifactsvalidator

To run just provide the location of the forensic artifact definition files:

forensicartifactsvalidator -v -s artifacts/data/*.yaml

The output is a list of potential issues in those files.

Index

• func DecodeFile(filename string) ([]ArtifactDefinition, []Flaw, error)
• func ProcessFiles(artifacts []string, validate, filter, addPartitions bool, ...) ([]ArtifactDefinition, []Flaw, error)
• type ArtifactDefinition
  • func Expand(infs forensicfs.ForensicFS, artifactDefinitions []ArtifactDefinition, ...) ([]ArtifactDefinition, error)
• type Attributes
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (dec *Decoder) Decode() ([]ArtifactDefinition, error)
• type Flaw
  • func ValidateArtifactDefinitions(artifactDefinitionMap map[string][]ArtifactDefinition) []Flaw
• type KeyValuePair
• type Severity
• type Source

Functions

func DecodeFile

func DecodeFile(filename string) ([]ArtifactDefinition, []Flaw, error)

DecodeFile takes a single artifact definition file to decode.

func ProcessFiles

func ProcessFiles(artifacts []string, validate, filter, addPartitions bool, infs forensicfs.ForensicFS, filenames []string) ([]ArtifactDefinition, []Flaw, error)

ProcessFiles takes a list of artifact definition files. Those files are decoded, validated, filtered and expanded.

Types

type ArtifactDefinition

type ArtifactDefinition struct {
	Name        string   `yaml:"name,omitempty"`
	Doc         string   `yaml:"doc,omitempty"`
	Sources     []Source `yaml:"sources,omitempty"`
	Conditions  []string `yaml:"conditions,omitempty"`
	Provides    []string `yaml:"provides,omitempty"`
	Labels      []string `yaml:"labels,omitempty"`
	SupportedOs []string `yaml:"supported_os,omitempty"`
	Urls        []string `yaml:"urls,omitempty"`
}

The ArtifactDefinition describes an object of digital archaeological interest.

func Expand

func Expand(infs forensicfs.ForensicFS, artifactDefinitions []ArtifactDefinition, addPartitions bool) ([]ArtifactDefinition, error)

Expand performs parameter expansion and globbing on a list of artifact definitions.

type Attributes

type Attributes struct {
	Names         []string       `yaml:"names,omitempty"`
	Paths         []string       `yaml:"paths,omitempty"`
	Separator     string         `yaml:"separator,omitempty"`
	Cmd           string         `yaml:"cmd,omitempty"`
	Args          []string       `yaml:"args,omitempty"`
	Keys          []string       `yaml:"keys,omitempty"`
	Query         string         `yaml:"query,omitempty"`
	BaseObject    string         `yaml:"base_object,omitempty"`
	KeyValuePairs []KeyValuePair `yaml:"key_value_pairs,omitempty"`
}

Attributes are specific to the type of source definition. They contain information

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder reads and decodes YAML values from an input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

The decoder introduces its own buffering and may read data from r beyond the YAML values requested.

func (*Decoder) Decode

func (dec *Decoder) Decode() ([]ArtifactDefinition, error)

Decode reads the next YAML-encoded value from its input and stores it in the value pointed to by v. See the documentation for Unmarshal for details about the conversion of YAML into a Go value.

type Flaw

type Flaw struct {
	Severity           Severity
	Message            string
	ArtifactDefinition string
	File               string
}

Flaw is a single issue found by the validator

func ValidateArtifactDefinitions

func ValidateArtifactDefinitions(artifactDefinitionMap map[string][]ArtifactDefinition) []Flaw

ValidateArtifactDefinitions validates a map of artifact definitions and returns any flaws found in those.

type KeyValuePair

type KeyValuePair struct {
	Key   string `yaml:"key,omitempty"`
	Value string `yaml:"value,omitempty"`
}

A KeyValuePair represents Windows Registry key path and value name that can potentially be collected.

type Severity

type Severity int

Severity level of a flaw.

const (
	Common  Severity = iota // Common errors
	Info                    // Style violations, will not create any issues
	Warning                 // Will compile but might create unexpected results
	Error                   // Will likely become an error
)

Severity levels of a flaw.

type Source

type Source struct {
	Type        string     `yaml:"type,omitempty"`
	Attributes  Attributes `yaml:"attributes,omitempty"`
	Conditions  []string   `yaml:"conditions,omitempty"`
	SupportedOs []string   `yaml:"supported_os,omitempty"`
}

The Source type objects define the source of the artifact data. 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;
• directory; the source is one or more directories;
• 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:\\Windows\\System32\\winevt\\Logs\\AppEvent.evt a file artifact definition, pointing to the Application Event Log file.