RecoverYantraSuite on the command line

Path to audit_trail.jsonl (or the folder holding it)

When to use it. Run at the close of a case, and again before disclosure, against the audit_trail.jsonl produced during the work. It proves the trail has not been edited, reordered or had entries inserted.

A recovery_manifest.json holding the sealed receipt, so entries REMOVED from the trail are detected too

When to use it. Add the recovery manifest whenever you need to prove nothing was REMOVED from the end of the trail. The manifest holds the sealed receipt the chain alone cannot see past.

What it costs. Without it, a trail that has been cut short at the end still verifies. For evidential work treat the manifest as required.

The mounted USB (e.g. E:\ on Windows, /media/usb on Linux)

When to use it. The mounted rescue USB. Use when you need to carry the tool to a machine that must not be written to or cannot be dismantled.

What it costs. Existing files on the stick are left alone, but confirm you have chosen the stick and not an external evidence drive.

Path to RecoverYantra-cli.exe to copy onto the USB (defaults to this executable)

When to use it. Point at a specific build when preparing a stick for a machine that must run a version you have already validated for the case.

A live Linux ISO, to make the USB bootable

When to use it. Supply a live Linux ISO when the target machine will not start, so the stick can boot it and read the drive in place.

What it costs. Writing an ISO makes the stick bootable and ERASES it. Check the ISO carries a USB boot record first, or the stick will be written perfectly and still not boot.

An extracted WinPE / live-Linux tree, to make it bootable

When to use it. Use an extracted WinPE or live-Linux tree instead of an ISO when your organisation maintains its own validated boot environment.

When to use it. Group several recovered sources - a laptop disk, a backup stick, a phone image - into one case for a single customer or job, and see everything recovered across them in one place, deduplicated by hash. `new` starts a case; `add` puts a source into it; `list` shows the cases or one case's sources; `status` totals its files and duplicates; `dedup` lists files found in more than one source. Use it when a job is more than one drive and you do not want to hand back the same file three times.

Raw device path (e.g. \\.\PhysicalDrive1 or /dev/sdb)

When to use it. Run the feasibility check the moment a drive arrives, before quoting, before imaging and before any promise to the client: it measures how much of the drive is unreadable and states the chances in plain words.

What it costs. A few hundred sampled reads - seconds on a healthy drive, and one gentle attempt per area on a failing one. Far cheaper than discovering mid-copy that the job was never viable.

An existing image file to check instead

When to use it. Check an existing image instead of a drive - for example to confirm a copy received from a client or another lab reads cleanly before work is billed against it.

Also write the answer as a PDF report at this path

When to use it. Write the verdict as a PDF wherever a client, insurer or case file needs the answer on record. The report states its numbers as ranges and says it is based on a sample.

How many areas of the drive to test (default 160)

When to use it. More samples narrow the stated range and cost more reads of the drive. The default suits a first assessment; raise it when the estimate must be tighter than a few percent.

What it costs. Each extra sample is another read of a drive that may be dying. On clearly failing hardware, keep the default and move to the copy.

Scan A: a session id from the history, or a recovery output folder

When to use it. The FIRST scan - a session id from the history, or the path to a recovery output folder. Normally the earlier pass, so that what the second scan added reads as the gain.

Scan B: the re-scan / deeper scan, same kind of reference

When to use it. The SECOND scan of the same source - the re-scan, the deeper scan, or the one run after a settings change. Files only in this scan are what it added, which is usually the reason for comparing at all.

What it costs. Comparing is read-only and charges nothing: it reads what the two scans already wrote. Files are matched by EXACT SHA-256 - a file with the same NAME but different bytes is reported in its own bucket and is never called the same file, because a deleted name can survive while the space under it is reused.

Write the diff to this folder (scan_compare.csv/.json)

When to use it. Write the comparison into this folder - scan_compare.csv or .json - so the four buckets go into a job sheet or a report rather than staying on screen. The folder is created if it is not there.

Export format (default csv)

When to use it. csv (the default) writes one row per file occurrence, so a changed file appears twice with its A side and its B side and the sheet opens in Excel; json writes the whole comparison for a script.

Also write the report (HTML, PDF, JSON) into DIR

