Forensic Artifact Definitions Database: Format specification

# Artifact definition format and style guide

The best way to show what an artifact definition is, is by example. The
following example is the artifact definition for the Windows EVTX System Event
Logs.

```yaml
name: WindowsSystemEventLogEvtx
doc: Windows System Event log for Vista or later systems.
sources:
- type: FILE
  attributes: {paths: ['%%environ_systemroot%%\System32\winevt\Logs\System.evtx']}
supported_os: [Windows]
urls: ['https://artifacts-kb.readthedocs.io/en/latest/sources/windows/EventLog.html']
```

The artifact definition can have the following values:

Value | Description
--- | ---
aliases | Optional list of alternate names to identify the artifact definition. Also see: See section: [Name](#name).
doc | The description (or documentation). A human readable string that describes the artifact definition. See section: [Description](#description).
name | The name. An unique string that identifies the artifact definition. See section: [Name](#name).
sources | A list of source definitions. See section: [Sources](#sources).
supported_os | Optional list that indicates which operating systems the artifact definition applies to. See section: [Supported operating system](#supported-operating-system).
urls | Optional list of URLs with more contextual information. Ideally the artifact definition links to an article that discusses the artifact in more depth for example on [Digital Forensics Artifact Knowledge Base](https://github.com/ForensicArtifacts/artifacts-kb).

## Deprecated values

Value | Description
--- | ---
conditions | Optional list of conditions that describe when the artifact definition should apply. Note that conditions have been deprecated as of version 20220710.
labels | Optional list of predefined labels. Note that labels have been deprecated as of version 20220311.
provides | Optional list of placeholder values that the artifact provides.

## Name

The name of an artifact definition should be in CamelCase name without spaces.

Prefix platform specific artifact definitions with the name of the operating
system using "Linux", "MacOS" or "Windows".

If not platform specific:

* prefix with the application name, for example "ChromeHistory".
* prefix with the name of the subsystem, for example "WMIComputerSystemProduct".

Commonly used prefixes:

Prefix | Description
--- | ---
Android | Android operating system specific artifact definition.
Darwin | Mac OS (or Darwin) operating system specific artifact definition.
iOS | iOS operating system specific artifact definition.
Linux | Linux operating system specific artifact definition.
Shell | Shell user-interface specific artifact definition.
User | User specific artifact definition.
Unix | Unix operating system (or POSIX) specific artifact definition.
Windows | Windows operating system specific artifact definition.

Suffix artifact definitions with the type of artifact, for example are files use
"BrowserHistoryFile" instead of "BrowserHistory" to reduce ambiguity.

Suffix | Description
--- | ---
ConfigurationFile | Contents of one or more configuration files.
Directory | Contents of one or more directories.
File | Contents of one or more files.
LogFile | Contents of one or more log files.
PlistFile | Contents of one or more property list (plist) files.
SQLiteDatabaseFile | Contents of one or more SQLite database files.

## Description

**Style note**: Typically one line description of the artifact, mentioning
important caveats. If more than one line is necessary, use the multi-line YAML
Literal Style as indicated by the `|` character.

```yaml
doc: |
  The Windows run keys.

  Note users.sid will currently only expand to SIDs with profiles on the system,
  not all SIDs.
```

**Style note**: the short description (first line) and the longer portion are
separated by an empty line.

**Style note**: explicit newlines (\n) should not be used.

## Sources

Every source definition starts with a `type` followed by arguments for example:

```yaml
sources:
- type: COMMAND
  attributes:
    args: [-qa]
    cmd: /bin/rpm
```

```yaml
sources:
- type: FILE
  attributes:
    paths:
    - /root/.bashrc
    - /root/.cshrc
    - /root/.ksh
    - /root/.logout
    - /root/.profile
    - /root/.tcsh
    - /root/.zlogin
    - /root/.zlogout
    - /root/.zprofile
    - /root/.zprofile
```

**Style note**: where sources take a single argument with a single value, the
one-line {} form should be used to save on line breaks as below:

```yaml
- type: FILE
  attributes: {paths: ['%%environ_systemroot%%\System32\winevt\Logs\System.evtx']}
```

Value | Description
--- | ---
attributes | A dictionary of keyword attributes specific to the type of source definition.
type | The source type.
supported_os | Optional list that indicates which operating systems the artifact definition applies to. See section: [Supported operating system](#supported-operating-system).

## Deprecated values

Value | Description
--- | ---
conditions | Optional list of conditions to when the artifact definition should apply. See section: Note that conditions have been deprecated as of version 20220710.

### Source types

Currently the following different source types are defined:

Value | Description
--- | ---
ARTIFACT_GROUP | A source that consists of a group of other artifacts.
COMMAND | A source that consists of the output of a command.
FILE | A source that consists of the contents of files.
PATH | A source that consists of the contents of paths.
REGISTRY_KEY | A source that consists of the contents of Windows Registry keys.
REGISTRY_VALUE | A source that consists of the contents of Windows Registry values.
WMI | A source that consists of the output of Windows Management Instrumentation (WMI) queries.

The sources types are defined in
[definitions.py](https://github.com/ForensicArtifacts/artifacts/blob/main/artifacts/definitions.py).
as TYPE_INDICATOR constants.

### Artifact group source

The artifact group source is a source that consists of a group of other artifacts e.g.

```yaml
- type: ARTIFACT_GROUP
  attributes:
    names:
    - WindowsRunKeys
    - WindowsServices
```

Where `attributes` can contain the following values:

Value | Description
--- | ---
names | A list of artifact definition names that make up this "composite" artifact. This can also be used to group multiple artifact definitions into one for convenience.

### Command source

The command source is a source that consists of the output of a command e.g.

```yaml
- type: COMMAND
  attributes:
    args: [-qa]
    cmd: /bin/rpm
```

Where `attributes` can contain the following values:

Value | Description
--- | ---
args | A list arguments to pass to the command.
cmd | The path of the command.

### File source

The file source is a source that consists of the contents of files e.g.

```yaml
- type: FILE
  attributes:
    paths: ['%%environ_systemroot%%\System32\winevt\Logs\System.evtx']
```

Where `attributes` can contain the following values:

Value | Description
--- | ---
paths | A list o