Whether you’re working on a university project, responding to cybercrime, or investigating a suspicious device in a corporate setting, clean and consistent logging isn’t optional; it’s essential.

In digital forensics, every step must be traceable. If you can’t prove what you did, when, and why, even solid evidence can be dismissed.

This post introduces a command-line tool that helps you do just that:
forensic-log-tracker, a lightweight, modular logging system for forensic work.

It helps you:

• Log shell commands and outputs
• Attach legal explanations (especially useful in academic or judicial contexts)
• Digitally sign logs using GPG
• Structure your investigation by cases
• Generate Markdown reports for handover or archiving

Let’s walk through what the tool does and how to use it with a practical example.

Example Scenario: Investigating a Suspicious USB Stick

Imagine you’re handed a USB stick found on the desk of a fraud suspect. You’ve booted into a forensics workstation and mounted the device read-only. Now it’s time to analyze the contents and document every step properly.

This walkthrough will show you how to do that with forensic-log-tracker.

Setup (The Easy Way)

Start with

virtualenv -p python3 log-tracker-env
source log-tracker-env/bin/activate

to activate your virtual environment for clean dependency management.

You only need to do this once:

git clone https://github.com/mev0lent/forensic-log-tracker.git
cd forensic-log-tracker
chmod +x setup.sh
./setup.sh

The script will:

• Set up your Python environment
• Install all dependencies
• Configure your repo path centrally
• Add a flt command you can use from anywhere
• Optionally help you generate a GPG key

Afterwards, restart your terminal or run:

source ~/.bashrc    # or ~/.zshrc

You're now ready to use flt to document everything you do, cryptographically signed.

Your configuration options

Open and edit config/config.yaml:

project:
  analyst: "Your name"
  timezone: "UTC"

execution:
  default_output_lines: 20
  dry_run_label: "[!] DRY RUN: Command not executed."

output:
  language: "de"              # "en", "de" – for future translation of explanations
  format: "md"                # "md", "html", "pdf"
  preview_lines: 20
  include_sha256: true
  hash_algorithm: "sha256"

gpg:
  enabled: true
  auto_verify: true
  default_key: ""             # optional: GPG fingerprint

logging:
  level: INFO                 # DEBUG, INFO, WARNING, ERROR, CRITICAL

You can also edit config/explanations.yaml to define legal or contextual explanations for each command - written in formal explanatory style by default, as used in legal documentation.

Step-by-Step: Using the Tool in an Investigation

1. Create a New Case

flt new-case case001 --description "Investigating suspicious USB stick"

This initializes a structured directory for all logs, reports, and signatures.

2. Run a Command

Let’s say we want to examine printable strings from a binary on the USB stick:

flt run "strings /mnt/usb/some_file" --case case001

This:

• Logs the command and its timestamp
• Captures a preview of the output
• Includes a legal explanation if configured
• Hashes the output (SHA256)
• Signs the log with your GPG key
• Creates both .log (the log itself) and .log.sig (it's digital signature) files

3. Simulate a Command (Dry Run)

Sometimes you need to document what you would do, without actually running the command.

flt run "fdisk -l /dev/sdb" --case case001 --dry-run

This logs the intended command, timestamp, and explanation but skips execution. Useful for evidence-preserving workflows.

4. Analyze the Case

flt analyze --case case001

Quick overview of what’s been done, which commands were run, and how the logs look.

5. View Case data

flt case-info --case case001

Shows description, log count, and last-modified times: handy during longer investigations.

6. Generate a Report

flt report --case case001

This creates: logs/case001/case001_report.md, a clean summary that includes:

• All commands used
• Timestamps
• Output excerpts
• SHA256 hash values
• GPG signature verification status
• Legal command explanations (if configured)

7. Verify Output Integrity

flt verify-output --case case001

This re-hashes each output and compares it to what’s recorded. Any tampering or corruption will show up.

Why GPG Signatures - what are they here for?

GPG adds a cryptographic layer of trust:

• You can prove logs weren’t altered
• Others can verify signatures independently - each .log has a matching .sig file
• You can use gpg --verify manually too:

gpg --verify logs/case001/strings_usb.log.sig

Tip: Using flt in Your Workflow

Once you're set up, consider integrating flt into your daily forensics flow:

• Create a case at the start of each new device or investigation scope
• Log everything you do, even exploratory steps or dry runs
• Use flt report regularly to generate a running timeline of actions
• Use flt verify-output before handover or submission to ensure everything still checks out

This turns your terminal into an evidence-grade tracking system, one that’s cryptographically signed, reproducible, and readable.

For example, instead of keeping loose notes:

flt run "grep suspicious /mnt/usb/dump.txt" --case usb001

...gives you a timestamped, signed log with full traceability.

Final Thoughts

forensic-log-tracker can't replace your analysis tools, it complements them.

It focuses on how you document your actions, and that’s what separates ad-hoc notes from reproducible, trustworthy forensic work.

Clean logs aren’t just a formality, they’re how you prove what you did, when, and why.

📎 Explore the Project

GitHub: mev0lent/forensic-log-tracker

Contributions are welcome, whether it’s adding more legal explanations, improving reporting styles, or building a GUI layer. It's open source for a reason.