When to use it. Write the detection report - HTML, PDF and JSON - into this folder: every device with its state, bus, serial and sector size, the hardware Windows can see but cannot use with the code and the fix, and the Plug-and-Play inventory. Use it when a customer or a partner says a drive is not detected: the report replaces "it does not work" with what the machine actually sees.

What it costs. The folder goes through the same pre-flight as every other writing job; the report is small, so only rights and a full disk stop it.

Skip the health read of each usable drive (faster)

When to use it. Skip the health read of each usable drive. Detection is then a listing only and returns in a second or two. Use it on a machine with many drives, or when a drive is known to be failing and you do not want even a test read against it before imaging.

Write the report even if the pre-flight objects

When to use it. Write the report even when the pre-flight objects to the folder. Use it only when you have read the objection and it does not apply - a report is a few hundred kilobytes, so the usual reason is a destination the check cannot judge.

What it costs. A refusal you have not read is not one you can override safely.

A folder of recovered eCryptfs files (encrypted ECRYPTFS_FNEK_ENCRYPTED.* names and/or eCryptfs bodies)

When to use it. Point at the folder of recovered eCryptfs files - an Ubuntu encrypted home or a Synology encrypted share pulled off the disk. Every encrypted filename and file body under it is decrypted with the passphrase you give.

The eCryptfs MOUNT passphrase (not the login password, unless the two are the same)

When to use it. The eCryptfs MOUNT passphrase, which is what unwraps the file keys. On Ubuntu it is usually NOT the login password: it is the long passphrase that ecryptfs-unwrap-passphrase prints at setup.

What it costs. A file or filename this passphrase does not unlock is reported and left encrypted, never handed back as invented plaintext, so a wrong passphrase costs nothing and produces nothing.

Where to write the decrypted tree

When to use it. Where to write the decrypted tree. Choose a folder off the source drive; the decrypted files are written under their recovered folder structure with their real names restored.

Write even if the pre-flight objects

When to use it. Write the decrypted tree even when the pre-flight objects, for example when free space is tight at the destination. Use it only after reading the warning.

What it costs. The pre-flight is what stops a half-written output; forcing past it can leave a partially decrypted tree behind.

A filename, part of one, or a wildcard (e.g. IMG_2019, *.jpg)

When to use it. Search every usable attached device for a file whose name matches PATTERN, without picking a drive first. Free, no licence needed - reads each device's index in seconds, the same tier as `--list`. Use it when the customer cannot say which of several drives holds what they want.

Give up on one drive after this long (default 20); a slow or failing drive never holds up the others

When to use it. Seconds allowed per device before moving on. A slow or failing device costs only its own row - the sweep never waits on one device at the expense of the rest.

List every drive checked, including the ones with no match

When to use it. Also sweep devices that are not in a normally-usable state, where possible. Use it only once the plain sweep has come back empty.

The damaged file to repair

When to use it. The damaged clip or photograph. Use when a file recovered without its index or its tables and will not open.

A healthy file from the same camera or phone

When to use it. A healthy file from the SAME camera or phone, ideally the same settings. The reference donates structure only.

What it costs. A reference from a different device produces a file that opens and is wrong. Picture data is never taken from the reference, and the repaired file contains only the damaged file's own frames.

Where to write the repaired copy (default: alongside the damaged file)

When to use it. Write the repaired copy to the case store when the original has to be preserved exactly as recovered.

Write the guide as a self-contained, searchable HTML page

When to use it. Produce the manual as a single searchable page to hand to a client, put on an internal share, or carry onto an air-gapped bench.

Write the guide as Markdown

When to use it. Produce Markdown when the content is going into your own documentation system or version control.

Raw device path (e.g. \\.\PhysicalDrive1 or /dev/sdb)

When to use it. Image the drive first whenever it is failing, whenever the original must go back to the client untouched, or whenever the matter may be produced. Every later step runs against the image.

What it costs. Imaging reads the whole drive once. On a drive that is actively dying that single pass is the best chance you get, so choose the retry policy before starting, not after.

Existing image/file to re-image

When to use it. Re-image an existing file, for example to convert a raw image to E01 or to make a working copy of an evidence image.

Output image path (.img or .E01)

When to use it. The image path on the case store. Name it for the exhibit, not for the machine.

Retries for bad sectors (default 3)

