auditor

auditor is a forensic tool for fast integrity auditing that uses cryptographic hash functions .

It is similar to other popular tools (fsum, hashdeep, sha256sum, etc.), but with features to make digital data auditing simpler and faster.

auditor has support to several hash algorithms. The default is sha256, that is recommended by NIST since 2015 ( see NIST Policy on Hash Functions).

By default, thash method is enabled, but this mode can be disabled.

Manuals

Some manuals available in:

How to use

With auditor installed in your system, you can use it as follows:

auditor subcommands: info
hash
check
info
usage
Important !

hash is the first step of forensic auditing. It generates audit files that allow verifying file integrity.

Basic usage of subcommand hash

auditor hash input_path

This will:

  1. Hash files in input_path with default algorithm (sha256)
  2. Generate audit files:
    • Audit_FullList: contains the integrity data (hash, size, name) of files in input_path. Default name: _auditor_hashes.txt
    • Audit_Stamp: contains only the integrity data of Audit_FullList. Default name: _auditor_stamp.txt.This is the file that needs to be printed or digitally signed to ensure check of all integrity chain.
  3. Show integrity data of Audit_FullList


    4. After hash, you can perform check command to verify integrity. To properly ensure integrity check in the future, follow advices in Important!



Others examples:

  1. Just generate hashes, but don’t create any files (-l)

    auditor hash input_path -l

  2. Overwrite audit files (-o), without using thash method (-d): 

    auditor hash input_path -o -d

  3. Overwrite audit files (-o), using a fast-disk (-z) with default algorithm (useful with SSD disks, to be fast): 

    auditor hash input_path -o -z

  4. Overwrite audit files (-o), include only txt files (-i "**/*.txt") only in root folder (-u 1) 

    auditor hash input_path -o -i "**/*.txt" -u 1

  5. Overwrite audit files (-o), include all files, except txt files (-e "**/*.txt") 

    auditor hash input_path -o -e "**/*.txt"

  6. Overwrite audit files (-o), include only files with name "file1.doc" (-i "**/*/file1.doc") and "file2.xls" (-i "**/*/file2.xls") 

    auditor hash input_path -o -i "**/*/file1.doc"  -i "**/*/file2.xls"

  7. Overwrite audit files (-o), include all txt files (-i "**/*/*.txt"), except that inside dir named folder1 (-e "**/*/folder1/*") 

    auditor hash input_path -z -o -a blake3 -i "**/*/*.txt" -e "**/*/folder1/*"

  8. Overwrite audit files (-o), use fast-disk (-z) and algorithm 'blake3' (very fast): 

    auditor hash input_path -o -z -a blake3

  9. Overwrite audit files (-o), use blockSize 10MB and 'whirlpool' hash function 

    auditor hash input_path -o -b 10MB -a whirlpool

See Manual section to all options!


check is the second step of forensic auditing. It checks the the integrity of data using information in the audit files and can be used after hash was performed.

Basic usage of subcommand Check

auditor check input_path

This will:

  1. Use integrity data listed in Audit_Stamp and check against Audit_FullList.
  2. Use integrity data listed in Audit_FullList and check against original files in input_path.
  3. Show the recalculated integrity data of Audit_FullList.

Others examples:

  1. Check in quiet mode (-q) and stop on first error (-x), using default audit files. 

    auditor check input_path -q -x

  2. Check F:\data_path using audit files with specific names. (-f to <Audit_FullList> and -s to <Audit_Stamp>) 

    auditor check F:\data_path -f C:\other_path\personal_fullList.txt -s C:\other_path\personal_stamp.txt -q -x

  3. Check integrity of just one file in <input_path> against some audit file 

    auditor check F:\data_path\file1.txt -f C:\other_path\some_audit.txt -q -x

Note: The auditor check is compatible with fsum format.

See Manual section to all options!



info does not perform hash integrity check. It only tests the audit files and the content of input_path and shows useful information. Can be used after hash was performed.

Example of Forensic Info

auditor info input_path

This will:

  1. Verify if audit files Audit_Stamp and Audit_FullList exists.
  2. Verify if files listed in Audit_Stamp and Audit_FullList exists and listed size is the same that in input_path.
  3. Verify if all files in input_path are listed in Audit_FullList.
  4. Recalculate integrity data of Audit_FullList and check against audit file Audit_Stamp
  5. Give a report of size of the files and of all input_path.


