Defining Artifacts


GRR artifacts are defined in YAML. The main artifact repository is hosted on GitHub. You can browse [existing artifact definitions] artifact-samples or read the exhaustive syntax overview.


We use a standard set of machine information collected from the host for variable interpolation. This collection of data is called the [knowledgebase] artifact-knowledgebase and is referenced with a %%variable%% syntax.

The artifact defines where the data lives. Once it is retrieved by GRR a parser can optionally be applied to turn the collected information into a more useful format, such as parsing a browser history file to produce URLs.

Uploading new definitions

New artifacts should be added to the [forensic artifacts repository] artifact-repository.

The changes can be imported into GRR by running make in the grr/artifacts directory. This will delete the existing artifacts, checkout the latest version of the artifact repository and add all of the YAML definitions into GRR’s directory. Running python build will have the same effect. The new artifacts will be available once the server is restarted.

Artifacts can also be uploaded via the Artifacts GUI and used immediately without the need for a restart.

Local definitions

Artifacts that are specific to your environment or need to remain private can be added to the grr/artifacts/local directory. This directory will remain untouched when you update the main artifacts repository. You can also use this directory to test new artifacts before they are added to the main public repository.

Flow templates

We currently support using the artifact format to call GRR-specific functionality, such as invoking a GRR client action or listing processes. Such “artifacts” are called flow templates and since they are GRR-specific they remain in the GRR repository in the grr/artifacts/flow_templates directory.

This is a temporary working name. We intend to rework this functionality into a more general, powerful and configurable way to call GRR from YAML.