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.
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. |
| doc | The description (or documentation). A human readable string that describes the artifact definition. See section: Description. |
| name | The name. An unique string that identifies the artifact definition. See section: Name. |
| sources | A list of source definitions. See section: Sources. |
| supported_os | Optional list that indicates which operating systems the artifact definition applies to. See section: 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. |
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.
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:
sources:
- type: COMMAND
attributes:
args: [-qa]
cmd: /bin/rpm
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:
- 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. |
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. as TYPE_INDICATOR constants.
Artifact group source
The artifact group source is a source that consists of a group of other artifacts e.g.
- 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.
- 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.
- type: FILE
attributes:
paths: ['%%environ_systemroot%%\System32\winevt\Logs\System.evtx']
Where attributes can contain the following values:
| Value | Description |
|---|---|
| paths | A list of file paths that can potentially be collected. The paths can use parameter expansion e.g. %%environ_systemroot%%. See section: Parameter expansion and globs. |
| separator | Optional path segment separator e.g. '\' for Windows systems. When not specified the default path segment separator is '/'. |
Path source
The path source is a source that consists of the contents of paths e.g.
- type: PATH
attributes:
paths: ['\Program Files']
separator: '\'
Where attributes can contain the following values:
| Value | Description |
|---|---|
| paths | A list of file paths that can potentially be collected. The paths can use parameter expansion e.g. %%environ_systemroot%%. See section: Parameter expansion and globs. |
| separator | Optional path segment separator e.g. '\' for Windows systems. When not specified the default path segment separator is '/'. |
Windows Registry key source
The Windows Registry key source is a source that consists of the contents of Windows Registry keys e.g.
sources:
- type: REGISTRY_KEY
attributes:
keys:
- 'HKEY_USERS\%%users.sid%%\Software\Microsoft\Internet Explorer\TypedURLs\*'
Where attributes can contain the following values:
| Value | Description |
|---|---|
| keys | A list of Windows Registry key paths that can potentially be collected. The paths can use parameter expansion e.g. %%users.sid%%. See section: Parameter expansion and globs. |
Windows Registry value source
The Windows Registry value source is a source that consists of the contents of Windows Registry values e.g.
- type: REGISTRY_VALUE
attributes:
key_value_pairs:
- {key: 'HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer\WindowsUpdate', value: 'CISCNF4654'}
Where attributes can contain the following values:
| Value | Description |
|---|---|
| key_value_pairs | A list of Windows Registry key paths and value names that can potentially be collected. The key path can use parameter expansion e.g. %%users.sid%%. See section: Parameter expansion and globs. |
Windows Management Instrumentation (WMI) query source
The Windows Management Instrumentation (WMI) query source is a source that consists of the output of Windows Management Instrumentation (WMI) queries e.g.
- type: WMI
attributes:
query: SELECT * FROM Win32_UserAccount WHERE name='%%users.username%%'
Where attributes can contain the following values:
| Value | Description |
|---|---|
| base_object | Optional WMI base object e.g. winmgmts:\root\SecurityCenter2 |
| query | The Windows Management Instrumentation (WMI) query. The query can use parameter expansion e.g. %%users.username%%. See section: Parameter expansion and globs. |
Supported operating system
Since operating system (OS) are a very common constraint, this has been provided as a separate option “supported_os” to simplify syntax. For supported_os no quotes are required. The currently supported operating systems are:
Android
Darwin (also used for Mac OS X)
iOS
Linux
Windows
supported_os: [Android, Darwin, iOS, Linux, Windows]
This can be translated to objectfilter as:
["os =='Android'" OR "os =='Darwin'" OR "os =='iOS'" "os=='Linux'" OR "os == 'Windows'"]
Parameter expansion and globs
Artifact definitions can use different types of parameters that need to be expanded at runtime, such as:
POSIX users variables, for example %%users.homedir%%
Windows evironment variables, for example %%environ_systemroot%%
Windows users variables, for example %%users.temp%%
POSIX users variables
Supported POSIX users variables are:
| Variable | Description |
|---|---|
| %%users.homedir%% | A user's home directory, for example '/home/username', '/root' or '/Users/username' |
Decomposition rules
Note that the following decomposition rules are approximations based on common usage scenarios.
%%users.homedir%% can be decomposed into:
‘/Users/*’ for Mac OS
‘/home/*’ and ‘/root’ for Linux
Windows evironment variables
Supported Windows evironment variables are:
| Variable | Description |
|---|---|
| %%environ_allusersappdata%% | The %AllUsersAppData% environment variable, which should fallback to the %ProgramData% environment variable if not available. |
| %%environ_allusersprofile%% | The %AllUsersProfile% environment variable. |
| %%environ_programdata%% | The %ProgramData% environment variable, which should fallback to the %AllUsersAppData% environment variable or '%AllUsersProfile%\Application Data' if not available. |
| %%environ_programfiles%% | The %ProgramFiles% environment variable. |
| %%environ_programfilesx86%% | The %ProgramFiles(x86)% environment variable. |
| %%environ_systemdrive%% | The %SystemDrive% environment variable, for example 'C:' |
| %%environ_systemroot%% | The %SystemRoot% environment variable, for example 'C:\Windows' |
| %%environ_windir%% | The %WinDir% environment variable, for example 'C:\Windows' |
Windows users variables
Supported Windows users variables are:
| Variable | Description |
|---|---|
| %%users.appdata%% | Windows version independent representation of a user specific %AppData% environment variable. |
| %%users.localappdata%% | Windows version independent representation of a user specific %LocalAppData% environment variable. |
| %%users.sid%% | A user's security identifier (SID) |
| %%users.temp%% | A user's temporary files directory, comparable to the %TEMP% or %TMP% environment variables, for example '/Users/username/temp' |
| %%users.username%% | A user's username, comparable to the %USERNAME% environment variable |
| %%users.userprofile%% | A user's (local) profile directory, for example '/Users/username' |
Decomposition rules
TODO: add information about system accounts
Note that the following decomposition rules are approximations based on common usage scenarios.
%%users.appdata%% can be decomposed into:
‘%%users.userprofile%%\AppData\Roaming’ for Windows Vista and later
‘%%users.userprofile%%\Application Data’
%%users.localappdata%% can be decomposed into:
‘%%users.userprofile%%\AppData\Local’ for Windows Vista and later
‘%%users.userprofile%%\Local Settings\Application Data’
%%users.localappdata_low%% can be decomposed into:
‘%%users.userprofile%%\AppData\LocalLow’ for Windows Vista and later
%%users.temp%% can be decomposed into:
‘%%users.localappdata%%\Temp’
%%users.userprofile%% can be decomposed into:
‘Documents and Settings\*’
‘Users\*’ for Windows Vista and later
Additional style notes
Artifact definition YAML files
Artifact definition YAML filenames should be of the form:
$FILENAME.yaml
Where $FILENAME is name of the file e.g. windows.yaml.
Each definition file should have a comment at the top of the file with a one-line summary describing the type of artifact definitions contained in the file e.g.
# Windows specific artifacts.
Lists
Generally use the short [] format for single-item lists that fit inside 80
characters to save on unnecessary line breaks:
supported_os: [Windows]
urls: ['https://artifacts-kb.readthedocs.io/en/latest/sources/windows/EventLog.html']
and the bulleted list form for multi-item lists or long lines:
paths:
- 'HKEY_USERS\%%users.sid%%\Software\Microsoft\Windows\CurrentVersion\Run\*'
- 'HKEY_USERS\%%users.sid%%\Software\Microsoft\Windows\CurrentVersion\RunOnce\*'
- 'HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Run\*'
- 'HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\RunOnce\*'
- 'HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\RunOnceEx\*'
Quotes
Quotes should not be used for doc strings, artifact names, and simple lists like supported_os.
Paths and URLs should use single quotes to avoid the need for manual escaping.
paths: ['%%environ_temp%%\*.exe']
urls: ['https://artifacts-kb.readthedocs.io/en/latest/sources/windows/EventLog.html']
Minimize the number of definitions by using multiple sources
To minimize the number of artifacts in the list, combine them using the supported_os attributes where it makes sense. e.g. rather than having FirefoxHistoryWindows, FirefoxHistoryLinux, FirefoxHistoryDarwin, do:
name: FirefoxHistory
doc: Firefox places.sqlite files.
sources:
- type: FILE
attributes:
paths:
- %%users.localappdata%%\Mozilla\Firefox\Profiles\*\places.sqlite
- %%users.appdata%%\Mozilla\Firefox\Profiles\*\places.sqlite
supported_os: [Windows]
- type: FILE
attributes:
paths: [%%users.homedir%%/Library/Application Support/Firefox/Profiles/*/places.sqlite]
supported_os: [Darwin]
- type: FILE
attributes:
paths: ['%%users.homedir%%/.mozilla/firefox/*/places.sqlite']
supported_os: [Linux]
supported_os: [Windows, Linux, Darwin]