Skip to main content

Getting Started

Learn the basic principles of indexing a filesystem with exhume_indexer.

exhume_indexer turns a supported filesystem into a structured SQLite database. It is useful when you want to browse, query, enrich, or process file metadata after Exhume has detected a filesystem in a disk image, mounted folder, or logical partition.

The indexer is designed to sit after the acquisition, body parsing, partition discovery, and filesystem detection steps. It creates the database tables used to store evidences, partitions, filesystem records, file signatures, known artefact matches, and parsed artefact objects.

🛠️ Prerequisites​

Installing Rust​

The Exhume Toolkit is built with Rust and requires it for development or compilation.

curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

Installing​

The following command installs Exhume Indexer globally:

cargo install exhume_indexer

Installing from source​

Clone the Exhume repository and build the indexer member:

git clone https://github.com/forensicxlab/exhume
cd exhume/members/exhume_indexer
cargo build --release

🚀 Basic Usage​

exhume_indexer supports two main targets:

  • A folder that should be indexed as a filesystem-like source.
  • A filesystem partition inside a disk image or body, addressed by byte offset and size.

The CLI creates or updates an SQLite database. If --database is omitted, the database is created next to the source using the default name <body>.sqlite.

Usage: exhume_indexer [OPTIONS] --body <body>

Options:
  -b, --body <body>                  The path to the disk image, body, or folder to index.
  -d, --database <database>          The SQLite database path used for the index.
  -f, --format <format>              The body format, either 'raw', 'ewf', or 'auto'.
  -o, --offset <offset>              Partition start offset in bytes, decimal or hexadecimal.
  -s, --size <size>                  Partition size in sectors, decimal or hexadecimal.
      --evidence-id <evidence_id>    Evidence identifier stored in the SQLite index.
      --partition-id <partition_id>  Existing partition identifier to reuse.
      --fvek <fvek>                  BitLocker Full Volume Encryption Key, encoded as hex.
      --identify-files               Run the file-signature identification pass after indexing.
      --extract-artefacts            Identify configured artefacts and run artefact parsers after indexing.
      --artifacts-yaml <path>        Optional path to a custom artifacts.yaml file.
      --no-progress                  Disable interactive progress bars.
  -l, --log-level <log_level>        Set the log verbosity level.
  -h, --help                         Print help.
  -V, --version                      Print version.

Example​

exhume_indexer -b linux.E01 -o 0x100000 -s 0x9c00000  --identify-files --extract-artefacts
2026-05-03T19:17:26.872602Z  INFO exhume_body: Detected an EWF disk image.                                                  2026-05-03T19:17:27.114903Z  INFO exhume_body: Detected an EWF disk image.
2026-05-03T19:17:27.122347Z  INFO exhume_extfs::superblock: Extended FileSystem Journaling feature is on.
2026-05-03T19:17:27.122369Z  INFO exhume_filesystem::detected_fs: Detected an Extended filesystem.
2026-05-03T19:17:27.122374Z  INFO exhume_indexer: Starting filesystem indexation…
⠐ Discovering files… 103450 found so far.
⠐ [00:01:36] [========================================] 461607/461607 Indexed 461607/461607 items…

Indexing Workflow​

A typical indexing workflow is:

  1. Identify the partition layout with exhume_partitions.
  2. Select the filesystem partition to index.
  3. Pass the partition offset and size to exhume_indexer.
  4. Store the result in an SQLite database.
  5. Optionally enrich the index with file signature identification.
  6. Optionally identify and extract configured artefacts.

Database Content​

The generated SQLite database contains normalized tables for:

  • evidence: the indexed source.
  • partitions: the indexed partition or folder scope.
  • system_files: filesystem records and metadata.
  • known_artefacts: artefact matches identified from the embedded or custom catalog.
  • parsed_artefacts: objects emitted by artefact parsers.

The database can be queried directly with SQLite tools or consumed by higher-level Exhume and Thanatology components.

Progress Display​

When run in an interactive terminal, the CLI displays progress bars for long-running operations. When output is redirected, or when --no-progress is used, the indexer falls back to plain progress messages.

Unknown-length phases such as filesystem discovery are displayed as a spinner. Known-length phases such as ingestion, file signature identification, and artefact extraction are displayed with a determinate progress bar.

Artefact Catalog​

exhume_indexer embeds a default artifacts.yaml catalog. You can provide a custom catalog with --artifacts-yaml when you need to adjust known paths, add internal artefact definitions, or test new parser mappings.

The catalog is used by --extract-artefacts to first identify matching files in the index and then run compatible parsers from exhume_artefacts.