Manual português

Usage

Usage: auditor.exe <SUBCOMMAND> [OPTIONS]

To see version: auditor.exe --version or auditor.exe -V

To help: auditor.exe --help or auditor.exe -h

SUBCOMMAND:

One of the following subcommands:

Subcommand hash

Hash <input_path> and generates audit files (<Audit_FullList>/<Audit_Stamp>)

Usage: auditor.exe hash <INPUT_PATH> [OPTIONS]

Arguments:

Options:

Subcommand check

Checks the integrity of <input_path> against data in audit files (<Audit_FullList>/<Audit_Stamp>)

Usage: auditor.exe check <INPUT_PATH> [OPTIONS]

Arguments:

Options:

Note: The auditor check is compatible with fsum format.

Subcommand info

Only tests if audit files and <input_path> are synchronized. This doesn't check the integrity!

Usage: auditor.exe info [OPTIONS] <INPUT_PATH>

Arguments:

Options:

About the integrity of data

To securely ensure future check of all chain of integrity, you should:

  1. Save all data, including audit files, and either print the contents of Audit_Stamp or digitally sign this file. If you don´t do this, someone can simply change the data an generate new audit files.
  2. In future, when someone performs a check, the content of audit file Audit_Stamp MUST BE the same of the printed or digitally signed version done in step 1. If does not match, the integrity check is not valid.

If you don't have a digital certificate, you can use a free timestamping authority to sign the file online, such as freetsa.org (using Online Signature).

Output Formats

The format of audit files are simple. Each line contains:

hash_value ?ALGORITHM[<THASH-BlockSize>]|file_size[:hex]*relative_filepath
where [ ] are optional:

hash_value: value of hash.

ALGORITHM[<THASH-BlockSize>]: ALGORITHM used to hash, stored in capital letters to mantain compatibility with some others tools. The parameter with <THASH-BlockSize> is optional, indicating that thash method and BlockSize were used. BlockSize must be in KB, MB, GB or TB. Ex: 10MB.

file_size: FileSize of original file when was hashed. Useful in check, to improve speed when size doesnt match. Why hash a big file when already is known that its size does not match with original?

[:hex]: Optional flag to indicate that filepaths is in hex format. This is necessary because char as '\n', '\r' or '\0', are permitted in some OS, and the hex avoid problems with formatting the results.

relative_filepath: The relative filepath of file hashed.

Example 1: using method thash with algorithm sha256 and BlockSize 50MB : 

281d5d93464f1165ea7c403ca99d63ff4bf9a360864f8df4bd0e8e6c03774e98 ?SHA256<THASH-50MB>|500000*file_hashed.bin

Example 2: using normal method, just with algorithm blake3. 

7357b67824d086dc53f5e1ded565f500456bea1812783f1fbcddc08fddc3944c ?BLAKE3|2233:hex*1aCb344356e4e2b2b6

Others formats can be implemented in future.

Download

Download and sha256 of binary application:

v.0.4.5- Windows x64

sha256 :d1d02861fe584bf35900f5bef96f92873f3a0350a73113331331623835111d0d

download

v.0.4.5- Linux x64

sha256:9f78aa4086ae24754cb564742feb6d7a698515860cb730a03851a283f95cdd7d

download

Disclaimer: This version of auditor is provided as development-stage software, with NO warranty or support of any kind, and is free for non-commercial use only. Use it at your own risk.


License: This version of auditor is licensed for non-commercial use only. Please review the full license terms for details.

Benchmarks

Using hyperfine, tests between auditor, fsum and hashdeep64 were performed and results are shown below.

Machine configs: 
S.O.: Windows 11 Home 64bits
Processor: AMD Ryzen 7 (7800X3D 4.20 GHz)
RAM: 64 GB of RAM (Corsair Vengeance DDR5 64GB - 5200MHz)
Disk: SSD M.2 2TB (Corsair MP600 Pro NVMe)

Data Source:
Benchmarks
Benchmarks using Data Source: Benchmarks
Have suggestions or found a bug? Contact us at: [email protected]