Core Concepts

ADARE automates forensic experiments inside virtual machines and validates the results with test functions. Before diving into specific commands and configurations, it helps to understand the core building blocks and how they fit together.

Projects

A project is the top-level workspace that contains everything needed for a set of related forensic experiments. You create one with adare project create and work inside it for the duration of your analysis.

A project directory has a fixed layout:

my-project/
├── environments/      # Environment configuration files (YAML)
├── experiments/       # Individual experiment directories
├── shared/            # Shared resources
│   ├── data/          # Data files available to all experiments
│   └── tools/         # Tools and utilities shared across experiments
├── testfunctions/     # Custom test function modules
├── vm/                # Virtual machine files and images
└── run/               # Experiment execution results and logs

Each directory has a clear purpose. Environments and experiments live in their own subdirectories. The shared/ directory provides a place for data files and tools that multiple experiments need. Custom test functions go in testfunctions/. The run/ directory is created automatically when experiments execute and holds all output.

See Projects for details on project structure and management.

Environments

An environment is a configured virtual machine paired with an operating system definition. It is expressed as a YAML file that points to a disk image and describes the OS inside it.

An environment definition specifies:

  • Its VM source: either a disk image (.qcow2, .ova, or another supported format) or a build recipe

  • The operating system platform, distribution, and version

  • Any post-setup installations or configuration steps

  • Tags for organization and filtering

Environments are the “where” of an experiment – they define the system under test. The same experiment can target multiple environments to compare forensic behavior across OS versions or configurations.

An environment can be anchored in one of two ways:

  • Baked disk – the YAML points at a pre-built disk image and integrity is anchored on that disk’s hash. This is the default for Linux.

  • Recipe – the YAML declares the build inputs (OS profile, installer ISO + its expected SHA256, build params, and optional build-time provisioning steps) and the disk is built on load. Integrity is anchored on the inputs, which makes the environment rebuildable – the default for Windows, where evaluation editions and activation expire. See Recipe Environments.

Two consequences of the recipe model are worth knowing early.

Software under test is installed at build time, not per run. A recipe’s provision block runs once, while the disk is being built. That matters for forensic work specifically: installing an application writes Prefetch entries, registry keys and MFT records – exactly the artifacts an experiment measures – so an install repeated inside every run would contaminate its own results. The older postsetupinstallations field still runs per run and remains the right place for setup that must not persist. See Build-time provisioning.

A recipe ships as text, so the ISO has to come from somewhere. For Linux the installer ISO is freely redistributable and the recipe carries its URL. For Windows it is licensed and cannot be rehosted, so a recipe instead names the file and its SHA256 and the consumer supplies it. A ~110-line YAML then replaces tens of gigabytes of disk image that could not have been shared at all. See Consumer-supplied (BYO) ISOs – Windows only.

See Environments for VM configuration and setup.

Experiments

An experiment is a self-contained unit of forensic analysis. It combines a playbook (the automation script) with metadata that describes which environments it targets and how it should be run.

Each experiment directory contains:

experiments/my-experiment/
├── playbook.yml       # Automation script (actions, tests, variables)
├── metadata.yml       # Experiment metadata (target environments, tags)
├── img/               # Screenshots for GUI element recognition
└── shared/            # Experiment-specific shared resources

The metadata.yml file links the experiment to one or more environments. The img/ directory holds reference screenshots that ADARE uses for image-based GUI targeting. The shared/ directory can hold files specific to this experiment.

See Experiments for experiment structure and metadata.

Playbooks

A playbook is the YAML file at the heart of every experiment. It defines what ADARE should do inside the virtual machine: which actions to perform, which tests to run, and what variables to use.

A playbook has four sections:

  • settings: Global configuration such as idle time between actions, timeouts, and screenshot format.

  • variables: Named values (strings, paths, numbers) that can be referenced throughout the playbook using {{variable_name}} syntax. Variables support type declarations and descriptions.

  • tests: Definitions of test functions to validate forensic artifacts. Each test references a function by name and provides parameters.

  • actions: An ordered sequence of steps executed inside the VM. Actions include GUI interactions (click, keyboard, type), system commands, idle waits, screenshots, timestamps, and test invocations.

Actions are executed sequentially. ADARE sends each action to the guest agent inside the VM, which carries it out and reports the result back. GUI actions use image recognition or text detection to find on-screen targets.

See Actions for the complete action reference and Test Functions for available test functions.

The Experiment Lifecycle

Running an experiment follows a defined sequence from start to finish:

  1. Load: The playbook YAML is parsed and its actions are serialized into the database as PlaybookItem records. The original YAML content is stored for variable and test resolution. A hash is computed for integrity validation.

  2. Prepare VM: ADARE imports the VM image (if not already imported), creates a snapshot for safe rollback, and boots the virtual machine.

  3. Install Agent: The ADARE guest agent is transferred into the VM and started. It establishes a WebSocket connection back to the host, creating a command channel.

  4. Execute Actions: Actions are loaded from the database (not re-parsed from YAML), reconstructed into action objects, and sent one by one to the guest agent for execution. GUI interactions, system commands, and tests all flow through this channel.

  5. Collect Artifacts: Screenshots, logs, timestamps, and test results are collected in the run/ directory. Each run is identified by a unique ULID.

  6. Cleanup: The VM is shut down and optionally rolled back to its pre-experiment snapshot, ensuring a clean state for the next run.

This database-driven approach provides a complete audit trail, integrity validation, and efficient re-execution without repeated YAML parsing.

Test Mode vs Production Mode

ADARE supports two execution modes that serve different stages of the workflow.

Test mode (the default) is designed for iterative development:

  • Allows playbook modifications between runs without re-loading

  • Creates “fake runs” that can be cleaned up with adare experiment clean

  • No strict integrity enforcement

  • Ideal for building and debugging experiments

Production mode (enabled with the --production flag) is for real data collection:

  • Enforces integrity checks on the playbook and its actions

  • Creates tracked runs with full audit trails

  • Validates that the loaded playbook has not been tampered with

  • Ensures reproducibility and forensic soundness of results

The typical workflow is to develop in test mode until the experiment works correctly, then switch to production mode for actual data collection.

ADARE Web

ADARE Web is the community platform for sharing and discovering forensic experiments. It allows researchers to:

  • Download environments, experiments, and test functions published by others

  • Publish your own work for the community to use and reproduce

  • Sync project resources with the platform

  • Browse shared results and compare findings across different setups

ADARE Web integration is built into the CLI. After logging in, you can pull down shared resources directly into your project or push your experiments for others to use.

See Sharing for workflows around ADARE Web.