SakshyaYantra Examiner 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.

Turn on an advanced method (e.g. checkm8, mtk_bootrom, qualcomm_edl)

When to use it. Turn on an advanced acquisition method for a case that needs it and is authorised for it. These methods interact with the device, so they are off until an examiner opts in on the record.

What it costs. Enabling is recorded in the audit trail with the operator and case. An advanced method can alter the device; decide before the exhibit is in front of you, not during.

Turn an advanced method back off

When to use it. Turn a method back off once the step that needed it is complete, so the next case starts from the conservative default.

Show the acquisition toolbox: the public methods (checkm8/mtkclient/edl/adb...), what's installed, and what is equipped for this case

When to use it. Run before an acquisition to see which external tools are actually installed on this machine and which methods are therefore available today.

What it costs. The product orchestrates the operator's own tools for advanced methods; it does not bundle exploits. A method with no tool present is not available however the case is authorised.

Examiner making the choice (recorded)

When to use it. Name the examiner making the decision. The choice belongs in the record alongside the result it produced.

Case reference (recorded)

When to use it. Tie the capability decision to the case it was made for.

ask "<question>" --case FOLDER | index --case FOLDER | cite --citation FILE (see caseqa ... -h)

When to use it. A verb and its options: `ask "<question>" --case FOLDER` returns the verbatim passages of the case that answer it, each with an exact citation (exhibit id + byte/field offset), or says "not found in this case"; `index --case FOLDER` builds the retrieval index; `cite --citation FILE` re-checks a saved answer's citations against the live case. For `ask`, -k N sets how many passages come back, --kind evidence|finding|note|report|overlay|exhibit and --tier executive|judicial|detailed narrow what is searched (both repeatable), --json prints the whole result including the citations, and --include-ai-observations searches AI observations already in the case (they are labelled, and excluded otherwise). --embedder DIR adds meaning-based search from a local embedding model. Add `--model PATH` (local only) for an optional summary, which needs --reading "<your own reading>" or --inconclusive and --examiner NAME first: the model is not even loaded until the reading is sealed.

What it costs. The answer is grounded, cited retrieval, not a chatbot: an unanswerable question is refused rather than guessed. Any local-model summary is a labelled AI observation, sealed after the examiner's own reading, never a finding; a claim citing an unsupplied passage refuses the whole answer. The retrieval makes no network connection.

The case folder; omit to use the most recent case

When to use it. The case folder to report on. Omit it and the most recently worked case is used, so an examiner mid-case runs the command with no arguments. Read only - the trail is never re-opened or locked.

What it costs. Free: it reads the case's own audit.jsonl and case.json and writes a report; it charges nothing and touches no evidence.

