asc.dfir.dfir_ps role – Deploy the DFIR automated-processing server

Note

This role is part of the asc.dfir collection (version 2.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: git clone git@ssh.dev.azure.com:v3/cloudasc/iac-ansible-collections/dfir $HOME/.ansible/collections/ansible_collections/asc/dfir.

To use it in a playbook, specify: asc.dfir.dfir_ps.

Entry point main – Deploy the DFIR automated-processing server

Synopsis

  • Deploys and configures the Windows processing server that runs automated evidence processing for the DFIR environment.

  • It mounts the DFIR working-copy fileshare and schedules the mount, storage-account sync and disk-processing tasks that move uploaded evidence through the chain-of-custody storage accounts.

  • When ‘dfir_autopsy’ is enabled it is also an Autopsy multi-user client, and creates the environment’s Autopsy case (named after env_name) under Cases on the fileshare.

  • With ‘dfir_autopsy’ enabled, the disk-processing task queues every complete image for Autopsy as soon as it is mounted and unlocked, so Autopsy runs alongside the tools instead of after them. Images that are not Windows are queued too, although they skip the mount and the tools. The ‘Autopsy Ingest’ scheduled task adds the queued images to the case one at a time with the dfir ingest profile, giving Autopsy the BitLocker password or recovery key from config.txt that unlocked the image.

  • A failed or interrupted Autopsy ingest is not retried, because Autopsy may already have added the image to the case. Its job file waits in C:\Processing_Scripts\autopsy\failed with the reason and Autopsy’s output; moving it back to queue retries it. Images processed before Autopsy was enabled are not queued; deleting their .complete marker processes them again.

  • The ingest runs Autopsy as the processing server’s admin account and stops any other Autopsy that account has open, so do not use the Autopsy GUI as that account on this server.

Parameters

Parameter

Comments

dfir_ps_config

dictionary

‘dfir_ps’ role configuration

autopsy_ingest_timeout_hours

integer

How long one Autopsy ingest may run before it is stopped as hung and marked failed. Multi-TB images can take more than a day.

Default: 72

copy_retries

integer

Max recopy-and-reverify attempts per file during intake (each retry re-reads the whole file)

Default: 3

custody_flush_seconds

integer

How often the local custody manifest and logs are bulk-flushed to the analyst share

Default: 300

enabled

boolean

Whether to enable the ‘dfir_ps’ role

Choices:

  • false ← (default)

  • true

hash_buffer_mb

integer

Read-buffer (MiB) for SHA256 hashing; larger cuts transactions on big files only, costs RAM per parallel hasher, capped at 2047 (int32)

Default: 512

processing_tools

list / elements=dictionary

Ordered roster of disk-processing tools run against each mounted image.

Tools run in ascending order; consecutive parallel tools run together as a batch, while a non-parallel tool is a barrier that must finish before the next order runs.

Each tool is a script at C:\Processing_Scripts\tools\<name>.ps1 invoked with a source path and its own output subfolder.

name

string / required

Tool name; maps to C:\Processing_Scripts\tools\<name>.ps1

order

integer / required

Run order (ascending); earlier orders complete before later ones start

parallel

boolean / required

Whether this tool may run concurrently with adjacent tools, or must run on its own as a barrier

Choices:

  • false

  • true

source

string / required

What the tool reads - drive for the mounted read-only volume, output for the artifacts an earlier stage collected

Choices:

  • "drive"

  • "output"

psvm_user

string

Username for the VM

Default: "forensics-admin"

sync_max_wait_seconds

integer

Debounce cap - force a batch when active uploads have run this long without settling

Default: 1800

sync_quiet_seconds

integer

Debounce - fire a batch once uploads have been quiet for this long

Default: 300

vm_name_prefix

string

Prefix for the VM name

Default: "psdfir"

vm_size

string

Size of the VM to deploy (Azure VM size).

The default (8 vCPU, 32 GiB, not burstable) leaves room for Autopsy ingest, which runs on this server when ‘dfir_autopsy’ is enabled, alongside KAPE and the intake engine. Burstable B-series sizes run out of CPU credits under sustained processing.

Azure only resizes in place between sizes that both have, or both lack, a local temp disk. A server on a temp-disk size (for example Standard_B2ms) moves to Standard_D8ads_v5 instead.

Default: "Standard_D8as_v5"

winvm_user

string

Optional override for the processing-server admin username (falls back to the Ansible connection user)

Authors

  • Ignace De Cock