forensic-log-tracker 1.0.0__tar.gz

forensic_log_tracker-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ahzek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forensic_log_tracker-1.0.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: forensic-log-tracker
+Version: 1.0.0
+Summary: CLI tool for documenting, hashing, and signing forensic investigations
+Author-email: Niklas Heringer <ping@niklas-heringer.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mev0lent/forensic-log-tracker
+Keywords: forensics,dfir,cli,digital-forensics,chain-of-custody
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.8
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: Jinja2>=3.1.6
+Requires-Dist: MarkupSafe>=3.0.2
+Requires-Dist: markdown-it-py>=3.0.0
+Requires-Dist: mdurl>=0.1.2
+Requires-Dist: PyYAML>=6.0.2
+Requires-Dist: rich>=14.0.0
+Requires-Dist: shellingham>=1.5.4
+Requires-Dist: typer>=0.15.2
+Requires-Dist: typing_extensions>=4.13.2
+Requires-Dist: tzdata>=2025.2
+Requires-Dist: Pygments>=2.19.1
+Requires-Dist: path>=17.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# Forensic Log Tracker
+
+A modular CLI tool for digital forensic professionals and students. Designed to execute, document, and cryptographically sign forensic commands during investigations — producing structured, auditable evidence records.
+
+---
+
+## What it does
+
+When you run a command through `flt`, it:
+
+- Executes the command via the system shell (bash or PowerShell)
+- Logs the output, truncated to a configurable preview
+- Attaches a formal legal explanation for the command (German, from `explanations.yaml`)
+- Hashes the output with SHA256 for integrity verification
+- Optionally signs the log file with your GPG key
+- Organizes everything under a named case folder
+
+All evidence is written as plain Markdown `.log` files alongside a `.meta.json` sidecar. Reports are generated as a single `case_report.md` per case.
+
+---
+
+## Requirements
+
+- Python 3.9+
+- GPG (GNU Privacy Guard)
+- Linux (tested on Kali) or Windows
+
+---
+
+## Installation
+
+### Linux
+
+```bash
+git clone https://github.com/mev0lent/forensic-log-tracker.git
+cd forensic-log-tracker
+chmod +x setup.sh
+./setup.sh
+source ~/.bashrc   # or ~/.zshrc
+```
+
+The setup script:
+- Creates a virtual environment at `forensic-log-venv/`
+- Installs all dependencies from `pyproject.toml`
+- Registers the `flt` alias in your shell profile
+- Prompts you to generate a GPG key if none exists
+
+After setup, activate the environment before use:
+
+```bash
+source forensic-log-venv/bin/activate
+```
+
+### Windows
+
+```powershell
+git clone https://github.com/mev0lent/forensic-log-tracker.git
+cd forensic-log-tracker
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+.\setup.ps1
+. $PROFILE
+.\forensic-log-venv\Scripts\Activate.ps1
+```
+
+### Alternative (requirements.txt)
+
+```bash
+python3 -m venv alt-env
+source alt-env/bin/activate
+pip install -r requirements.txt
+```
+
+---
+
+## Configuration
+
+Edit `config/config.yaml` before first use:
+
+```yaml
+project:
+  analyst: "Your Name"
+  timezone: "Europe/Berlin"   # Any IANA timezone string
+
+output:
+  preview_lines: 20           # Lines shown in log preview
+  hash_algorithm: "sha256"
+  comment_type: "Comment"     # "Comment" or "Callout" (Obsidian-style)
+
+gpg:
+  enabled: true
+  auto_verify: true
+  default_key: ""             # Optional: GPG key fingerprint
+
+logging:
+  level: INFO                 # DEBUG, INFO, WARNING, ERROR, CRITICAL
+```
+
+To add or extend tool explanations, edit `config/explanations.yaml`. Each entry maps a command (and optional flags) to a formal explanation used in log output and reports.
+
+---
+
+## Usage
+
+### Create a case
+
+```bash
+flt new-case case001 --description "Investigating suspicious USB device"
+```
+
+Creates `logs/case001/` and writes a `description.txt`.
+
+---
+
+### Run a forensic command
+
+```bash
+flt run "strings /bin/ls" --case case001
+```
+
+Produces:
+- `logs/case001/<timestamp>_command.log` — Markdown log with output preview, explanation, and hash
+- `logs/case001/<timestamp>_command.meta.json` — structured metadata (command, hash, timestamp)
+- `logs/case001/<timestamp>_command.log.sig` — GPG detached signature (if enabled)
+
+---
+
+### Dry-run mode
+
+```bash
+flt run "fdisk -l /dev/sdb" --case case001 --dry-run
+```
+
+Logs the command with its explanation and timestamp but does not execute it. Useful for documenting intended actions before touching evidence.
+
+---
+
+### Add a comment
+
+```bash
+flt comment --case case001 --text "Drive was write-protected before imaging."
+```
+
+Creates a `_comment.log` file with the analyst name and timestamp. Signed with GPG if enabled.
+
+---
+
+### List all cases
+
+```bash
+flt list-cases
+```
+
+---
+
+### View case description
+
+```bash
+flt case-info --case case001
+```
+
+---
+
+### Analyze a case
+
+```bash
+flt analyze --case case001
+```
+
+Lists all log files and signatures present in the case folder.
+
+---
+
+### Generate a report
+
+```bash
+flt report --case case001
+```
+
+Writes `logs/case001/case001_report.md` containing:
+- Case description
+- Chronological timeline of all commands and comments
+- Output excerpts, SHA256 hashes, legal context, and GPG signature status per entry
+
+To skip GPG verification during report generation:
+
+```bash
+flt report --case case001 --no-verify
+```
+
+---
+
+### Verify output hashes
+
+```bash
+flt verify-output --case case001
+```
+
+Recomputes the SHA256 hash of each log's output block and compares it against the stored value. Reports OK or Mismatch per file.
+
+---
+
+### Verify a signature manually
+
+```bash
+gpg --verify logs/case001/<logfile>.log.sig
+```
+
+---
+
+## Testing
+
+Tests run inside Docker to ensure a clean, isolated environment.
+
+```bash
+# Build and run tests separately
+make build
+make test
+
+# Build and run in one step
+make run_test
+
+# Remove leftover Docker images
+make clean
+```
+
+---
+
+## File structure
+
+```
+forensic-log-tracker/
+├── core/               # Execution, logging, hashing, signing, legal explanations
+├── utils/              # Config loading, path resolution, reporting, comments
+├── config/
+│   ├── config.yaml     # Runtime configuration
+│   └── explanations.yaml  # Tool explanation database
+├── templates/          # Jinja2 template for legal explanation rendering
+├── forensic_log_tracker/
+│   └── cli.py          # CLI entry point
+├── test/               # pytest test suite
+├── setup.sh            # Linux setup script
+├── setup.ps1           # Windows setup script
+└── Makefile            # Docker test targets
+```
+
+Logs are written to `logs/<case-id>/` and are excluded from version control by default.
+
+---
+
+## .gitignore
+
+Make sure your `.gitignore` includes the following to avoid committing evidence or keys:
+
+```
+logs/
+*.sig
+*.log
+*.meta.json
+forensic-log-venv/
+__pycache__/
+```
+
+---
+
+## License
+
+MIT — free to use, modify, and extend.