Where to write the report (default: the case's reports/ folder)

When to use it. Where to write the report. The default is the case's own reports/ folder, so it travels with the case; point it elsewhere to hand a copy straight to a shared drive.

Comma list of html,pdf,text (default all three; PDF only where reportlab is present)

When to use it. A comma list of html, pdf and text (default all three). The HTML is self-contained - screenshots are embedded - so one file can be shared as the whole workflow; PDF is written where reportlab is present.

A screenshot to attach (repeatable); PATH or PATH::caption

When to use it. A screenshot to attach, repeatable, as PATH or PATH::caption. Each is embedded in the HTML so the report is one shareable file; a path that cannot be read is noted in the report as not-found, never dropped silently.

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.

When to use it. Pick what to do: `ingest` adds a case's properties to the lab store, `lookup` finds which cases carry a value, `correlate` shows what a case shares with others, `forget` removes a case, `export`/`import` move the store, `stats` summarises it.

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 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.

Use the classic Tkinter wizard

When to use it. Fall back to the classic interface on a machine where the modern window will not start, typically an old or minimal Windows install.

When to use it. Read the how-to guides for this product: list them, print one as plain text, open the bundled page or PDF, or copy one out to a folder. Each guide says plainly where this product stops.

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

When to use it. Point at a raw device when you need to inspect a structure on a live disk or partition directly, without imaging it first.

An image file to inspect instead

When to use it. Point at an image file to inspect instead of a live device - the usual choice once a drive has been imaged.

Byte offset to read from (default 0)

When to use it. Give the exact byte offset of the structure you want to look at (a partition start, a specific MFT record, a GPT entry). Read the offset off find_partitions/browse first rather than guessing.

Bytes to read (default: the template's own size, or 512)

When to use it. Override the number of bytes read when a template's own size is not what you need - a non-standard MFT record size, for example. Left out, each template reads its own documented size.

Structure template to overlay on the hex (default: auto-detect the filesystem at --offset)

When to use it. Leave it on auto to have the engine identify the filesystem at --offset and pick the right structure; name one explicitly (e.g. ntfs-mft, gpt-entry) when you are navigating to something the auto-detector cannot locate on its own, like one MFT record or one GPT partition-table entry.

Hex dump only, no field overlay

When to use it. Show plain hex+ASCII with no field overlay, for a region no template covers or when you want to eyeball the bytes yourself.

Machine-readable JSON output

When to use it. Emit machine-readable JSON instead of a printed table, for scripting or for a report generator to consume.

RAID member images, in array order (use '-' for a missing one) - switches this command to RAID inspection: --raid-parity or --raid-translate

When to use it. Give the RAID member images, in array order, to switch this command into RAID inspection mode (--raid-parity or --raid-translate) instead of decoding a single structure. Use a dash for a member that is missing.

With --members: compute/verify RAID5/6 parity for one stripe row (--row)

When to use it. Check whether a stripe row's stored parity actually matches its data - the fastest way to find which row of a suspect array is wrong before trusting a rebuild.

Translate a logical RAID array offset to its member disk + physical offset (needs --members, or -n with --level/--chunk alone)

When to use it. Give a logical offset into the assembled array to find out which physical member disk and sector really holds it - useful when a member is failing and you need to know exactly what it is about to lose.

RAID level for --raid-parity/--raid-translate (0/1/4/5/6/1e/jbod, default 5)

When to use it. State the RAID level for --raid-parity/--raid-translate the same way you would for the raid command: 0/1/4/5/6/1e/jbod.

Stripe/chunk size in bytes (default 65536)

When to use it. State the stripe size for --raid-parity/--raid-translate. It must match the array's real geometry.

What it costs. A wrong chunk size makes the parity check or the translated address meaningless - it will not raise an error, it will silently point at the wrong bytes.

RAID5/6 parity layout (default left-symmetric)

When to use it. Change from the default only for a RAID5/6 array documented as using a different parity layout.

Stripe row for --raid-parity (default 0)

When to use it. Pick which stripe row --raid-parity checks. Sweep rows one at a time when hunting for exactly where an array went wrong.

Member count for --raid-translate when --members is not given

When to use it. Give the member count for --raid-translate when you are reasoning about the array's geometry without opening the actual member images.

When to use it. Add evidence to a case and process it through one pipeline with a live dashboard. `add` enqueues a source; `run` runs the stages; `status` prints the dashboard; `stop` halts at a stage boundary; `retry` re-queues a failed stage.

Show what has been acknowledged on this install

When to use it. Show what lawful-use acknowledgements have been made on this install. Useful when auditing a shared bench machine.

Forget remembered acknowledgements (history is kept)

When to use it. Clear the remembered acknowledgements when a machine changes hands or a new operator takes it over.

What it costs. The history is retained. Resetting does not erase the record of what was previously acknowledged.

When to use it. The same command as `licence` (US spelling): status, activate KEY, deactivate.

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.

When to use it. Analyse a memory image. `plugins` lists what can run and whether Volatility 3 is installed; `info` identifies the operating system; `run` runs one Volatility 3 plugin and prints its table; `finding` adds a row of a saved result to the case; `scan` is the in-house reader that needs no Volatility 3.

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.

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

When to use it. Recover directly from the attached drive when it is healthy, the job is not evidential, and time matters.

What it costs. If the drive is failing, image it first. A direct scan reads the whole surface and can be the read that finishes a dying drive.

Disk image file (.dd/.img/.iso)

When to use it. The default choice for anything evidential, anything failing, and anything where the original must be returned untouched.

An iOS (iTunes/Finder) backup folder (Manifest.db)

When to use it. Point at an iTunes or Finder backup folder when the handset itself is unavailable, locked, or must not be touched.

Storage Spaces slab-map JSON: reassemble a pool virtual disk from member images and recover from it

When to use it. Reassemble a Storage Spaces virtual disk from member images and recover from the assembled volume.

Output directory for recovered files (required unless --list)

When to use it. Always a separate drive from the source. The product refuses a destination on the drive being read.

smart=metadata+carving (default), fs=named files only, carve=signatures only

When to use it. Leave at smart. It parses the file system for original names and folders AND carves free space for what the metadata no longer covers. Use fs when you want named files quickly from an intact file system; use carve on formatted or badly damaged media where the metadata is gone.

What it costs. fs alone misses everything the file system no longer indexes. carve alone returns files without their original names or folders. smart is what maximises the result.

Carry on from where an earlier scan of the same source into the same output folder stopped, instead of starting again from the beginning

When to use it. Continue a scan that was stopped, on the same source into the same output folder. A large drive is an overnight job and does not need to be restarted.

What it costs. The checkpoint belongs to the DRIVE, not the path. A different disk in the same slot restarts from the beginning, with the reason stated.

Also recover currently-existing (non-deleted) files

When to use it. Add whenever the loss is a volume rather than a deletion: a reformatted disk, a RAW volume, a failed array. In those cases the files were never deleted and the default deleted-only view will look almost empty.

What it costs. It substantially increases the output size, because it recovers everything present as well as everything deleted.

Print the drive's folder tree from its index (live and deleted files) and stop. Fast; nothing is written. -o is not needed.

When to use it. Look before you scan. Reads the filesystem index only and prints the folder tree - live and deleted files, deleted ones marked - in seconds, writing nothing. Use it first on any drive whose index is intact: it tells you whether the folder the customer wants is still named, so you can recover that alone with --only instead of reading the whole drive.

What it costs. Free, and needs no licence. What it cannot show is anything whose index entry is gone - a formatted card, a wiped table - which still needs the full scan.

Recover only this folder or file (repeatable). Paths are the volume's own, e.g. --only /Users/jo/Documents/ --only /Photos/IMG_0042.jpg. Implies --mode fs and --include-intact.

When to use it. Recover one folder or file rather than everything: the customer wants the Documents folder, not four hours and a terabyte of working folder. Repeat the switch for several paths; a folder path takes everything under it, and 1:/Folder/ names the folder on partition 1 only. Paths are the volume's own, as --list prints them.

What it costs. Implies --mode fs and --include-intact. Every content check, the manifest and the organising run exactly as in a full scan; a use is still charged for the drive.

native=built-in (default), photorec=use TestDisk's PhotoRec, auto=PhotoRec if installed

When to use it. Leave at native. Select photorec only to cross-check a result with a second implementation, which is occasionally useful in a disputed matter.

What it costs. The external engine must be installed separately and does not carry this product's validation or its verdicts.

Carving processes: 0=auto/all cores (default, byte-identical output, ~3x faster), 1=single-threaded, N=that many

When to use it. Leave at 0 so the carve uses the available cores. Set 1 when you need the machine responsive for other work, or when reproducing a result exactly for a report.

What it costs. Output is byte-identical either way; only the time changes. Below about 128 MB the product stays single-threaded because process start-up costs more than it saves.

Bytes per sector (default 512)

When to use it. Change from 512 only for 4K-native drives, where the wrong value prevents the volume being recognised.

Unlock an encrypted drive. A BitLocker 48-digit recovery password, a LUKS passphrase, or a key in hexadecimal.

When to use it. Supply the BitLocker recovery password, LUKS passphrase or hex key for an encrypted volume.

What it costs. Without the correct credential the volume cannot be read by anyone. The product states that rather than returning fragments. The credential is not retained for a later resume.

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 when you have read the pre-flight objection and established that it is wrong for your situation.

What it costs. The two objections it can override are both serious: too little room means the scan stops part way, and writing onto the drive being recovered overwrites the data you are trying to get back.

Generate a recovery report after scanning (comma-separated: pdf,docx,html; default all)

When to use it. Generate the report at the end of the scan whenever the result goes to somebody else: a client, an insurer, or a case file.

Override the mode for this run (forensic=hash+manifest+evidence, recovery=fast+by-type). Defaults to the saved global mode.

When to use it. Override the saved mode for this one run, for example a single evidential job on a bench normally used for commercial recovery.

What it costs. Setting it per run avoids the more common error, which is leaving a bench in forensic mode and hashing every file on high-volume commercial work.

List the APFS snapshots on the source (point-in-time views that may hold deleted/overwritten files) and stop

When to use it. Run first on any Mac volume. Snapshots are point-in-time views that often still hold the file as it was before it was deleted or overwritten.

Recover files as they were in this named APFS snapshot (byte-exact from the copy-on-write extents)

When to use it. Recover from the named snapshot. Where the file exists in a snapshot, this returns it byte-exact and is far better than carving for it.

List the Windows Volume Shadow Copies on the source (previous versions - originals from before deletion or ransomware) and stop

When to use it. Run first on any Windows volume, and always in a ransomware incident. Shadow copies hold previous versions from before the deletion or the encryption.

Recover files as they were in this shadow copy: the snapshot-time volume is reconstructed and scanned

When to use it. Reconstruct the volume as it was at that snapshot and recover from it. This is frequently the fastest complete recovery available.

When to use it. Parse a rosbag2 .db3 or MCAP .mcap robot black-box, salvage deleted messages from a damaged .db3 store, or write a report/manifest. Every subcommand is documented on its own line.

The image or file to analyse

When to use it. The image or file to examine for hidden data, run whenever an exhibit might carry a concealed payload - a picture that is larger than its content explains, a file a suspect treated as important, or anything flagged for a second look. Reading only; the exhibit is never changed.

Also carve out and save any hidden data that is found

When to use it. Add this when the examination should also carve out and save what it finds, so recovered appended data, embedded files and LSB payloads land in a folder you can open, not only in the on-screen result.

What it costs. It writes new files to the output folder; it never alters the exhibit, and an unconfirmed carve is labelled so it is not mistaken for proven.

Folder to write recovered hidden data into (with --extract)

When to use it. Where the recovered hidden data is written when extraction is on, used when the default folder beside the exhibit is not where the case keeps its working files. Choose a case folder, never the exhibit's own media.

Print the full report as JSON instead of as text

When to use it. Print the full report as JSON instead of text, used when another tool or a case script consumes the result rather than a person reading it.

The .tar / .cpio archive to read (ustar, GNU, pax, or cpio newc/odc/old-binary - auto-detected)

When to use it. Point at the .tar/.cpio archive - ustar, GNU, pax or cpio newc/odc/old-binary, detected automatically from the header.

Where to extract to (omit to just list)

When to use it. Give an output folder to extract into. Leave it out to only list the archive's contents first.

List the archive's contents; don't extract

When to use it. List what the archive holds before deciding what to extract, especially on a tape dump nobody has an index for.

Extract only this file or folder (repeatable; a folder is named with a trailing /)

When to use it. Extract one named file or folder (a trailing / means the whole folder) instead of the whole archive. Repeat it for more than one.

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 why the pre-flight objected and confirming it does not apply here, for example a free-space estimate that is wrong for a network share.

What it costs. The pre-flight exists to stop a job that cannot finish. Forcing past a genuine space objection can leave a half-extracted archive.

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.

When to use it. Organize a TeslaCam/Sentry export, read a GoPro/Insta360 video's GPS telemetry, read the documented CarPlay/Android Auto phone-side files, ingest a Berla iVe CSV export, or write a report/manifest. Every subcommand is documented on its own line. This product does not acquire vehicle hardware - it parses media and exports something else already produced.

When to use it. Open an artefact in a structured viewer without leaving the case: `registry` browses a hive, `plist` shows a property list, `sqlite` browses a database and its deleted rows, `hex` pages raw bytes, `interpret` decodes the bytes at an offset, `bookmark` marks bytes on the case. Every view prints JSON.

Workflow id (e.g. data_recovery); omit to list them

When to use it. Print the guided steps for a workflow. Useful for a new operator, or for a procedure your team runs rarely enough to want the sequence in front of them.

List the available guided workflows

When to use it. List the guided workflows available in this product.