Sharing¶

ADARE Web Platform¶

The ADARE web platform at adare.seclab-bonn.de is a community hub for sharing forensic experiments, environments, test functions, and results. Researchers can publish their work, download experiments created by others, and build on the community’s collective forensic analysis.

The platform supports sharing of:

Experiments – playbooks and metadata for forensic analysis workflows
Environments – VM configurations (OS profiles, settings)
Test functions – reusable validation logic for forensic artifacts
Experiment bundles – complete packages with experiments and all their dependencies
Run results – published experiment execution results with forensic data

All sharing operations are performed through the adare web command group.

Authentication¶

You must be logged in to interact with the ADARE web platform.

Logging In¶

adare web login

This starts an interactive authentication flow that connects your local ADARE installation to your account on the web platform.

Logging Out¶

adare web logout

Downloading Resources¶

Download shared content from the platform into your local project. All download commands require being inside an ADARE project directory (or specifying one with -p).

Downloading Experiments¶

adare web download experiment <ulid>

Downloads an experiment by its ULID (unique identifier). The experiment is added to your project’s experiments/ directory.

# Example
adare web download experiment 01JQXYZ123ABC

Downloading Test Functions¶

adare web download testfunction <name>

# Download a specific version
adare web download testfunction <name> -v 2

Downloads a test function by name. By default, the latest version is downloaded. Use -v to specify a particular version.

# Download the latest version
adare web download testfunction standard.file_exists

# Download version 3 specifically
adare web download testfunction excel.validate_columns -v 3

Downloading Environments¶

adare web download environment <name>

Downloads an environment configuration by name.

adare web download environment ubuntu24043

A downloaded recipe environment is a set of build inputs, not a disk: the disk is built locally on the first adare environment load. If it declares recipe.iso_name rather than recipe.iso, you must supply that ISO yourself – put it in ~/.adare/isos/ or pass --iso. See The environment publish contract and Consumer-supplied (BYO) ISOs – Windows only.

Downloading Bundles¶

adare web download bundle <ulid>

Downloads an experiment bundle: the experiment plus all its dependencies (testfunction sets and referenced environment configurations). Only descriptor/config files are downloaded — VM disk images are fetched later, on demand, when the environment is loaded (see below).

adare web download bundle 01JQXYZ123ABC

Options¶

-p, --project: Target project name or path.

Replicating an Experiment (one command)¶

To download a published experiment and immediately run it — the easiest way to reproduce a result end to end:

adare experiment replicate <ulid>

This downloads the bundle, loads the environment (fetching and verifying the VM disk via its sha256), loads the experiment, and runs it in test mode.

# Auto-selects the environment if the bundle has exactly one
adare experiment replicate 01JQXYZ123ABC

# Pick an environment when the bundle has more than one
adare experiment replicate 01JQXYZ123ABC -e ubuntu24043

# Run for real (production mode) instead of test mode
adare experiment replicate 01JQXYZ123ABC --production

# Only download and load, don't run
adare experiment replicate 01JQXYZ123ABC --skip-run

-e, --environment: Name of the environment to use. Required if the bundle has more than one; optional (auto-selected) if it has exactly one.
--production, --prod: Run in production mode with full integrity checks (default: test mode).
--skip-run: Download and load only, without starting a VM.
-p, --project: Target project name or path.

Running Downloaded Experiments Manually¶

You can also perform the download/load/run steps yourself instead of using adare experiment replicate:

# Download an experiment
adare web download experiment 01JQXYZ123ABC

# Run it (same as any local experiment)
adare experiment run downloaded-experiment -e ubuntu24043

# Or use it in dev mode
adare dev start -e ubuntu24043
adare dev playbook -f experiments/downloaded-experiment/playbook.yml

Downloaded test functions are automatically available for use in playbooks.

Syncing¶

Synchronize your project data with the web platform:

adare web sync

# Sync a specific project
adare web sync -p my-project

This updates the platform with your local project information, ensuring the web interface reflects your current experiments, environments, and test functions.

Publishing Results¶

Share your experiment run results with the community:

adare web publish <run_ulid>

# With explicit project
adare web publish 01JRXYZ456DEF -p my-project

This uploads the results of a specific experiment run, including all collected forensic data, test outcomes, and execution metadata. Published results are visible to other researchers on the platform.

The <run_ulid> is the unique identifier of the experiment run, which is displayed when you execute adare experiment run or can be found with adare experiment list-runs.

Submitting to the Community¶

Submit your experiments, test functions, or environments for inclusion in the shared community repository. Submissions are created as pull requests that are reviewed before being merged.

Submitting an Experiment¶

adare web submit experiment <name>

# With explicit project
adare web submit experiment browser-analysis -p my-project

Submitting a Test Function¶

adare web submit testfunction <name>

# Example
adare web submit testfunction standard.file_exists -p my-project

Submitting an Environment¶

adare web submit environment <name>

# Example
adare web submit environment ubuntu24043 -p my-project

Each submit command creates a pull request on the shared repository. You receive a PR URL upon successful submission that you can use to track the review process.