When to use it. Same trade-off as on acquire: more retries recover more marginal sectors and cost more reads of a failing surface.

raw .dd/.img (default) or compressed .E01 evidence image

When to use it. Use e01 for evidential work: it is compressed and carries the acquisition metadata other forensic tools expect. Use raw when the image will be mounted or read by tooling that only takes a flat image.

What it costs. Raw images are the size of the whole drive, including empty space.

Filesystem-aware (read-once): image only the space the filesystems say holds data, skipping free space without reading it. Faster and gentler on a failing drive, and a smaller image. Deleted files still in free space are NOT captured - use a full image for those.

When to use it. Filesystem-aware, read-once imaging: the filesystems' own allocation maps say which space holds data, and only that is read and copied - free space is skipped without touching the drive. Use it to image a large or failing drive faster and more gently, and to get a smaller image, when the live files are what matter.

What it costs. Deleted files still sitting in free space are NOT captured - free space is exactly where they live. When deleted data matters, take a full image (omit --targeted). A filesystem we cannot read a map for is imaged in full, so it is never wrong, only sometimes not smaller.

Measure the entropy of the data as it is copied and record which spans are high-entropy (encrypted or compressed) in the image's .map.json.

When to use it. Measure the entropy of the data as it is copied and record which spans are high-entropy - encrypted or compressed - in the image's .map.json. Use it to see at a glance whether a drive (or a region) is encrypted before spending time on recovery.

What it costs. Entropy cannot tell encryption from compression; a high-entropy span may be either. It is a signpost, not a verdict.

Start even when the pre-flight checks say this cannot finish: too little room, or writing onto the drive being recovered.

When to use it. Only after reading the objection. See acquire.

Also check each device's health (SMART + test reads), how it's connected, and what kind of device it is (CCTV recorder, phone, dashcam, card, ...) with advice on what to do

When to use it. Run before touching anything. It reports each device's health, how it is connected and what kind of device it is, which is what decides whether to recover directly or image first.

What it costs. Triage reads the drive. On a drive that is audibly failing, keep even this brief and go straight to imaging.

The raw NAND dump from the lab (spare areas included)

When to use it. The raw dump a lab read straight off the bare NAND chip, spare (OOB) areas included. It is not a disk image yet; this command is what turns it into one the recovery engine can read.

Where to write the reconstructed image

When to use it. Where to write the reconstructed image, on a different drive from the dump. The rebuilt image is written whole so the ordinary recovery flow can open it like any other disk image.

Report the geometry / scrambling / ECC / block-map findings and write nothing - run this first

When to use it. Read the dump and report the geometry, scrambling, error correction and block map it can work out, writing nothing. Run this first, before you commit to an image, because it costs nothing and tells you which figures still need supplying.

Page size in bytes, if the lab told you

When to use it. The page size in bytes when the lab already measured it, so it is taken as fact instead of inferred. Supplying a wrong figure produces an image that looks like a disk and holds nobody's files, so give it only when you know it.

Spare (OOB) size in bytes, if known

When to use it. The spare (out-of-band) area size in bytes when the lab measured it. It is taken as given rather than inferred; a wrong value shifts every page and the result carves to nothing, so supply it only when known.

Pages per block, if known

When to use it. How many pages make up an erase block when the lab measured it. It is used for the block map; an image can still be built without it, in the order the chip stores rather than logical order.

The lab's XOR de-scramble key file, if they have one

When to use it. A file holding the controller's XOR keystream when the lab supplied one. A dump scrambled from end to end cannot be de-scrambled by analysis alone, so this file is what makes such a dump readable at all.

The repeating XOR period in bytes, if known

When to use it. The length in bytes at which the scrambling keystream repeats, when it is known. It narrows the de-scramble search; leave it off and the period is recovered from the dump.

The controller's ECC scheme, if detection failed

When to use it. The controller's error-correction code, bch or hamming, when automatic detection could not settle it. It decides how spare bytes are read as correction data, so name it only when you know the controller.

ECC data step size in bytes

When to use it. How many data bytes each error-correction step covers, when detection needs help. It pairs with the scheme and strength; the wrong step corrects nothing, so supply it only from the controller's datasheet.

ECC strength (correctable bits per step)

