#!/usr/bin/env python3
"""Agent for Windows artifact analysis with Eric Zimmerman tools.

Runs EZ tools (MFTECmd, PECmd, LECmd, JLECmd, ShellBags Explorer CLI)
via subprocess, parses CSV output, and builds a forensic timeline
from Windows filesystem and registry artifacts.
"""

import subprocess
import json
import sys
import csv
import io
from datetime import datetime
from pathlib import Path


class EZToolsAgent:
    """Analyzes Windows forensic artifacts using Eric Zimmerman tools."""

    def __init__(self, output_dir="./ez_analysis"):
        self.output_dir = Path(output_dir)
        self.output_dir.mkdir(parents=True, exist_ok=True)
        self.timeline = []

    def _run_tool(self, tool, args, timeout=300):
        cmd = [tool] + args
        try:
            result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
            return {"return_code": result.returncode,
                    "stdout_lines": len(result.stdout.splitlines()),
                    "stderr": result.stderr[:300] if result.stderr else ""}
        except FileNotFoundError:
            return {"error": f"{tool} not found. Download from https://ericzimmerman.github.io/"}
        except subprocess.TimeoutExpired:
            return {"error": f"{tool} timed out"}

    def parse_mft(self, mft_path):
        """Parse $MFT using MFTECmd and extract file creation/modification."""
        csv_out = self.output_dir / "mft_output.csv"
        result = self._run_tool("MFTECmd.exe", ["-f", mft_path,
                                                  "--csv", str(self.output_dir),
                                                  "--csvf", "mft_output.csv"])
        if "error" in result:
            return result
        return self._parse_csv(csv_out, "MFT",
                               time_cols=["Created0x10", "LastModified0x10"])

    def parse_prefetch(self, prefetch_dir):
        """Parse Prefetch files using PECmd for program execution evidence."""
        csv_out = self.output_dir / "prefetch_output.csv"
        result = self._run_tool("PECmd.exe", ["-d", prefetch_dir,
                                               "--csv", str(self.output_dir),
                                               "--csvf", "prefetch_output.csv"])
        if "error" in result:
            return result
        return self._parse_csv(csv_out, "Prefetch",
                               time_cols=["LastRun", "PreviousRun0"])

    def parse_lnk_files(self, lnk_dir):
        """Parse LNK shortcut files using LECmd."""
        csv_out = self.output_dir / "lnk_output.csv"
        result = self._run_tool("LECmd.exe", ["-d", lnk_dir,
                                               "--csv", str(self.output_dir),
                                               "--csvf", "lnk_output.csv"])
        if "error" in result:
            return result
        return self._parse_csv(csv_out, "LNK",
                               time_cols=["TargetCreated", "TargetModified"])

    def parse_jump_lists(self, jl_dir):
        """Parse Jump Lists using JLECmd for recent file access."""
        csv_out = self.output_dir / "jumplist_output.csv"
        result = self._run_tool("JLECmd.exe", ["-d", jl_dir,
                                                "--csv", str(self.output_dir),
                                                "--csvf", "jumplist_output.csv"])
        if "error" in result:
            return result
        return self._parse_csv(csv_out, "JumpList",
                               time_cols=["TargetCreated", "TargetModified"])

    def parse_shellbags(self, registry_hive):
        """Parse ShellBags from NTUSER.DAT/UsrClass.dat."""
        csv_out = self.output_dir / "shellbags_output.csv"
        result = self._run_tool("SBECmd.exe", ["-d", registry_hive,
                                                "--csv", str(self.output_dir),
                                                "--csvf", "shellbags_output.csv"])
        if "error" in result:
            return result
        return self._parse_csv(csv_out, "ShellBag",
                               time_cols=["LastWriteTime", "FirstExplored"])

    def _parse_csv(self, csv_path, artifact_type, time_cols=None):
        """Parse EZ tool CSV output into timeline entries."""
        if not csv_path.exists():
            return {"error": f"CSV not found: {csv_path}"}
        entries = []
        try:
            with open(csv_path, "r", encoding="utf-8-sig") as f:
                reader = csv.DictReader(f)
                for row in reader:
                    entry = {"artifact_type": artifact_type}
                    for key, val in row.items():
                        if val:
                            entry[key] = val
                    if time_cols:
                        for tc in time_cols:
                            ts = row.get(tc, "")
                            if ts:
                                entry["timestamp"] = ts
                                self.timeline.append({
                                    "timestamp": ts,
                                    "artifact": artifact_type,
                                    "source": csv_path.name,
                                    "details": {k: v for k, v in row.items()
                                                if v and k != tc}
                                })
                                break
                    entries.append(entry)
        except (csv.Error, UnicodeDecodeError) as exc:
            return {"error": str(exc)}
        return {"artifact": artifact_type, "entries": len(entries)}

    def build_timeline(self):
        """Sort all collected entries into a unified forensic timeline."""
        self.timeline.sort(key=lambda x: x.get("timestamp", ""))
        return self.timeline

    def generate_report(self):
        self.build_timeline()
        report = {
            "report_date": datetime.utcnow().isoformat(),
            "total_timeline_entries": len(self.timeline),
            "timeline_sample": self.timeline[:50],
        }
        report_path = self.output_dir / "ez_tools_report.json"
        with open(report_path, "w") as f:
            json.dump(report, f, indent=2, default=str)
        print(json.dumps(report, indent=2, default=str))
        return report