forensic_log_tracker-1.0.0/README.md

@@ -0,0 +1,267 @@
+# Forensic Log Tracker
+
+A modular CLI tool for digital forensic professionals and students. Designed to execute, document, and cryptographically sign forensic commands during investigations — producing structured, auditable evidence records.
+
+---
+
+## What it does
+
+When you run a command through `flt`, it:
+
+- Executes the command via the system shell (bash or PowerShell)
+- Logs the output, truncated to a configurable preview
+- Attaches a formal legal explanation for the command (German, from `explanations.yaml`)
+- Hashes the output with SHA256 for integrity verification
+- Optionally signs the log file with your GPG key
+- Organizes everything under a named case folder
+
+All evidence is written as plain Markdown `.log` files alongside a `.meta.json` sidecar. Reports are generated as a single `case_report.md` per case.
+
+---
+
+## Requirements
+
+- Python 3.9+
+- GPG (GNU Privacy Guard)
+- Linux (tested on Kali) or Windows
+
+---
+
+## Installation
+
+### Linux
+
+```bash
+git clone https://github.com/mev0lent/forensic-log-tracker.git
+cd forensic-log-tracker
+chmod +x setup.sh
+./setup.sh
+source ~/.bashrc   # or ~/.zshrc
+```
+
+The setup script:
+- Creates a virtual environment at `forensic-log-venv/`
+- Installs all dependencies from `pyproject.toml`
+- Registers the `flt` alias in your shell profile
+- Prompts you to generate a GPG key if none exists
+
+After setup, activate the environment before use:
+
+```bash
+source forensic-log-venv/bin/activate
+```
+
+### Windows
+
+```powershell
+git clone https://github.com/mev0lent/forensic-log-tracker.git
+cd forensic-log-tracker
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+.\setup.ps1
+. $PROFILE
+.\forensic-log-venv\Scripts\Activate.ps1
+```
+
+### Alternative (requirements.txt)
+
+```bash
+python3 -m venv alt-env
+source alt-env/bin/activate
+pip install -r requirements.txt
+```
+
+---
+
+## Configuration
+
+Edit `config/config.yaml` before first use:
+
+```yaml
+project:
+  analyst: "Your Name"
+  timezone: "Europe/Berlin"   # Any IANA timezone string
+
+output:
+  preview_lines: 20           # Lines shown in log preview
+  hash_algorithm: "sha256"
+  comment_type: "Comment"     # "Comment" or "Callout" (Obsidian-style)
+
+gpg:
+  enabled: true
+  auto_verify: true
+  default_key: ""             # Optional: GPG key fingerprint
+
+logging:
+  level: INFO                 # DEBUG, INFO, WARNING, ERROR, CRITICAL
+```
+
+To add or extend tool explanations, edit `config/explanations.yaml`. Each entry maps a command (and optional flags) to a formal explanation used in log output and reports.
+
+---
+
+## Usage
+
+### Create a case
+
+```bash
+flt new-case case001 --description "Investigating suspicious USB device"
+```
+
+Creates `logs/case001/` and writes a `description.txt`.
+
+---
+
+### Run a forensic command
+
+```bash
+flt run "strings /bin/ls" --case case001
+```
+
+Produces:
+- `logs/case001/<timestamp>_command.log` — Markdown log with output preview, explanation, and hash
+- `logs/case001/<timestamp>_command.meta.json` — structured metadata (command, hash, timestamp)
+- `logs/case001/<timestamp>_command.log.sig` — GPG detached signature (if enabled)
+
+---
+
+### Dry-run mode
+
+```bash
+flt run "fdisk -l /dev/sdb" --case case001 --dry-run
+```
+
+Logs the command with its explanation and timestamp but does not execute it. Useful for documenting intended actions before touching evidence.
+
+---
+
+### Add a comment
+
+```bash
+flt comment --case case001 --text "Drive was write-protected before imaging."
+```
+
+Creates a `_comment.log` file with the analyst name and timestamp. Signed with GPG if enabled.
+
+---
+
+### List all cases
+
+```bash
+flt list-cases
+```
+
+---
+
+### View case description
+
+```bash
+flt case-info --case case001
+```
+
+---
+
+### Analyze a case
+
+```bash
+flt analyze --case case001
+```
+
+Lists all log files and signatures present in the case folder.
+
+---
+
+### Generate a report
+
+```bash
+flt report --case case001
+```
+
+Writes `logs/case001/case001_report.md` containing:
+- Case description
+- Chronological timeline of all commands and comments
+- Output excerpts, SHA256 hashes, legal context, and GPG signature status per entry
+
+To skip GPG verification during report generation:
+
+```bash
+flt report --case case001 --no-verify
+```
+
+---
+
+### Verify output hashes
+
+```bash
+flt verify-output --case case001
+```
+
+Recomputes the SHA256 hash of each log's output block and compares it against the stored value. Reports OK or Mismatch per file.
+
+---
+
+### Verify a signature manually
+
+```bash
+gpg --verify logs/case001/<logfile>.log.sig
+```
+
+---
+
+## Testing
+
+Tests run inside Docker to ensure a clean, isolated environment.
+
+```bash
+# Build and run tests separately
+make build
+make test
+
+# Build and run in one step
+make run_test
+
+# Remove leftover Docker images
+make clean
+```
+
+---
+
+## File structure
+
+```
+forensic-log-tracker/
+├── core/               # Execution, logging, hashing, signing, legal explanations
+├── utils/              # Config loading, path resolution, reporting, comments
+├── config/
+│   ├── config.yaml     # Runtime configuration
+│   └── explanations.yaml  # Tool explanation database
+├── templates/          # Jinja2 template for legal explanation rendering
+├── forensic_log_tracker/
+│   └── cli.py          # CLI entry point
+├── test/               # pytest test suite
+├── setup.sh            # Linux setup script
+├── setup.ps1           # Windows setup script
+└── Makefile            # Docker test targets
+```
+
+Logs are written to `logs/<case-id>/` and are excluded from version control by default.
+
+---
+
+## .gitignore
+
+Make sure your `.gitignore` includes the following to avoid committing evidence or keys:
+
+```
+logs/
+*.sig
+*.log
+*.meta.json
+forensic-log-venv/
+__pycache__/
+```
+
+---
+
+## License
+
+MIT — free to use, modify, and extend.