The experiment dependency pre-flight¶

An experiment declares two kinds of dependency: the test functions its tests: block calls, and the environments listed in its metadata.yml. The server resolves both when it ingests the pull request – long after the PR exists – and rejects the experiment with UNKNOWN_DEPENDENCY if either lookup fails.

To keep an unmergeable PR from being opened at all, adare web submit experiment checks the server’s published catalog (/api/testfunction/ and /api/environment/) before creating any branch or pull request. A failure names every unresolvable dependency and what to do about it, and no PR is created.

Two properties are worth knowing:

The check models the server’s lookup, which is an exact match on the stored, qualified <set>.<name> form. A bare playbook name (e.g. file_exists) is normalized to standard.<name> before that match – the same rule the client’s own resolver applies (adarelib’s get_testclass_from_testfunction) – so a name that resolves locally resolves here too. What the pre-flight does not do is re-derive that resolution for anything beyond the bare/standard case: a name qualified under the wrong set, or a set that is still registered under an unprefixed name because it has not been re-ingested since the server’s qualified-name migration, is still reported as missing (with a message naming which of the two it is).
The catalog only lists published entities. If a test function’s owning set is registered but not yet published, the pre-flight reports it as missing even though ingest would resolve it. Bypass the check in that case with --skip-dependency-check; the server remains authoritative either way.

If the server cannot be reached the check is skipped with a warning rather than blocking the submission. The catalog read is authenticated (the same Django token used for the rest of the submit flow), so an unauthenticated host is not a case the pre-flight needs to degrade for: adare web submit cannot create the pull request either without being logged in, and reports that plainly.

Order of submission¶

Because dependencies are resolved at ingest, submit and merge them before the experiment that needs them:

adare web submit testfunction <set> for every set the playbook calls, then merge those PRs.
adare web submit environment <name> for every environment in metadata.yml, then merge those PRs.
adare web submit experiment <name>.

Merging is a manual action in the Gitea web UI – the CLI does not auto-merge – so this is a multi-round process whenever a new dependency is involved.

The environment publish contract¶

An environment descriptor is checked before any branch or pull request is created, so a non-publishable one never reaches the shared repo – and a local filesystem path can never leak into it. What is required depends on the source.

Baked disk. vm must be an http(s) URL with a required vm_sha256, plus a vm_format when the URL path has no recognizable disk extension (share links like .../s/TOKEN/download have none). Prepare one with:

adare env publish-prepare my-env --vm-url https://cloud.example.org/s/TOKEN/download \
  --vm-format qcow2 --verify-url

A baked (non-Windows) publish carries no recipe, so by default nothing records which OS profile or installer ISO the disk came from. To attach that as optional provenance – for audit/reproducibility only, not a build recipe – pass --source-profile and, if you still have it, --source-iso-sha256:

adare env publish-prepare my-env --vm-url https://cloud.example.org/s/TOKEN/download \
  --vm-format qcow2 --source-profile ubuntu2404 --source-iso-sha256 <hex>

Neither field is required, neither is checked against any catalog, and neither makes the environment rebuildable – omitting them still publishes fine; you just lose the “what was this built from” record for later.

Recipe, Linux profile. recipe.iso must be an http(s) URL with a required recipe.iso_sha256. Linux ISOs are freely redistributable, so there is no reason to make a consumer hunt for one.

Recipe, Windows profile. Microsoft installer media cannot lawfully be rehosted, so a Windows recipe may instead declare recipe.iso_name (a bare filename) plus recipe.iso_sha256 and an optional plain-text recipe.iso_notes download pointer. The consumer supplies the ISO themselves; the digest proves they got the right one. Convert an existing recipe with:

adare env recipe-byo win11-autopsy-solr4

Exactly one of iso / iso_name may be set, and iso_sha256 is required in both forms – it is the actual integrity boundary. It must be written in canonical form (lowercase, no surrounding whitespace): the server stores the value verbatim and other clients compare it case-sensitively, so a non-canonical digest would publish an environment nobody can build.

The declared os.platform must also agree with what the profile actually builds, in both directions. profile: ubuntu2404 next to platform: windows describes a system it does not build, and is rejected.

Note

The consumer’s own environment load re-checks the same rules against their OS-profile catalog, which is the authoritative check for building. The server’s ingest validation is a coarse filter – it has no profile catalog and therefore cannot resolve a profile to a platform.

Warning

ADARE clients older than build-time provisioning silently ignore a recipe.provision block: unknown YAML keys are dropped, so such a client builds a bare OS install and reports success. It computes a different recipe hash (no provision key), so there is no false cache hit, but the operator gets a disk without the provisioned software and no warning. Consumers of a provisioned recipe need a client with this feature.

Checking Status¶

Verify whether your experiments or runs have been published to the server.

Checking an Experiment¶

adare web check experiment <ulid>

Reports whether the experiment exists on the server and its publication status.

Checking a Run¶

adare web check run <ulid>

Reports whether the experiment run exists on the server.