@modular-intelligence/forensic-analysis 1.0.0

package/README.md

@@ -0,0 +1,1336 @@
+# Forensic Analysis MCP Server
+
+A Model Context Protocol (MCP) server for file forensics and static analysis. Perform deep inspection of files including hashing, binary string extraction, entropy analysis, PE/ELF header parsing, metadata extraction, and comprehensive forensic investigation capabilities.
+
+## Overview
+
+This MCP server provides ten specialized tools for analyzing files without executing them. Whether you're investigating suspicious binaries, analyzing malware samples, performing general file forensics, or building forensic investigation reports, this server enables Claude to perform comprehensive static analysis using industry-standard techniques.
+
+**Key capabilities:**
+- Calculate cryptographic hashes (MD5, SHA1, SHA256) on individual files and entire directories
+- Extract printable strings with pattern recognition (URLs, IPs, suspicious APIs)
+- Identify file types via magic bytes
+- Calculate Shannon entropy to detect packing/encryption
+- Parse Windows PE (Portable Executable) headers with section analysis
+- Parse Linux ELF headers with readelf
+- Extract metadata from images, documents, and media files
+- Recursively hash directories and detect duplicate files
+- Correlate file timestamps with log entries for timeline analysis
+- Generate structured forensic investigation reports with findings and indicators
+
+## Tools
+
+### Tool Reference
+
+| Tool | Purpose | Input | Output |
+|------|---------|-------|--------|
+| `file_hash` | Calculate MD5, SHA1, SHA256 hashes | File path | Three hash values + file size |
+| `file_strings` | Extract strings with pattern highlighting | File path, min length, encoding | Strings + categorized interesting patterns |
+| `file_identify` | Identify file type via magic bytes | File path | Type, MIME type, hex magic bytes |
+| `file_entropy` | Calculate Shannon entropy | File path | Entropy value + rating (very_low to extremely_high) |
+| `pe_header` | Parse Windows PE headers | File path | Machine type, sections, imports, packing detection |
+| `elf_header` | Parse Linux ELF headers | File path | Architecture, sections, entry point |
+| `exif_metadata` | Extract file metadata | File path | Key-value metadata dictionary |
+| `hash_directory` | Recursively hash files in directory | Directory path, algorithm, pattern | File hashes + duplicate detection |
+| `file_correlate` | Correlate file timestamps with log entries | Directory path, log file, time window | Timeline correlations between files and logs |
+| `forensic_report` | Generate structured forensic report | Case ID, title, findings, evidence | Professional report with aggregated findings |
+
+---
+
+## Tool Details
+
+### file_hash
+
+Calculate cryptographic hashes for file integrity verification and malware database lookups.
+
+**Input Schema:**
+```json
+{
+  "file": "/path/to/file"
+}
+```
+
+**Example Output:**
+```json
+{
+  "file": "/Users/ehenry/Documents/sample.exe",
+  "size": 45056,
+  "md5": "d41d8cd98f00b204e9800998ecf8427e",
+  "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
+  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+}
+```
+
+**Use cases:**
+- Check files against VirusTotal or other malware databases
+- Verify file integrity across different systems
+- Create hash-based file inventories
+
+---
+
+### file_strings
+
+Extract ASCII and wide-character strings from binaries with automatic pattern recognition for suspicious indicators.
+
+**Input Schema:**
+```json
+{
+  "file": "/path/to/file",
+  "min_length": 6,
+  "encoding": "both",
+  "max_results": 500
+}
+```
+
+**Parameters:**
+- `min_length`: Minimum string length (3-100, default: 6)
+- `encoding`: "ascii", "wide" (Unicode), or "both" (default: "both")
+- `max_results`: Maximum strings to return (default: 500)
+
+**Interesting Pattern Categories:**
+- `url` — HTTP/HTTPS URLs
+- `ip_address` — IPv4 addresses
+- `email` — Email addresses
+- `unc_path` — UNC network paths (\\server\share)
+- `windows_path` — Windows file paths (C:\...)
+- `registry_key` — Windows registry keys (HKEY_...)
+- `sensitive_keyword` — "password", "secret", "apikey", etc.
+- `shell_reference` — Shell commands (cmd.exe, powershell, bash)
+- `suspicious_api` — Win32 APIs (CreateProcess, VirtualAlloc, LoadLibrary, etc.)
+- `crypto_reference` — Cryptography keywords (encrypt, decrypt, cipher)
+
+**Example Output:**
+```json
+{
+  "file": "/Users/ehenry/Documents/sample.exe",
+  "total_strings": 1247,
+  "strings": [
+    "This program cannot be run in DOS mode",
+    "kernel32.dll",
+    "advapi32.dll",
+    "user32.dll",
+    "LoadLibraryA",
+    "GetProcAddress"
+  ],
+  "interesting": [
+    {
+      "value": "http://malware.example.com/beacon",
+      "category": "url"
+    },
+    {
+      "value": "CreateProcessA",
+      "category": "suspicious_api"
+    },
+    {
+      "value": "192.168.1.100",
+      "category": "ip_address"
+    },
+    {
+      "value": "VirtualAlloc WriteProcessMemory CreateRemoteThread",
+      "category": "suspicious_api"
+    },
+    {
+      "value": "password=",
+      "category": "sensitive_keyword"
+    }
+  ]
+}
+```
+
+**Use cases:**
+- Quickly identify command & control domains
+- Detect suspicious API usage patterns
+- Find hardcoded credentials or configuration
+- Analyze code reuse and similarities
+
+---
+
+### file_identify
+
+Identify file type using magic bytes (file command) for verification of claimed file types.
+
+**Input Schema:**
+```json
+{
+  "file": "/path/to/file"
+}
+```
+
+**Example Output:**
+```json
+{
+  "file": "/Users/ehenry/Documents/sample.exe",
+  "type": "PE32 executable (console) Intel 80386, for MS Windows",
+  "mime_type": "application/x-msdownload",
+  "magic_bytes": "4d 5a 90 00 03 00 00 00 04 00 00 00 ff ff 00 00"
+}
+```
+
+**Magic Bytes Reference:**
+- `4d 5a` — PE/DOS executable (MZ header)
+- `7f 45 4c 46` — ELF (Linux/Unix binary)
+- `89 50 4e 47` — PNG image
+- `ff d8 ff` — JPEG image
+- `50 4b 03 04` — ZIP archive
+
+**Use cases:**
+- Verify file type hasn't been disguised with wrong extension
+- Detect polyglot files that are multiple formats simultaneously
+- Identify obfuscated or renamed files
+
+---
+
+### file_entropy
+
+Calculate Shannon entropy to detect compression, encryption, or packing.
+
+**Input Schema:**
+```json
+{
+  "file": "/path/to/file"
+}
+```
+
+**Example Output:**
+```json
+{
+  "file": "/Users/ehenry/Documents/sample.exe",
+  "overall_entropy": 6.847,
+  "entropy_rating": "very_high (likely compressed/encrypted)",
+  "size": 45056,
+  "max_possible_entropy": 8,
+  "entropy_percentage": 85.59
+}
+```
+
+**Entropy Rating Scale:**
+
+| Entropy Range | Rating | Meaning |
+|---|---|---|
+| < 1.0 | very_low | Empty or uniform data (suspicious padding) |
+| 1.0 - 3.0 | low | Structured data, plain text, source code |
+| 3.0 - 5.0 | medium | Mixed content, normal executables |
+| 5.0 - 7.0 | high | Compressed or encoded sections |
+| 7.0 - 7.5 | very_high | Likely compressed/encrypted |
+| > 7.5 | extremely_high | Almost certainly encrypted or random data |
+
+**Interpretation:**
+- **Legitimate binaries:** Typically 4.0 - 6.5 (mix of code, strings, data)
+- **Packed malware:** Often 7.0+ (entire payload compressed/encrypted)
+- **Encrypted data:** Approaches 8.0 (maximum randomness)
+
+**Use cases:**
+- Detect code packing/obfuscation
+- Identify encryption without cryptanalysis
+- Spot unusual data patterns
+- Compare sections of a binary (high entropy .text section = suspicious)
+
+---
+
+### pe_header
+
+Parse Windows PE (Portable Executable) headers for comprehensive binary analysis. Pure TypeScript parsing, no external tools required.
+
+**Input Schema:**
+```json
+{
+  "file": "/path/to/file"
+}
+```
+
+**Example Output:**
+```json
+{
+  "file": "/Users/ehenry/Documents/malware.exe",
+  "is_64bit": true,
+  "machine": "AMD64",
+  "timestamp": "2023-06-15T10:23:45.000Z",
+  "characteristics": [
+    "EXECUTABLE_IMAGE",
+    "LARGE_ADDRESS_AWARE"
+  ],
+  "sections": [
+    {
+      "name": ".text",
+      "virtual_size": 204800,
+      "raw_size": 205312,
+      "entropy": 6.234,
+      "characteristics": [
+        "CODE",
+        "EXECUTE",
+        "READ"
+      ]
+    },
+    {
+      "name": ".data",
+      "virtual_size": 4096,
+      "raw_size": 4096,
+      "entropy": 3.456,
+      "characteristics": [
+        "INITIALIZED_DATA",
+        "READ",
+        "WRITE"
+      ]
+    },
+    {
+      "name": ".rsrc",
+      "virtual_size": 8192,
+      "raw_size": 8192,
+      "entropy": 2.123,
+      "characteristics": [
+        "INITIALIZED_DATA",
+        "READ"
+      ]
+    }
+  ],
+  "imports": [
+    {
+      "dll": "kernel32.dll",
+      "functions": []
+    },
+    {
+      "dll": "user32.dll",
+      "functions": []
+    },
+    {
+      "dll": "advapi32.dll",
+      "functions": []
+    }
+  ],
+  "is_packed": true,
+  "packing_indicators": "High entropy sections: .text, .reloc; RWX sections: .overlay"
+}
+```
+
+**Key Fields:**
+
+- **machine:** i386, AMD64, ARM, ARM64
+- **timestamp:** Compilation date (UTC)
+- **characteristics:** EXECUTABLE_IMAGE, DLL, 32BIT_MACHINE, LARGE_ADDRESS_AWARE
+- **sections:** Code, data, resources, debug info
+  - **entropy:** Section-level entropy (high entropy = packed)
+  - **characteristics:** CODE, INITIALIZED_DATA, EXECUTE, READ, WRITE
+- **is_packed:** Detected based on high entropy sections or RWX permissions
+- **packing_indicators:** Specific detection reasons
+
+**Packing Detection Heuristics:**
+- Section entropy > 7.0 (indicates compression/encryption)
+- Read+Write+Execute permissions on same section (unusual for legitimate code)
+- Size mismatches between virtual and raw sizes
+
+**Common Packed Binary Indicators:**
+```
+.text entropy: 7.2+ (should be 4.5-6.5)
+.reloc entropy: 7.5+ (normally 3.0-5.0)
+RWX section present (normal code is RX only)
+Timestamp: 1970-01-01 (modified to hide compilation time)
+```
+
+**Use cases:**
+- Detect code packing and obfuscation
+- Identify imported APIs (often reveals malware family)
+- Analyze binary compilation metadata
+- Check for suspicious section permissions
+- Verify DLL dependencies
+
+---
+
+### elf_header
+
+Parse Linux/Unix ELF (Executable and Linkable Format) headers using readelf.
+
+**Input Schema:**
+```json
+{
+  "file": "/path/to/file"
+}
+```
+
+**Example Output:**
+```json
+{
+  "file": "/usr/bin/ls",
+  "class": "ELF64",
+  "data": "2's complement, little endian",
+  "type": "EXEC (Executable file)",
+  "machine": "Advanced Micro Devices X86-64",
+  "entry_point": "0x401000",
+  "section_count": 27,
+  "sections": [
+    {
+      "name": ".text",
+      "type": "PROGBITS",
+      "size": 184652,
+      "flags": "AX"
+    },
+    {
+      "name": ".rodata",
+      "type": "PROGBITS",
+      "size": 98304,
+      "flags": "A"
+    },
+    {
+      "name": ".data",
+      "type": "PROGBITS",
+      "size": 8192,
+      "flags": "WA"
+    },
+    {
+      "name": ".bss",
+      "type": "NOBITS",
+      "size": 4096,
+      "flags": "WA"
+    }
+  ]
+}
+```
+
+**Key Fields:**
+
+- **class:** ELF32, ELF64
+- **data:** Endianness (little/big endian)
+- **type:** EXEC (executable), DYN (shared object), REL (relocatable)
+- **machine:** x86, x86-64, ARM, ARM64, MIPS, PPC, etc.
+- **entry_point:** Memory address where execution begins
+- **sections:** Program sections (.text, .data, .bss, .rodata, etc.)
+  - **flags:** A (allocate), W (write), X (execute)
+
+**Section Types:**
+- `PROGBITS` — Program data in file
+- `NOBITS` — Space but no file data (like .bss)
+- `SYMTAB` — Symbol table
+- `STRTAB` — String table
+- `RELA` — Relocation entries
+- `DYNAMIC` — Dynamic linking info
+
+**Use cases:**
+- Analyze Linux/Unix binaries
+- Check architecture and entry points
+- Identify stripped vs. unstripped binaries
+- Verify PIE (Position Independent Executable) support
+- Detect hardening features
+
+---
+
+### exif_metadata
+
+Extract metadata from image files, documents, and media using exiftool.
+
+**Input Schema:**
+```json
+{
+  "file": "/path/to/image.jpg"
+}
+```
+
+**Example Output:**
+```json
+{
+  "file": "/Users/ehenry/Documents/photo.jpg",
+  "field_count": 34,
+  "metadata": {
+    "FileName": "photo.jpg",
+    "FileSize": "2048 kB",
+    "FileType": "JPEG",
+    "MIMEType": "image/jpeg",
+    "ExifImageWidth": "4032",
+    "ExifImageHeight": "3024",
+    "Make": "Apple",
+    "Model": "iPhone 14 Pro",
+    "DateTime": "2023:06:15 14:23:45",
+    "LensModel": "iPhone 14 Pro main camera 6.86mm f/1.78",
+    "GPSLatitude": "37 deg 46' 54.32\" N",
+    "GPSLongitude": "122 deg 24' 13.70\" W",
+    "GPSAltitude": "12.3 m Above Sea Level",
+    "Copyright": "2023 John Doe",
+    "ImageDescription": "Vacation photo"
+  }
+}
+```
+
+**Common Metadata Fields:**
+- **Image:** Width, height, bit depth, color space
+- **Camera:** Make, model, lens, aperture, shutter speed, ISO
+- **Location:** GPS coordinates, altitude
+- **Timestamps:** Original, modified, digitized
+- **Copyright:** Creator, copyright notice, usage rights
+- **Software:** Creator application, version
+
+**Privacy Note:** EXIF data can reveal:
+- Camera location (GPS coordinates)
+- Device used (phone model)
+- Creation timestamp
+- Copyright/author information
+- Camera settings and behavior patterns
+
+**Use cases:**
+- Extract geolocation data from images
+- Identify device/software used
+- Discover copyright and authorship info
+- Detect privacy leaks in shared images
+- Verify timestamp authenticity
+
+---
+
+### hash_directory
+
+Recursively hash all files in a directory with duplicate file detection.
+
+**Input Schema:**
+```typescript
+{
+  directory_path: string              // Path to directory to hash
+  algorithm: "md5" | "sha1" | "sha256" // Hash algorithm (default: sha256)
+  recursive: boolean                  // Hash subdirectories (default: true)
+  max_files: number                   // Maximum files to process (default: 1000)
+  include_pattern?: string            // Only include files matching pattern (e.g., '*.exe')
+}
+```
+
+**Example Request:**
+```json
+{
+  "directory_path": "/Users/ehenry/Downloads",
+  "algorithm": "sha256",
+  "recursive": true,
+  "max_files": 1000,
+  "include_pattern": "*.exe"
+}
+```
+
+**Example Output:**
+```json
+{
+  "directory": "/Users/ehenry/Downloads",
+  "algorithm": "sha256",
+  "total_files": 42,
+  "total_errors": 2,
+  "duplicates_found": 3,
+  "files": [
+    {
+      "path": "/Users/ehenry/Downloads/installer.exe",
+      "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f",
+      "size": 524288,
+      "modified": "2024-01-15T10:23:45.000Z"
+    },
+    {
+      "path": "/Users/ehenry/Downloads/setup.exe",
+      "hash": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g",
+      "size": 1048576,
+      "modified": "2024-01-14T15:30:20.000Z"
+    }
+  ],
+  "duplicates": [
+    {
+      "hash": "c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h",
+      "files": [
+        "/Users/ehenry/Downloads/report_v1.pdf",
+        "/Users/ehenry/Downloads/report_v1_copy.pdf",
+        "/Users/ehenry/Downloads/Archive/report_old.pdf"
+      ]
+    }
+  ],
+  "errors": [
+    {
+      "path": "/Users/ehenry/Downloads/large_file.iso",
+      "error": "File too large (>100MB), skipped"
+    }
+  ]
+}
+```
+
+**Use cases:**
+- Find duplicate files in a directory tree
+- Verify integrity of archived files
+- Detect suspicious files disguised with different names
+- Create forensic inventories of file systems
+- Identify potential data exfiltration artifacts
+
+---
+
+### file_correlate
+
+Correlate file modification timestamps with log entries within a specified time window for timeline analysis.
+
+**Input Schema:**
+```typescript
+{
+  directory_path: string                // Path to directory containing files
+  log_file: string                      // Path to log file to correlate
+  time_window_minutes: number           // Time window in minutes (default: 60)
+  max_files: number                     // Maximum files to analyze (default: 500)
+}
+```
+
+**Example Request:**
+```json
+{
+  "directory_path": "/var/log/suspicious_dir",
+  "log_file": "/var/log/syslog",
+  "time_window_minutes": 30,
+  "max_files": 500
+}
+```
+
+**Example Output:**
+```json
+{
+  "directory": "/var/log/suspicious_dir",
+  "log_file": "/var/log/syslog",
+  "time_window_minutes": 30,
+  "total_files_analyzed": 15,
+  "total_log_entries": 2847,
+  "correlations_found": 8,
+  "correlations": [
+    {
+      "file": "/var/log/suspicious_dir/malware.exe",
+      "file_modified": "2024-01-15T14:23:45.000Z",
+      "related_log_entries": [
+        {
+          "line_number": 1245,
+          "timestamp": "2024-01-15T14:20:30.000Z",
+          "content": "Process execution detected: C:\\System32\\cmd.exe /c download malware.exe"
+        },
+        {
+          "line_number": 1246,
+          "timestamp": "2024-01-15T14:22:15.000Z",
+          "content": "File created: /var/log/suspicious_dir/malware.exe"
+        },
+        {
+          "line_number": 1247,
+          "timestamp": "2024-01-15T14:23:45.000Z",
+          "content": "Suspicious API call: CreateProcessA from unknown process"
+        }
+      ]
+    },
+    {
+      "file": "/var/log/suspicious_dir/config.ini",
+      "file_modified": "2024-01-15T14:45:20.000Z",
+      "related_log_entries": [
+        {
+          "line_number": 1312,
+          "timestamp": "2024-01-15T14:43:00.000Z",
+          "content": "Registry key modified: HKEY_LOCAL_MACHINE\\Software\\Microsoft\\Windows\\Run"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Supported Timestamp Formats:**
+- ISO 8601: `2024-01-15T14:23:45Z` or `2024-01-15 14:23:45`
+- Syslog: `Jan 15 14:23:45`
+
+**Use cases:**
+- Timeline analysis during incident response
+- Correlate file modifications with system events
+- Identify suspicious activity sequences
+- Establish causality between files and log entries
+- Support forensic investigation timelines
+
+---
+
+### forensic_report
+
+Generate a structured forensic investigation report with findings, evidence, indicators of compromise, and recommendations.
+
+**Input Schema:**
+```typescript
+{
+  case_id: string                           // Unique case or incident identifier
+  title: string                             // Report title
+  findings: Array<{
+    category: string                        // Category (e.g., 'malware', 'network', 'filesystem')
+    severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
+    description: string                     // Detailed finding description
+    evidence?: string[]                     // Evidence items (files, hashes, etc.)
+    tools_used?: string[]                   // Tools used to discover finding
+  }>
+  timeline?: Array<{
+    timestamp: string                       // ISO 8601 timestamp
+    event: string                           // Event description
+    source?: string                         // Source of the event
+  }>
+  affected_systems?: string[]               // List of affected systems/hosts
+  iocs?: Array<{
+    type: string                            // IOC type (ip, domain, hash, url, email)
+    value: string                           // IOC value
+    context?: string                        // Context/source of IOC
+  }>
+  recommendations?: string[]                // Recommended actions
+}
+```
+
+**Example Request:**
+```json
+{
+  "case_id": "INC-2024-0215",
+  "title": "Ransomware Incident Investigation Report",
+  "findings": [
+    {
+      "category": "malware",
+      "severity": "CRITICAL",
+      "description": "Detected known ransomware executable with high entropy and suspicious API calls",
+      "evidence": [
+        "/Users/shared/payload.exe",
+        "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f"
+      ],
+      "tools_used": ["file_identify", "pe_header", "file_strings"]
+    },
+    {
+      "category": "network",
+      "severity": "HIGH",
+      "description": "Suspicious outbound connections to known command and control server",
+      "evidence": [
+        "192.168.1.100",
+        "malware-c2.example.com"
+      ],
+      "tools_used": ["file_strings", "network_analysis"]
+    }
+  ],
+  "timeline": [
+    {
+      "timestamp": "2024-01-15T08:00:00Z",
+      "event": "Initial infection vector: phishing email with malicious attachment"
+    },
+    {
+      "timestamp": "2024-01-15T12:30:00Z",
+      "event": "Ransomware deployment and encryption process initiated"
+    },
+    {
+      "timestamp": "2024-01-15T14:00:00Z",
+      "event": "Ransom note displayed to user"
+    }
+  ],
+  "affected_systems": ["WORKSTATION-01", "FILESERVER-02", "LAPTOP-15"],
+  "iocs": [
+    {
+      "type": "hash",
+      "value": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f",
+      "context": "SHA256 of ransomware executable"
+    },
+    {
+      "type": "domain",
+      "value": "malware-c2.example.com",
+      "context": "Command and control domain"
+    },
+    {
+      "type": "ip",
+      "value": "192.0.2.100",
+      "context": "C2 server IP address"
+    },
+    {
+      "type": "email",
+      "value": "attacker@example.com",
+      "context": "Ransom contact email"
+    }
+  ],
+  "recommendations": [
+    "Isolate all affected systems from the network",
+    "Preserve forensic evidence before remediation",
+    "Reset credentials for all affected accounts",
+    "Update security monitoring and detection rules"
+  ]
+}
+```
+
+**Example Output:**
+```json
+{
+  "report_metadata": {
+    "case_id": "INC-2024-0215",
+    "title": "Ransomware Incident Investigation Report",
+    "generated_at": "2024-01-16T09:30:00.000Z",
+    "overall_risk_level": "CRITICAL"
+  },
+  "executive_summary": {
+    "total_findings": 2,
+    "severity_breakdown": {
+      "CRITICAL": 1,
+      "HIGH": 1,
+      "MEDIUM": 0,
+      "LOW": 0
+    },
+    "affected_systems_count": 3,
+    "ioc_count": 4
+  },
+  "findings": [
+    {
+      "id": "F-001",
+      "category": "malware",
+      "severity": "CRITICAL",
+      "description": "Detected known ransomware executable with high entropy and suspicious API calls",
+      "evidence": [
+        "/Users/shared/payload.exe",
+        "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f"
+      ],
+      "tools_used": ["file_identify", "pe_header", "file_strings"]
+    },
+    {
+      "id": "F-002",
+      "category": "network",
+      "severity": "HIGH",
+      "description": "Suspicious outbound connections to known command and control server",
+      "evidence": [
+        "192.168.1.100",
+        "malware-c2.example.com"
+      ],
+      "tools_used": ["file_strings", "network_analysis"]
+    }
+  ],
+  "timeline": [
+    {
+      "timestamp": "2024-01-15T08:00:00Z",
+      "event": "Initial infection vector: phishing email with malicious attachment"
+    },
+    {
+      "timestamp": "2024-01-15T12:30:00Z",
+      "event": "Ransomware deployment and encryption process initiated"
+    },
+    {
+      "timestamp": "2024-01-15T14:00:00Z",
+      "event": "Ransom note displayed to user"
+    }
+  ],
+  "affected_systems": ["WORKSTATION-01", "FILESERVER-02", "LAPTOP-15"],
+  "indicators_of_compromise": [
+    {
+      "type": "hash",
+      "value": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f",
+      "context": "SHA256 of ransomware executable"
+    },
+    {
+      "type": "domain",
+      "value": "malware-c2.example.com",
+      "context": "Command and control domain"
+    },
+    {
+      "type": "ip",
+      "value": "192.0.2.100",
+      "context": "C2 server IP address"
+    },
+    {
+      "type": "email",
+      "value": "attacker@example.com",
+      "context": "Ransom contact email"
+    }
+  ],
+  "recommendations": [
+    "Isolate affected systems from the network",
+    "Preserve forensic evidence before remediation",
+    "Reset credentials for compromised accounts",
+    "Apply patches for exploited vulnerabilities",
+    "Review and update security monitoring rules"
+  ]
+}
+```
+
+**Use cases:**
+- Generate professional incident response reports
+- Aggregate findings from multiple forensic tools
+- Document investigation timeline and evidence
+- Track indicators of compromise
+- Provide actionable recommendations to stakeholders
+- Support incident response procedures and compliance documentation
+
+---
+
+## Prerequisites
+
+### Required Tools
+
+The server uses standard Unix/Linux utilities that come pre-installed on most systems:
+
+- **strings** — Extract printable strings from binaries
+  - Built into all POSIX systems
+  - Already available on macOS, Linux, BSD
+
+- **file** — Identify file types via magic bytes
+  - Standard command on all Unix-like systems
+  - Installed by default on macOS and Linux
+
+- **readelf** — Parse ELF binary headers
+  - Standard on Linux systems
+  - On macOS: `brew install binutils` (provides readelf)
+  - On BSD: `pkg install binutils` or equivalent
+
+### Optional Tools
+
+- **exiftool** — Extract metadata from images/documents
+  - macOS: `brew install exiftool`
+  - Linux: `apt-get install libimage-exiftool-perl` or `yum install perl-Image-ExifTool`
+  - Download: https://exiftool.org/
+
+### PE Header Parsing
+
+PE header parsing is implemented in pure TypeScript with no external dependencies. The server automatically parses Windows executables without requiring any additional tools.
+
+### Verify Installation
+
+```bash
+# Check required tools
+which strings
+which file
+which readelf  # or brew install binutils
+
+# Optional: Check exiftool
+which exiftool  # or brew install exiftool
+```
+
+---
+
+## Installation
+
+### Prerequisites
+- Node.js 18+ or Bun 1.0+
+- Bun runtime (recommended for better performance)
+
+### Steps
+
+1. **Install Bun** (if not already installed):
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+2. **Clone or download this repository:**
+```bash
+cd /path/to/forensic-analysis
+```
+
+3. **Install dependencies:**
+```bash
+bun install
+```
+
+4. **Build the server:**
+```bash
+bun run build
+```
+
+This creates the compiled output in `dist/index.js`.
+
+### File Structure
+
+```
+forensic-analysis/
+├── src/
+│   ├── index.ts              # Server entry point
+│   ├── schemas.ts            # Input validation schemas
+│   ├── security.ts           # File path validation
+│   ├── types.ts              # TypeScript interfaces
+│   ├── cli-executor.ts       # External command execution
+│   └── tools/
+│       ├── file-hash.ts
+│       ├── file-strings.ts
+│       ├── file-identify.ts
+│       ├── file-entropy.ts
+│       ├── pe-header.ts
+│       ├── elf-header.ts
+│       ├── exif-metadata.ts
+│       ├── hash-directory.ts
+│       ├── file-correlate.ts
+│       └── forensic-report.ts
+├── dist/                      # Compiled output (generated)
+├── package.json
+└── README.md
+```
+
+---
+
+## Usage
+
+### Starting the Server
+
+The server communicates via stdio (standard input/output), making it compatible with Claude Desktop and other MCP clients.
+
+**Direct execution:**
+```bash
+bun run src/index.ts
+```
+
+**Via compiled build:**
+```bash
+bun dist/index.js
+```
+
+### Claude Desktop Integration
+
+Add the server to Claude Desktop's configuration:
+
+**File:** `~/.claude/claude.json` (or `%APPDATA%\Claude\claude.json` on Windows)
+
+```json
+{
+  "mcpServers": {
+    "forensic-analysis": {
+      "command": "bun",
+      "args": [
+        "run",
+        "/Users/ehenry/Documents/code/mcp-servers/forensic-analysis/src/index.ts"
+      ]
+    }
+  }
+}
+```
+
+Or with built version:
+```json
+{
+  "mcpServers": {
+    "forensic-analysis": {
+      "command": "bun",
+      "args": [
+        "/Users/ehenry/Documents/code/mcp-servers/forensic-analysis/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+### Claude Code (Cline) Integration
+
+Add to Claude Code settings JSON:
+
+```json
+{
+  "mcpServers": {
+    "forensic-analysis": {
+      "command": "bun",
+      "args": [
+        "run",
+        "/Users/ehenry/Documents/code/mcp-servers/forensic-analysis/src/index.ts"
+      ]
+    }
+  }
+}
+```
+
+### Programmatic Usage
+
+When connected to the MCP server, Claude can invoke tools like:
+
+```
+Analyze /path/to/binary.exe for packing indicators
+```
+
+This would trigger:
+1. `file_identify` to verify it's a PE file
+2. `file_entropy` to check for high entropy
+3. `pe_header` to analyze sections and detect packing
+
+---
+
+## Security
+
+### File Path Validation
+
+All file paths are validated before access:
+
+1. **Path normalization:** Resolves relative paths and symlinks
+2. **Absolute path requirement:** Converted to absolute paths
+3. **Blocked paths:** Access to sensitive system paths is denied:
+   - `/etc/shadow` — Password hashes
+   - `/proc` — Process information
+   - `/sys` — Kernel information
+   - `/dev` — Device files
+4. **Existence check:** File must exist
+5. **File type check:** Must be a regular file (not directory)
+6. **Size limit:** Files must be under 100 MB
+
+### Security Module
+
+```typescript
+// src/security.ts
+const BLOCKED_PATHS = ["/etc/shadow", "/proc", "/sys", "/dev"];
+const MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
+
+function validateFilePath(path: string): string {
+  // 1. Normalize and resolve to absolute path
+  const resolved = resolve(normalize(path));
+
+  // 2. Check against blocked paths
+  for (const blocked of BLOCKED_PATHS) {
+    if (resolved.startsWith(blocked)) {
+      throw new Error(`Access to ${blocked} is not allowed`);
+    }
+  }
+
+  // 3. Verify file exists
+  if (!existsSync(resolved)) {
+    throw new Error(`File does not exist: ${resolved}`);
+  }
+
+  // 4. Verify it's a regular file
+  const stat = statSync(resolved);
+  if (!stat.isFile()) {
+    throw new Error(`Path is not a file: ${resolved}`);
+  }
+
+  // 5. Check file size
+  if (stat.size > MAX_FILE_SIZE) {
+    throw new Error(`File too large (${(stat.size / 1024 / 1024).toFixed(1)}MB). Maximum: 100MB`);
+  }
+
+  return resolved;
+}
+```
+
+### External Command Execution
+
+External commands (strings, file, readelf, exiftool) are executed with:
+- **Timeout:** 30 seconds per command
+- **Buffer limit:** 10 MB max output
+- **No shell:** Commands executed directly without shell interpretation
+- **Argument validation:** Zod schemas validate all inputs
+
+### Best Practices
+
+- **Only analyze trusted files** — Never analyze files from untrusted sources without verification
+- **Use in isolated environment** — Consider running in a container or VM for suspicious files
+- **Monitor resource usage** — Large files (approaching 100 MB) may be slow to analyze
+- **Verify external tools** — Ensure strings, file, readelf are from official sources
+
+---
+
+## Examples
+
+### Analyze a Suspicious Binary
+
+```
+I found a suspicious executable at /Users/shared/unknown.exe.
+Can you analyze it for signs of malware?
+```
+
+Claude would:
+1. Run `file_identify` to confirm it's a PE executable
+2. Run `file_hash` to get hashes for VirusTotal lookup
+3. Run `file_entropy` to check for packing
+4. Run `pe_header` to analyze imports and detect packing
+5. Run `file_strings` to find URLs, APIs, and indicators
+
+---
+
+### Extract Metadata from Photo
+
+```
+I have a photo at /Users/ehenry/Documents/vacation.jpg
+that I want to share publicly. What metadata does it contain?
+```
+
+Claude would:
+1. Run `exif_metadata` to extract all metadata
+2. Report GPS coordinates, camera info, timestamps
+3. Recommend removing sensitive fields before sharing
+
+---
+
+### Compare Two Files
+
+```
+Are these two binaries the same?
+File A: /tmp/program_v1.exe
+File B: /tmp/program_v2.exe
+```
+
+Claude would:
+1. Run `file_hash` on both files
+2. Compare the SHA256 hashes
+3. If different, run `file_entropy` and `pe_header` on both
+4. Report differences in compilation time, sections, imports
+
+---
+
+### Detect Packing
+
+```
+This binary seems obfuscated. How can I tell if it's packed?
+```
+
+Claude would:
+1. Run `file_entropy` to check overall entropy
+2. Run `pe_header` to analyze section entropy
+3. Check for high-entropy sections (.text, .reloc)
+4. Check for RWX (read-write-execute) sections
+5. Report packing indicators with confidence
+
+---
+
+### Find Duplicate Files
+
+```
+Find all duplicate files in my Downloads directory
+```
+
+Claude would:
+1. Run `hash_directory` on `/Users/ehenry/Downloads`
+2. Report files with matching hashes
+3. Identify duplicate copies and suggest deletion candidates
+
+---
+
+### Timeline Analysis During Incident Response
+
+```
+Correlate files in /var/suspect_files with system logs to build a timeline
+```
+
+Claude would:
+1. Run `file_correlate` with the suspect directory and system log file
+2. Show which log entries correspond to file modifications
+3. Help establish sequence of events during the incident
+
+---
+
+### Generate Forensic Investigation Report
+
+```
+Create a comprehensive report for incident INC-2024-0215 with these findings:
+- Detected ransomware executable
+- Found C2 communications
+- Affected systems: WORKSTATION-01, FILESERVER-02
+```
+
+Claude would:
+1. Run `forensic_report` to aggregate findings
+2. Generate professional report with timeline and IOCs
+3. Include severity levels and recommendations
+
+---
+
+## Architecture
+
+### Design Philosophy
+
+- **Stateless:** Each analysis is independent
+- **Sandboxed:** File path validation prevents access to protected areas
+- **Non-invasive:** No file modification or execution
+- **Transparent:** All results include file paths and metadata
+- **Performance:** Streaming analysis for large files where possible
+
+### Tool Organization
+
+Each tool in `src/tools/` exports:
+1. **Schema:** Zod validation for inputs (exported as `{toolName}Schema`)
+2. **Function:** Async handler that performs analysis (exported as `{toolName}`)
+3. **Result types:** Defined in `src/types.ts`
+
+### MCP Server Structure
+
+```typescript
+// src/index.ts
+const server = new McpServer({
+  name: "forensic-analysis",
+  version: "1.0.0",
+});
+
+// Each tool registered with schema and handler
+server.tool("file_hash", "Calculate hashes", fileHashSchema.shape, toolHandler(fileHash));
+server.tool("file_strings", "Extract strings", fileStringsSchema.shape, toolHandler(fileStrings));
+// ... etc
+```
+
+The `toolHandler` wrapper:
+- Catches errors and returns them as MCP error responses
+- Serializes results to JSON
+- Maintains consistent response format
+
+---
+
+## Troubleshooting
+
+### "Command not found: strings"
+Ensure the `strings` utility is installed:
+```bash
+# macOS
+which strings  # Should be /usr/bin/strings
+
+# Linux
+sudo apt-get install binutils  # or yum install binutils
+
+# BSD
+pkg install binutils
+```
+
+### "Command not found: readelf"
+Install binutils:
+```bash
+# macOS
+brew install binutils
+
+# Linux
+sudo apt-get install binutils  # or yum install binutils
+```
+
+### "exiftool not found"
+Install exiftool:
+```bash
+# macOS
+brew install exiftool
+
+# Linux
+sudo apt-get install libimage-exiftool-perl
+# or
+sudo yum install perl-Image-ExifTool
+
+# From source
+visit https://exiftool.org/
+```
+
+### "File too large"
+The 100 MB limit exists to prevent memory issues. For larger files:
+- Analyze portions separately using other tools
+- Use external forensics tools (Volatility, Ghidra, IDA)
+- Consider file compression/splitting
+
+### "Command timed out"
+External commands have a 30-second timeout. For slow operations:
+- Try a smaller file
+- Verify the file isn't corrupted
+- Check system load
+
+### "Invalid PE file (missing MZ signature)"
+The file is not a Windows executable:
+- Use `file_identify` to confirm actual type
+- PE header parsing only works on PE files
+- Try `elf_header` for Linux binaries
+
+---
+
+## Performance Notes
+
+### Analysis Speed
+
+Tool performance depends on file size and complexity:
+
+- **file_hash:** ~10-50 MB/sec (limited by disk I/O)
+- **file_identify:** ~1-5 MB/sec (reads magic bytes only)
+- **file_entropy:** ~50-100 MB/sec (reads entire file)
+- **file_strings:** ~5-20 MB/sec (pattern matching overhead)
+- **pe_header:** ~10-50 MB/sec (inline parsing, no external tools)
+- **elf_header:** ~5-10 MB/sec (depends on readelf performance)
+- **exif_metadata:** ~1-5 MB/sec (depends on file type and exiftool)
+- **hash_directory:** ~5-30 MB/sec aggregate (depends on file count and sizes)
+- **file_correlate:** ~1-10 MB/sec (depends on log file size)
+- **forensic_report:** Instant (data aggregation only)
+
+### Memory Usage
+
+- Small files (< 10 MB): < 50 MB RAM
+- Medium files (10-50 MB): 100-300 MB RAM
+- Large files (50-100 MB): 300-600 MB RAM
+- Directory operations: Depends on file count (typically under 500 MB for 1000 files)
+
+---
+
+## License
+
+MIT License
+
+Copyright (c) 2024
+
+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.