forensic_log_tracker-1.0.0/core/case_manager.py

@@ -0,0 +1,11 @@
+from utils.pathing import get_case_log_path
+from utils.log import logger
+
+def create_case_folder(case: str, description: str):
+    base_path = get_case_log_path(case, create=True)
+    base_path.mkdir(parents=True, exist_ok=True)
+    desc_file = base_path / "description.txt"
+
+    with desc_file.open("w", encoding="utf-8") as f:
+        f.write(f"Case-ID: {case}\nDescription: {description}\n")
+    logger.info(f"New case created: {base_path}")

forensic_log_tracker-1.0.0/core/executor.py

@@ -0,0 +1,49 @@
+import subprocess
+import platform
+from datetime import datetime
+from pathlib import Path
+from core.hasher import compute_hash
+from core.logger import write_log
+from core.legalizer import get_legal_explanation
+from utils.log import logger
+from utils.shared_config import load_config
+from utils.pathing import get_case_log_path
+
+config = load_config()
+
+
+def execute_command(cmd: str, case: str, dry_run: bool = False):
+    timestamp = datetime.now(config["TIMEZONE"]).isoformat()
+    case_dir = get_case_log_path(case, create=False)
+
+    logger.info(f"Executing command: {cmd}")
+
+    if dry_run:
+        output = "[!] DRY RUN: Command not executed."
+    else:
+        try:
+            if platform.system() == "Windows":
+                result = subprocess.run(
+                    ["powershell", "-Command", cmd],
+                    capture_output=True,
+                    text=True,
+                    check=True
+                )
+            else:
+                result = subprocess.run(
+                    ["bash", "-c", cmd],
+                    capture_output=True,
+                    text=True,
+                    check=True
+                )
+            output = f"[STDOUT]\n{result.stdout}\n[STDERR]\n{result.stderr}"
+        except subprocess.CalledProcessError as e:
+            output = f"[!] Command failed:\n{e.stderr}"
+
+    explanation = get_legal_explanation(" ".join(cmd.split()[:4]))
+    preview_lines = config.get("output", {}).get("preview_lines", 20)
+    hash_algo = config.get("output", {}).get("hash_algorithm", "sha256")
+    output_hash = compute_hash(output, hash_algo)
+
+    logfile = write_log(case_dir, cmd, output, explanation, timestamp, preview_lines, dry_run, output_hash)
+    return logfile, output