When to use it. The correction strength, the number of bit errors each step can fix, when detection needs help. It has to match the controller; a value too low leaves errors, too high reads correction bytes as data.

Offset of the ECC bytes in the spare area

When to use it. Where the correction bytes begin inside each page's spare area, when it is known. It positions the read of the correction data; leave it off and the offset is inferred from the dump.

Offset of the block-address field in the spare area

When to use it. Where the logical block address sits inside the spare area, when the lab knows the controller. It is what lets the blocks be put back into the order a filesystem expects rather than the chip's own order.

Width of the block-address field in bytes

When to use it. How many bytes the logical block-address field takes in the spare area, when it is known. It pairs with the offset to read the block map; an image still builds without it in physical order.

Byte order of the block-address field

When to use it. The byte order of the block-address field, little or big, when the lab knows the controller. It only matters once the offset and width are set, and the wrong order scrambles the block map.

Write an image even when the geometry is not confident (the result may be nonsense that looks like a disk)

When to use it. Write an image even when the geometry could not be confirmed, taking the best guess rather than refusing. Use it only after --analyse shows how uncertain the figures are.

What it costs. A forced image is built on unconfirmed page and block sizes, so it can look like a sound disk while holding nonsense; the run records that it was forced.

Folder of encrypted files + ransom notes to examine

When to use it. Point at a folder holding encrypted files and the ransom note. The first question in every incident is which strain, because that decides what is realistically recoverable.

Observed filenames (encrypted files and/or note files)

When to use it. Supply observed filenames when you cannot give the tool access to the affected system, for example when working from a photograph of a screen or a client's email.

Ransom-note text file(s) to read

When to use it. Supply the ransom note itself. It is often the strongest single identifier of the family.

List the known ransomware families and their outlook

When to use it. Review the known families and their outlook when scoping an incident or briefing a client on likely outcomes.

Show the offline decryptor index for a family: the legitimate tool, publisher, LE-key status, flaw time-box and scope - or that no decryptor exists

When to use it. Check whether a legitimate published decryptor exists for the identified family before planning any other recovery.

What it costs. Where none exists the index says so. Do not substitute an unverified tool found by searching; that is how a second incident starts.

With --decryptor FAMILY: SHA-256 a downloaded decryptor and check it against the catalog (or print the hash to compare against the publisher)

When to use it. Always run this against a decryptor you have downloaded, before running it on client data.

What it costs. A decryptor obtained from anywhere other than the named publisher is an unknown executable being run against the only copy of the data.

Damage-assessment triage of a folder of hit files: how many are recoverable with no key, salvageable, or truly encrypted - before any decryption is attempted

When to use it. Run early. It reports how many files are recoverable with no key, how many are salvageable, and how many are genuinely encrypted, before anyone commits to a recovery plan or a payment discussion.

Find the decryption-free ORIGINALS the ransomware left behind (temp/autosave/backup, Recycle Bin, cloud caches, DB WAL sidecars) and pair them to the encrypted files

When to use it. Run on every incident. Many strains write a new encrypted file and delete the original; those deleted originals are frequently still present in free space, temp folders, the Recycle Bin, cloud caches and database sidecar files.

What it costs. This is the highest-value step in the whole flow and it is time-critical: continued use of the machine overwrites exactly the free space the originals are sitting in.

With --recover-originals: a $UsnJrnl:$J blob to resurrect what was deleted/hit, with paths

When to use it. Add the change journal to --recover-originals when you need the original PATHS as well as the file contents.

The full ransomware flow over a folder: triage + identify + recover-originals, fused into one honest recovery verdict (tier + prioritised action plan)

When to use it. The single command to run when you need one defensible answer for a client or an insurer: triage, identification and originals recovery fused into a stated outcome with a priority order.

With --verdict: a memory image / pagefile to scan for the key (aeskeyfind / rsakeyfind)

When to use it. Supply a memory image or pagefile with --verdict when the machine was captured while still running. Some strains leave key material in memory.

What it costs. This only helps if memory was captured before shutdown. It is a reason to capture memory first at the scene.

ESXi/Linux recovery playbook for a strain (esxiargs, blackbasta_esxi, lockbit_linux): flat-VMDK descriptor rebuild, intermittent-encryption damage map, keystream reuse