def main():
    if len(sys.argv) < 3:
        print("Usage: agent.py <artifact_type> <path>")
        print("  artifact_type: mft|prefetch|lnk|jumplist|shellbag")
        sys.exit(1)
    agent = EZToolsAgent()
    atype = sys.argv[1]
    path = sys.argv[2]
    dispatch = {"mft": agent.parse_mft, "prefetch": agent.parse_prefetch,
                "lnk": agent.parse_lnk_files, "jumplist": agent.parse_jump_lists,
                "shellbag": agent.parse_shellbags}
    fn = dispatch.get(atype)
    if fn:
        fn(path)
    agent.generate_report()


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
EZ Tools Forensic Artifact Processor

Automates the execution of Eric Zimmerman's tools against collected
forensic artifacts and generates consolidated analysis reports.
"""

import subprocess
import csv
import os
import sys
import json
import hashlib
from pathlib import Path
from datetime import datetime
from collections import defaultdict


class EZToolsProcessor:
    """Orchestrates EZ Tools processing against forensic artifact collections."""

    def __init__(self, ez_tools_path: str, evidence_path: str, output_path: str):
        self.ez_tools_path = Path(ez_tools_path)
        self.evidence_path = Path(evidence_path)
        self.output_path = Path(output_path)
        self.output_path.mkdir(parents=True, exist_ok=True)
        self.results = {}
        self.tools = {
            "MFTECmd": self.ez_tools_path / "MFTECmd.exe",
            "PECmd": self.ez_tools_path / "PECmd.exe",
            "LECmd": self.ez_tools_path / "LECmd.exe",
            "JLECmd": self.ez_tools_path / "JLECmd.exe",
            "SBECmd": self.ez_tools_path / "SBECmd.exe",
            "EvtxECmd": self.ez_tools_path / "EvtxECmd.exe",
            "RECmd": self.ez_tools_path / "RECmd.exe",
            "RBCmd": self.ez_tools_path / "RBCmd.exe",
            "AmcacheParser": self.ez_tools_path / "AmcacheParser.exe",
            "AppCompatCacheParser": self.ez_tools_path / "AppCompatCacheParser.exe",
        }

    def verify_tools(self) -> dict:
        """Verify which EZ Tools are available on the system."""
        availability = {}
        for name, path in self.tools.items():
            availability[name] = path.exists()
        return availability

    def run_tool(self, tool_name: str, args: list) -> dict:
        """Execute an EZ Tool with given arguments."""
        tool_path = self.tools.get(tool_name)
        if not tool_path or not tool_path.exists():
            return {"status": "error", "message": f"{tool_name} not found at {tool_path}"}

        cmd = [str(tool_path)] + args
        try:
            result = subprocess.run(
                cmd,
                capture_output=True,
                text=True,
                timeout=300
            )
            return {
                "status": "success" if result.returncode == 0 else "error",
                "stdout": result.stdout,
                "stderr": result.stderr,
                "returncode": result.returncode
            }
        except subprocess.TimeoutExpired:
            return {"status": "error", "message": f"{tool_name} timed out after 300 seconds"}
        except Exception as e:
            return {"status": "error", "message": str(e)}

    def process_mft(self, mft_path: str = None) -> dict:
        """Parse the $MFT file with MFTECmd."""
        if mft_path is None:
            mft_candidates = list(self.evidence_path.rglob("$MFT"))
            if not mft_candidates:
                return {"status": "skipped", "message": "$MFT not found"}
            mft_path = str(mft_candidates[0])

        output_file = "MFT_output.csv"
        args = ["-f", mft_path, "--csv", str(self.output_path), "--csvf", output_file]
        result = self.run_tool("MFTECmd", args)
        result["output_file"] = str(self.output_path / output_file)
        self.results["MFT"] = result
        return result

    def process_usn_journal(self, journal_path: str = None) -> dict:
        """Parse the USN Journal ($J) with MFTECmd."""
        if journal_path is None:
            j_candidates = list(self.evidence_path.rglob("$J"))
            if not j_candidates:
                return {"status": "skipped", "message": "$J not found"}
            journal_path = str(j_candidates[0])

        output_file = "USNJournal_output.csv"
        args = ["-f", journal_path, "--csv", str(self.output_path), "--csvf", output_file]
        result = self.run_tool("MFTECmd", args)
        result["output_file"] = str(self.output_path / output_file)
        self.results["USNJournal"] = result
        return result

    def process_prefetch(self, prefetch_dir: str = None) -> dict:
        """Parse Prefetch files with PECmd."""
        if prefetch_dir is None:
            pf_candidates = list(self.evidence_path.rglob("Prefetch"))
            if not pf_candidates:
                return {"status": "skipped", "message": "Prefetch directory not found"}
            prefetch_dir = str(pf_candidates[0])

        output_file = "Prefetch_output.csv"
        args = ["-d", prefetch_dir, "--csv", str(self.output_path), "--csvf", output_file]
        result = self.run_tool("PECmd", args)
        result["output_file"] = str(self.output_path / output_file)
        self.results["Prefetch"] = result
        return result

    def process_lnk_files(self, lnk_dir: str = None) -> dict:
        """Parse LNK shortcut files with LECmd."""
        if lnk_dir is None:
            recent_candidates = list(self.evidence_path.rglob("Recent"))
            if not recent_candidates:
                return {"status": "skipped", "message": "Recent directory not found"}
            lnk_dir = str(recent_candidates[0])

        output_file = "LNK_output.csv"
        args = ["-d", lnk_dir, "--csv", str(self.output_path), "--csvf", output_file]
        result = self.run_tool("LECmd", args)
        result["output_file"] = str(self.output_path / output_file)
        self.results["LNK"] = result
        return result

    def process_jump_lists(self, jl_dir: str = None) -> dict:
        """Parse Jump List files with JLECmd."""
        if jl_dir is None:
            auto_dest = list(self.evidence_path.rglob("AutomaticDestinations"))
            if not auto_dest:
                return {"status": "skipped", "message": "AutomaticDestinations not found"}
            jl_dir = str(auto_dest[0])

        output_file = "JumpLists_output.csv"
        args = ["-d", jl_dir, "--csv", str(self.output_path), "--csvf", output_file]
        result = self.run_tool("JLECmd", args)
        result["output_file"] = str(self.output_path / output_file)
        self.results["JumpLists"] = result
        return result

    def process_event_logs(self, evtx_dir: str = None) -> dict:
        """Parse Windows Event Logs with EvtxECmd."""
        if evtx_dir is None:
            logs_candidates = list(self.evidence_path.rglob("winevt"))
            if logs_candidates:
                evtx_dir = str(logs_candidates[0] / "Logs")
            else:
                evtx_files = list(self.evidence_path.rglob("*.evtx"))
                if not evtx_files:
                    return {"status": "skipped", "message": "Event logs not found"}
                evtx_dir = str(evtx_files[0].parent)

        output_file = "EventLogs_output.csv"
        args = ["-d", evtx_dir, "--csv", str(self.output_path), "--csvf", output_file]
        result = self.run_tool("EvtxECmd", args)
        result["output_file"] = str(self.output_path / output_file)
        self.results["EventLogs"] = result
        return result

    def process_shellbags(self, registry_dir: str = None) -> dict:
        """Parse Shellbag artifacts with SBECmd."""
        if registry_dir is None:
            registry_dir = str(self.evidence_path)

        output_file = "Shellbags_output.csv"
        args = ["-d", registry_dir, "--csv", str(self.output_path), "--csvf", output_file]
        result = self.run_tool("SBECmd", args)
        result["output_file"] = str(self.output_path / output_file)
        self.results["Shellbags"] = result
        return result

    def process_recycle_bin(self, recycle_dir: str = None) -> dict:
        """Parse Recycle Bin artifacts with RBCmd."""
        if recycle_dir is None:
            rb_candidates = list(self.evidence_path.rglob("$Recycle.Bin"))
            if not rb_candidates:
                return {"status": "skipped", "message": "$Recycle.Bin not found"}
            recycle_dir = str(rb_candidates[0])

        output_file = "RecycleBin_output.csv"
        args = ["-d", recycle_dir, "--csv", str(self.output_path), "--csvf", output_file]
        result = self.run_tool("RBCmd", args)
        result["output_file"] = str(self.output_path / output_file)
        self.results["RecycleBin"] = result
        return result

    def detect_timestomping(self, mft_csv_path: str) -> list:
        """Analyze MFT CSV output to detect timestomping indicators."""
        timestomped = []
        try:
            with open(mft_csv_path, "r", encoding="utf-8-sig") as f:
                reader = csv.DictReader(f)
                for row in reader:
                    si_created = row.get("Created0x10", "")
                    fn_created = row.get("Created0x30", "")
                    if si_created and fn_created:
                        try:
                            si_dt = datetime.fromisoformat(si_created.replace("Z", "+00:00"))
                            fn_dt = datetime.fromisoformat(fn_created.replace("Z", "+00:00"))
                            if si_dt < fn_dt:
                                timestomped.append({
                                    "file": row.get("FileName", "Unknown"),
                                    "entry_number": row.get("EntryNumber", ""),
                                    "si_created": si_created,
                                    "fn_created": fn_created,
                                    "indicator": "$SI Created before $FN Created"
                                })
                        except (ValueError, TypeError):
                            continue
        except FileNotFoundError:
            return [{"error": f"MFT CSV not found: {mft_csv_path}"}]
        return timestomped

    def process_all(self) -> dict:
        """Run all available EZ Tools processors against evidence."""
        print("[*] Starting comprehensive EZ Tools processing...")
        print(f"[*] Evidence path: {self.evidence_path}")
        print(f"[*] Output path: {self.output_path}")

        available = self.verify_tools()
        print(f"[*] Available tools: {sum(v for v in available.values())}/{len(available)}")

        processors = [
            ("MFT", self.process_mft),
            ("USN Journal", self.process_usn_journal),
            ("Prefetch", self.process_prefetch),
            ("LNK Files", self.process_lnk_files),
            ("Jump Lists", self.process_jump_lists),
            ("Event Logs", self.process_event_logs),
            ("Shellbags", self.process_shellbags),
            ("Recycle Bin", self.process_recycle_bin),
        ]

        for name, processor in processors:
            print(f"[*] Processing {name}...")
            result = processor()
            status = result.get("status", "unknown")
            print(f"    [{status.upper()}] {name}")

        return self.results

    def generate_report(self) -> str:
        """Generate a summary report of all processing results."""
        report = {
            "timestamp": datetime.now().isoformat(),
            "evidence_path": str(self.evidence_path),
            "output_path": str(self.output_path),
            "results": {}
        }

        for artifact, result in self.results.items():
            report["results"][artifact] = {
                "status": result.get("status", "unknown"),
                "output_file": result.get("output_file", ""),
            }
            output_file = result.get("output_file", "")
            if output_file and os.path.exists(output_file):
                file_size = os.path.getsize(output_file)
                report["results"][artifact]["output_size_bytes"] = file_size
                with open(output_file, "rb") as f:
                    report["results"][artifact]["sha256"] = hashlib.sha256(f.read()).hexdigest()

        report_path = self.output_path / "processing_report.json"
        with open(report_path, "w") as f:
            json.dump(report, f, indent=2)

        print(f"\n[*] Report saved to: {report_path}")
        return str(report_path)


def main():
    if len(sys.argv) < 4:
        print("Usage: python process.py <ez_tools_path> <evidence_path> <output_path>")
        print("Example: python process.py C:\\Tools\\EZTools C:\\Cases\\Evidence C:\\Cases\\Output")
        sys.exit(1)

    ez_tools_path = sys.argv[1]
    evidence_path = sys.argv[2]
    output_path = sys.argv[3]

    processor = EZToolsProcessor(ez_tools_path, evidence_path, output_path)
    processor.process_all()
    processor.generate_report()


if __name__ == "__main__":
    main()