HMAC File Integrity Checker (python, written by Claude Code)

Claude Code wrote this python project from the task below. It installed and ran on a clean Ubuntu 22.04 machine as written.

Task given to the agent:

TASK: HMAC File Integrity Checker

Write a program that computes and verifies HMAC-based integrity checksums for files and directories, creating a manifest of checksums that can later be used to detect unauthorized modifications.

FUNCTIONAL REQUIREMENTS:
- Accept a file or directory path, a secret key, and a mode (generate or verify) as command-line arguments
- Support multiple hash algorithms selectable via --algorithm flag: SHA-256 (default), SHA-384, SHA-512, SHA3-256
- generate mode: Compute HMAC for each file and save a manifest file containing file paths, HMAC values, file sizes, and timestamps
- verify mode: Read the manifest, recompute HMACs, and report which files are unchanged, modified, added (present but not in manifest), or missing (in manifest but deleted)
- For directories, recursively process all files and support --exclude flag with glob patterns to skip files (e.g., --exclude "*.log,*.tmp")
- Support a --output flag for the manifest file path (default: integrity_manifest.json)
- Print a colored summary to console showing verification results: passed files in green, modified in red, missing in yellow, new files in blue
- Compute a master HMAC over the entire manifest to detect tampering of the manifest file itself
- Support incremental updates: when generating with an existing manifest, only recompute HMACs for files whose modification time has changed via --incremental flag
- If no arguments are given, generate sample files in a temporary directory, create an integrity manifest, modify one file, delete another, add a new file, then run verification to demonstrate all detection capabilities
- Handle binary and text files correctly, permission errors gracefully

Create a complete Python project for a clean Ubuntu 22.04 machine with only Python 3.10+ installed. Include:
- Source code
- requirements.txt with all dependencies (direct and transitive) pinned to exact versions
- README.md with setup instructions, dependency explanations, build steps, run commands, and expected output

[]

#!/usr/bin/env python3
"""HMAC File Integrity Checker using hmac + hashlib (stdlib).

Compute and verify HMAC-SHA256 checksums for files and directories.
Manifest file stores path + HMAC pairs. Supports recursive directory scanning.
"""

import argparse
import hmac
import hashlib
import json
import os
import sys


def compute_hmac(file_path: str, key: bytes) -> str:
    """Compute HMAC-SHA256 for a single file."""
    h = hmac.new(key, digestmod=hashlib.sha256)
    with open(file_path, "rb") as f:
        while True:
            chunk = f.read(8192)
            if not chunk:
                break
            h.update(chunk)
    return h.hexdigest()


def scan_files(target: str) -> list:
    """Get list of files from a file path or directory (recursive)."""
    if os.path.isfile(target):
        return [target]
    elif os.path.isdir(target):
        files = []
        for root, dirs, filenames in os.walk(target):
            for fname in sorted(filenames):
                full_path = os.path.join(root, fname)
                files.append(full_path)
        return sorted(files)
    else:
        print(f"Error: {target} is not a file or directory.")
        sys.exit(1)


def compute_manifest(target: str, key: str, manifest_path: str) -> None:
    """Compute HMAC-SHA256 for all files and write manifest."""
    key_bytes = key.encode("utf-8")
    files = scan_files(target)
    manifest = {}

    for file_path in files:
        # Normalize paths using forward slashes
        rel_path = os.path.relpath(file_path).replace("\\", "/")
        mac = compute_hmac(file_path, key_bytes)
        manifest[rel_path] = mac
        print(f"  {mac}  {rel_path}")

    with open(manifest_path, "w") as f:
        json.dump(manifest, f, indent=2)

    print(f"\nManifest written to {manifest_path} ({len(manifest)} files)")


def verify_manifest(manifest_path: str, key: str) -> bool:
    """Verify files against a manifest."""
    key_bytes = key.encode("utf-8")

    with open(manifest_path, "r") as f:
        manifest = json.load(f)

    passed = 0
    failed = 0
    missing = 0

    for file_path, expected_hmac in manifest.items():
        if not os.path.exists(file_path):
            print(f"  MISSING  {file_path}")
            missing += 1
            continue

        actual_hmac = compute_hmac(file_path, key_bytes)
        if hmac.compare_digest(actual_hmac, expected_hmac):
            print(f"  OK       {file_path}")
            passed += 1
        else:
            print(f"  FAILED   {file_path}")
            failed += 1

    print(f"\nResults: {passed} OK, {failed} FAILED, {missing} MISSING")
    return failed == 0 and missing == 0


def demo() -> None:
    """Run a demonstration with sample files."""
    print("=== HMAC File Integrity Checker Demo ===\n")

    demo_dir = "demo_files"
    manifest_path = "demo_manifest.json"
    secret_key = "my-secret-key-for-demo"

    # Create sample files
    os.makedirs(demo_dir, exist_ok=True)
    for i in range(1, 4):
        with open(os.path.join(demo_dir, f"file{i}.txt"), "w") as f:
            f.write(f"This is sample file {i} for HMAC integrity checking.\n")
    print(f"1. Created sample files in {demo_dir}/\n")

    # Compute manifest
    print("2. Computing HMAC-SHA256 manifest...")
    compute_manifest(demo_dir, secret_key, manifest_path)

    # Verify
    print("\n3. Verifying manifest...")
    verify_manifest(manifest_path, secret_key)

    # Tamper
    print("\n4. Tampering with a file...")
    with open(os.path.join(demo_dir, "file2.txt"), "w") as f:
        f.write("This file has been tampered with!\n")
    verify_manifest(manifest_path, secret_key)

    # Cleanup
    import shutil
    shutil.rmtree(demo_dir, ignore_errors=True)
    if os.path.exists(manifest_path):
        os.remove(manifest_path)
    print("\n5. Cleaned up demo files.")


def main() -> None:
    parser = argparse.ArgumentParser(description="HMAC File Integrity Checker")
    subparsers = parser.add_subparsers(dest="command")

    cp = subparsers.add_parser("compute", help="Compute HMAC manifest")
    cp.add_argument("target", help="File or directory to process")
    cp.add_argument("--key", required=True, help="HMAC secret key")
    cp.add_argument("--manifest", default="manifest.json", help="Manifest output path")

    vf = subparsers.add_parser("verify", help="Verify files against manifest")
    vf.add_argument("--manifest", default="manifest.json", help="Manifest file path")
    vf.add_argument("--key", required=True, help="HMAC secret key")

    args = parser.parse_args()

    if args.command is None:
        demo()
        return

    if args.command == "compute":
        compute_manifest(args.target, args.key, args.manifest)
    elif args.command == "verify":
        success = verify_manifest(args.manifest, args.key)
        sys.exit(0 if success else 1)


if __name__ == "__main__":
    main()

# HMAC File Integrity Checker (Python - hmac+hashlib stdlib)

Compute and verify HMAC-SHA256 checksums for files and directories.

## Usage

```bash
# Compute HMAC manifest for a directory
python checker.py compute ./mydir --key mysecret

# Verify against manifest
python checker.py verify --manifest manifest.json --key mysecret

# Run demo
python checker.py
```

## Dependencies

- Python 3.7+ (no external dependencies, uses stdlib hmac+hashlib)

# No external dependencies - uses Python stdlib (hmac, hashlib)