When to use it. Use for a hypervisor or Linux estate rather than a workstation. It produces the playbook for that family: descriptor rebuild, damage mapping, and what the specific strain leaves recoverable.

Rebuild a VMDK descriptor for an intact <name>-flat.vmdk; needs --flat-size BYTES

When to use it. Use when the flat VMDK holding the virtual machine's data survived but its small descriptor file was encrypted. Rebuilding the descriptor makes the intact data readable again.

What it costs. Requires the exact byte size of the flat file. A wrong size produces a descriptor that opens and misreads the disk.

Exact byte size of the -flat.vmdk (with --rebuild-vmdk)

When to use it. The exact size in bytes of the -flat.vmdk, taken from the file itself, not from the datastore listing.

Enumerate NAS (QNAP/Synology/LVM) snapshots from a file of LVM2 metadata text - the pre-attack recovery sources

When to use it. Enumerate NAS snapshots from the volume metadata. On QNAP, Synology and LVM estates these are frequently the fastest complete recovery and are missed because the attacker deleted the visible backups.

Living-off-the-land recovery: scan recovered scripts, registry exports and memory strings (a file or folder) for the BitLocker recovery key or archive password that abuse of BitLocker/EFS/7-Zip left behind. The secret is often still there, not an exfiltrated RSA key, so a ShrinkLocker case is not 'AES, unrecoverable'

When to use it. Scan recovered scripts, registry exports and memory strings for the recovery key or archive password that living-off-the-land ransomware left behind when it abused BitLocker, EFS or a bundled 7-Zip. The secret is often still present, so a ShrinkLocker case is not the unrecoverable AES it first looks like.

What it costs. It recovers the key the abuse left, it does not break BitLocker or strong archive crypto; a case with no left-behind key is reported as such rather than pretended recoverable.

Rebuild a document (Office/PDF) or media file from an INTERMITTENTLY-encrypted copy: recover the readable content the ransomware left between its encrypted blocks (R3b)

When to use it. Point at one INTERMITTENTLY-encrypted file - a document or a photo the ransomware only part-encrypted to save time. It pulls back the readable content left in the intact blocks between the encrypted ones. Use it when a large file is 'damaged' rather than fully scrambled.

What it costs. This is surviving content, not a decryption: the parts that WERE encrypted are still gone, so the result can be partial. It is written only when something readable is actually found.

Attempt a DOCUMENTED cryptographic weakness on an encrypted file - keystream reuse / repeating-key XOR - and write the plaintext only if it validates (R4)

When to use it. Point at one encrypted file to attempt a DOCUMENTED cryptographic weakness - a reused or repeating keystream, which some families leave. Use it when identification flags keystream reuse; it does nothing against a sound per-file key, and says so.

What it costs. The recovery is a heuristic and is accepted only when it validates as no-longer-ciphertext, so a wrong key is refused rather than written. Always confirm the recovered file opens before relying on it.

With --exploit: the keystream period in bytes if it is known (0 detects it)

When to use it. The keystream length in bytes, when you already know it from the family or from analysis; leave it at 0 to let the tool detect the period from the repeats in the ciphertext.

Where to write the recovered file (with --reconstruct or --exploit); without it, the result is only reported

When to use it. Where to write the reconstructed or recovered file. Choose a path off the affected drive; without it the result is only reported, not saved, so nothing is written until you ask for it.

When to use it. Work with a machine across the network. `agent` runs on the far machine and offers its disks read-only; `discover` and `list` find it and show what it has; `image` copies a disk that is not in use; `volumes` asks a running machine what it has and whether it can be frozen; `live` acquires a machine that is STILL IN USE, through a snapshot taken on that machine. Use the network route when the drive cannot be removed: a machine under warranty, a server that cannot be opened, a member of staff three time zones away, or a site you cannot attend.

What it costs. The transfer is only as reliable as the link. The image is verified on arrival, and a short image is reported failed rather than handed over as complete. `live` additionally creates a snapshot on the far machine, which allocates space there - so a live acquisition writes to the endpoint even though it never writes to the data being acquired, and every result records that. A volume that cannot be frozen is refused rather than read while it moves. Live acquisition is built into Enterprise, Forensics and the Suite.

