X-Ways-MCP

# X-Ways MCP Server An MCP server for X-Ways Forensics triage, installation validation, and controlled automation. This repo follows the same general idea as `bethington/ghidra-mcp`: put a specialist desktop analysis tool behind a structured MCP surface so agents can inspect state, run repeatable workflows, and keep a useful audit trail. The first version is intentionally a safe control plane. When command-line or scripting coverage is not enough, runners should generate a small X-Tension bridge for the specific in-process gap and document the API provenance for future runs. ## Current Capabilities - Discover X-Ways Forensics, WinHex, X-Ways Imager, and XWFIM executables. - Validate XWFIM `Temp` downloads and detect truncated ZIPs such as a bad `viewer.zip`. - Hash evidence and downloaded packages with MD5/SHA-1/SHA-256. - Create repeatable case workspace folders. - Build read-only triage inventories for mounted folders or exports. - Run a forensic harness that writes case manifests, report stubs, status JSON, and audit logs compatible with `Donovoi/forensic-copilot`. - Create disposable synthetic test environments for Windows, Linux, macOS, and generic evidence fixtures. - Build X-Ways launch commands without executing them. - Optionally launch X-Ways when explicitly enabled. - Fetch public X-Ways release information for quick version checks. - Cache and search the X-Ways manual locally for command-line, scripting, and headless workflow syntax. - Plan X-Ways operations with a headless-first, native-distributed-RVS, X-Tension-next, UI-last policy. - Generate local X-Tension bridge scaffolds with API notes and build hooks. - Inventory X-Ways executable imports, delay imports, `XWF_*` exports, and `XWF_*`/`XT_*` string clues with documented PowerShell cmdlets. - Expose the 77 verified `XWF_*` exports as agent-facing PowerShell cmdlets that create validated JSONL requests for an in-process X-Tension bridge. - Plan parallel X-Ways processing from the local manual: native distributed volume snapshot refinement first, isolated worker cases only as fallback. - Provide a reusable PowerShell guardrail module for container-first exports, manual/action gates, and contemporaneous notes. - Prefer query-first X-Ways analysis through command-line/script, Export List metadata, X-Tensions, reports, or bounded UI before materializing file contents. - Run read-only X-Ways case database usage-pattern triage from metadata strings, with sanitized reports and local-only alias maps. - Provide a loose case-run manifest contract so examiner harnesses such as `Donovoi/forensic-copilot` can consume sanitized X-Ways outputs without becoming tightly coupled to this repo. - Maintain a generic best-practice catalog so notes can record which jurisdiction/SOP guidance was followed and why. ## Safety Model Read-only and dry-run behavior is the default. `launch_xways` will not execute unless both conditions are true: - `XWAYS_MCP_ALLOW_EXECUTE=1` - the tool call passes `confirm=true` This avoids accidentally starting analysis, imaging, or script workflows while an agent is still planning. Automation preference is: 0. Manual first: check the newest available X-Ways manual, official docs, or approved local docs cache before deciding command syntax, API behavior, distributed processing, X-Tension work, or UI fallback. 1. X-Ways command-line, scripts, saved dialog selections, `Cfg:`, `XT:`, and `XTParam:*`. 2. X-Ways native distributed RVS for different evidence objects in the same case when the manual supports it. 3. A generated X-Tension bridge when the task needs in-process X-Ways access or the API covers something the headless surface cannot. 4. UI automation only as a bounded last resort. If a runner uses documented or undocumented X-Tensions API behavior, it must record the symbols, X-Ways version constraints, and provenance in local bridge notes before using the bridge on real evidence. X-Ways analysis is query-first. Use command-line/script routes, Export List metadata, reports, X-Tensions, or bounded UI queries when they can answer the question without materializing file contents. File-content exports are container-first only when bytes must leave X-Ways for external tooling. Metadata-only lists can be exported for planning, but copied/recovered file contents must first go into an X-Ways evidence file container. ## Requirements - Python 3.10+ - X-Ways Forensics, WinHex, X-Ways Imager, or XWFIM installed separately - Windows for real X-Ways launching and executable version inspection The server itself can run on other platforms for archive validation, hashing, and folder inventory work. ## Quick Start ```powershell python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -e ".[dev]" pytest python -m xways_mcp --transport stdio ``` Cache the current X-Ways manual locally for offline model lookup: ```powershell python -m pip install -e ".[dev]" python -c "from xways_mcp.manual import cache_xways_manual; print(cache_xways_manual(source=r'<XWAYS_ROOT>\manual.pdf'))" ``` To refresh from the public X-Ways manual and official scripting/setup pages: ```powershell python -c "from xways_mcp.manual import cache_xways_manual; print(cache_xways_manual(download_latest=True, fetch_official_docs=True, refresh=True))" ``` Run the MCP stdio smoke test: ```powershell python scripts\smoke_mcp.py --search-root "<XWFIM_ROOT>" --public-release ``` Run a forensic-copilot-compatible harness preflight: ```powershell python -m xways_mcp.harness xwfim-preflight ` --case-name CASE-001 ` --xwfim-root "<XWFIM_ROOT>" ` --staging-root artifacts ` --output-root reports ` --evidence-os Windows ` --evidence-mode portable-tooling ``` Run a local query-first usage-pattern triage over an existing X-Ways case database without exporting file contents: ```powershell .\scripts\Invoke-XwfCaseDbPathStringTriage.ps1 ``` The script writes a sanitized report, structured JSON, and a sensitive local-only alias map under the local case workspace reports folder. Compare a local X-Ways executable surface against the committed XWF/XT reference baseline: ```powershell Import-Module .\powershell\XWaysForensicWorkflow\XWaysForensicWorkflow.psd1 -Force Compare-XwfExternalSurface ` -XwfRoot "<XWF_ROOT>" ` -OutputDirectory ".\reports\xwf-external-surface" ``` The comparison writes Markdown, JSON, and CSV artifacts for imports, delay imports, exports, API-like strings, and undocumented-looking string candidates. Create validated XWF API bridge requests with the generated PowerShell cmdlets: ```powershell Import-Module .\powershell\XWaysForensicWorkflow\XWaysForensicWorkflow.psd1 -Force Get-XwfItemName -Argument @{ nItemID = 42 } Add-XwfComment ` -Argument @{ nItemID = 42; lpComment = 'Reviewed'; nFlagsHowToAdd = 0 } ` -OutboxPath ".\case-workspaces\CASE-001\xwf-api-requests.jsonl" ` -AllowMutating ``` These cmdlets do not call X-Ways exports directly from PowerShell. They produce `xwf-api-bridge-request/v1` objects for an in-process X-Tension bridge. Build disposable synthetic fixtures for every supported evidence OS: ```powershell python -m xways_mcp.testenv build --name CASE-001 --evidence-os all --root test-envs --force python -m xways_mcp.testenv destroy --name CASE-001 --evidence-os all --root test-envs --missing-ok ``` Configure your MCP client with: ```json { "mcpServers": { "xways-mcp": { "command": "python", "args": ["-m", "xways_mcp", "--transport", "stdio"], "env": { "XWAYS_HOME": "C:\\xwf", "XWAYS_MCP_SEARCH_ROOTS": "<XWAYS_ROOT>;<XWFIM_ROOT>", "XWAYS_MCP_ALLOW_EXECUTE": "0", "PYTHONIOENCODING": "utf-8" } } } } ``` ## Useful Tools - `environment` - `public_xways_release` - `manual_status` - `cache_xways_manual` - `search_xways_manual` - `headless_xways_reference` - `plan_xways_operation` - `plan_parallel_xways_jobs` - `create_xtension_scaffold` - `discover_installations` - `inspect_xwfim_cache` - `validate_archive` - `hash_file` - `create_workspace` - `triage_inventory` - `build_launch_command` - `launch_xways` - `harness_init_case` - `harness_xwfim_preflight` - `harness_folder_triage` - `testenv_create` - `testenv_build` - `testenv_run` - `testenv_destroy` - `testenv_list` See [docs/TOOLS.md](docs/TOOLS.md) for details. See [docs/FORENSIC_COPILOT.md](docs/FORENSIC_COPILOT.md) for integration with `Donovoi/forensic-copilot`. See [docs/INTEGRATION_CONTRACT.md](docs/INTEGRATION_CONTRACT.md) for the loose adapter contract and shared case-run manifest. See [docs/TEST_ENVIRONMENTS.md](docs/TEST_ENVIRONMENTS.md) for disposable synthetic fixture testing. See [docs/MANUAL_FIRST.md](docs/MANUAL_FIRST.md) for the manual-first tooling policy. See [docs/HEADLESS_XWAYS.md](docs/HEADLESS_XWAYS.md) for local manual indexing and headless command lookup. See [docs/PARALLEL_PROCESSING.md](docs/PARALLEL_PROCESSING.md) for the manual-backed distributed processing policy. See [docs/XTENSION_BRIDGE.md](docs/XTENSION_BRIDGE.md) for the generated X-Tension bridge workflow. See [docs/EXTERNAL_SURFACE_ANALYSIS.md](docs/EXTERNAL_SURFACE_ANALYSIS.md) for PE import/export/string analysis and the XWF 21.8 x64 baseline. See [docs/XWF_API_CMDLETS.md](docs/XWF_API_CMDLETS.md) for the generated PowerShell wrappers over the verified `XWF_*` exports. See [docs/FORENSIC_SOUNDNESS.md](docs/FORENSIC_SOUNDNESS.md) for the container-first export policy and reusable PowerShell module. See [docs/BEST_PRACTICES.md](docs/BEST_PRACTICES.md) for the public best-practice catalog and selection workflow. ## XWFIM Validation Example ```text inspect_xwfim_cache(path="<XWFIM_ROOT>") ``` This reports each ZIP in `Temp`, whether it can be opened, and whether the ZIP end-of-central-directory record is missing. That is the signal for a truncated download. ## Roadmap 1. Stabilize the Python MCP control plane. 2. Add stronger X-Ways script templates for repeatable triage. 3. Add native distributed RVS orchestration for multi-instance same-case runs. 4. Generate operation-specific X-Tension DLL bridges for in-process gaps. 5. Dynamically register X-Tension-backed tools when X-Ways is open. 6. Add reporting workflows for timeline, search hit, and tagged-file exports. ## References - X-Ways X-Tensions API: <https://www.x-ways.net/forensics/x-tensions/api.html> - X-Ways manual: <https://www.x-ways.net/winhex/manual.pdf> - X-Ways scripting: <https://www.x-ways.net/winhex/scripting.html> - X-Ways command-line setup notes: <https://www.x-ways.net/winhex/setup.html> - X-Ways release mailing list: <https://www.x-ways.net/winhex/mailings/>