forensic_log_tracker-1.0.0/core/gpg_signer.py

@@ -0,0 +1,17 @@
+import subprocess
+from pathlib import Path
+from utils.log import logger
+
+
+def sign_file(log_path: Path) -> bool:
+    sig_path = log_path.with_suffix(log_path.suffix + ".sig")
+    try:
+        subprocess.run(
+            ["gpg", "--batch", "--yes", "--output", str(sig_path), "--detach-sign", str(log_path)],
+            check=True
+        )
+        logger.info(f"Signed logfile: {sig_path.name}")
+        return True
+    except subprocess.CalledProcessError:
+        logger.warning("GPG signature failed – is a key configured?")
+        return False

forensic_log_tracker-1.0.0/core/hasher.py

@@ -0,0 +1,16 @@
+# core/hasher.py# core/hasher.py
+import hashlib
+
+
+def compute_hash(data: str, algorithm: str = "sha256") -> str:
+    """
+    Compute a hash for the given string using the specified algorithm.
+
+    Supported: sha256, md5, sha1, sha512, etc.
+    """
+    try:
+        hasher = hashlib.new(algorithm)
+        hasher.update(data.encode("utf-8"))
+        return hasher.hexdigest()
+    except ValueError as e:
+        raise ValueError(f"[!] Unsupported hashing algorithm: {algorithm}") from e