Workflow id (e.g. forensics, data_recovery); omit to list them by category

When to use it. Show the full procedure for one job - every stage, what it is for, the safety gates that cannot be skipped, and the command that carries each one out. Use it when a technician is doing a job for the first time, when a job is done rarely enough that nobody remembers the order, or when a reviewer asks why the work was done the way it was.

Show only one category's workflows

When to use it. Show only data recovery, or only forensics. The two follow different orders because they are for different things: a recovery is judged on how much comes back, an examination on whether you can prove what you did. Verification therefore ends a recovery and sits in the MIDDLE of an examination, before any analysis. Use this to hand a new examiner only the sequence that applies to them.

Print only the commands, in order, ready to copy

When to use it. Print only the commands, in order, ready to paste. Use it to build a runbook, to script a job that is done the same way every time, or to check a script somebody else wrote actually follows the procedure.

Show the published practice each step comes from

When to use it. Show the published practice each stage comes from - ISO/IEC 27037, NIST SP 800-86, the ACPO principles. Use it when a client, an auditor or a court asks why a step exists, and when training staff who need to know the procedure is not this vendor's opinion.

The image's /data/system folder (holding gesture.key / password.key / locksettings.db)

When to use it. Point at the /data/system folder from an Android image when the device credential is needed and you are authorised to recover it.

What it costs. This works on an IMAGE you have already lawfully acquired. It is not a way into a handset you cannot already read.

Optional word list for a non-numeric password

When to use it. Supply a word list when the credential is a password rather than a numeric PIN.

Longest PIN to try (default 6; raising it costs time)

When to use it. Raise beyond 6 only when the case justifies the additional time, which grows sharply with each digit.

Examiner asserting lawful authority (recorded)

When to use it. The examiner asserting lawful authority.

Lawful basis: warrant / consent / statutory power

When to use it. The lawful basis. This step in particular should never be run without one recorded.

Examiner's organisation (recorded)

When to use it. The examining organisation, recorded against a step that in most jurisdictions will be examined closely if the matter is contested.

Case / FIR reference (recorded)

When to use it. The case reference, so this step appears in the same custody record as the acquisition it was run against.

Volume file or image (a raw device path also works)

When to use it. A VeraCrypt or TrueCrypt volume file, or a device path. Use when the data is inside an encrypted container and the password is lawfully available.

Volume password (omit to be prompted, so it is not left in shell history)

When to use it. Omit it to be prompted. Typing a password on the command line leaves it in shell history and in process listings.

What it costs. On a shared or logged bench, treat the prompt as the only acceptable route.

Personal Iterations Multiplier (0 = VeraCrypt default)

When to use it. Supply the Personal Iterations Multiplier if the volume was created with one. Without the correct value the correct password still fails.

Restrict to one cipher/cascade (e.g. AES, Serpent, AES-Twofish-Serpent). Omit to try all.

When to use it. Restrict to one cipher when it is known, which cuts the unlock time considerably.

What it costs. Restricting to the wrong cipher makes a correct password look wrong.

Restrict to one PRF (sha512/sha256/blake2s/whirlpool/streebog). Omit to try the usable ones.

When to use it. Restrict the hash function when it is known, for the same reason.

Treat as a legacy TrueCrypt volume (different iteration counts and TRUE magic)

When to use it. Set for a legacy TrueCrypt volume; the iteration counts and the header magic differ.

Unlock the hidden volume (header at offset 65536)

When to use it. Unlock the hidden volume rather than the outer one, where a hidden volume exists and you are authorised to access it.

Also write the structured result (no key material) here

When to use it. Write the structured result for the case file. No key material is written.

Folder to sanitise

When to use it. Sanitise the working folder at the end of a job, so a client's recovered data does not sit on the bench indefinitely.

What it costs. On flash, copy-on-write file systems and anything that has been backed up, overwriting a folder does not guarantee every copy is gone. The limits are stated every time.

Overwrite passes (default 1 - NIST SP 800-88 Rev. 1)

When to use it. Leave at 1. As on erase, more passes cost time and add nothing measurable.

Do not ask for confirmation

When to use it. For scripted end-of-job cleanup only, where the folder is chosen by the script and not by a person.

What it costs. Removing the confirmation removes the last check that the right folder was named.