Sharphy

Sharphy: CLR Intelligence & Runtime Forensic Bridge

Native Model Context Protocol (MCP) Server Empowering AI Coding Agents as Advanced .NET Runtime Diagnosticians, Memory Forensic Analysts, and Binary Architects.

Leveraging ECMA-335 Metadata Semantics, Cross-Platform Crash Dump Telemetry, and Rigid CIL Bytecode Navigation.

Architecture · Ecosystem · MCP Catalog · Agent Setup · Policies & Legal · Changelog · Contributing · Code of Conduct

[!CAUTION]

Legal Disclaimer & Limitation of Liability

Sharphy is engineered exclusively for good-faith security research, production crash dump diagnostics, vulnerability assessments, incident response, and lawful software engineering. Users bear sole civil and criminal responsibility for complying with applicable territorial cyber laws, third-party End User License Agreements (EULAs), and intellectual property rights. The developer disclaims any liability for malicious misuse or unlawful reverse engineering. Full details: DISCLAIMER.md.

[!IMPORTANT]

Install and execute Sharphy only from official distribution channels: verified NuGet packages (Sharphy.Cli under the verified Sharphy.* reserved prefix), official Model Context Protocol (MCP) Registry (io.github.baharmaulidiii/sharphy), or direct compilation from the official repository at github.com/baharmaulidiii/sharphy.

---

Architecture Overview & Philosophy

Mainstream AI coding agents (*Cursor*, *Claude Code*, *Windsurf*, *Copilot*) operate primarily on raw source code heuristics in an editor. They suffer from runtime blindness when confronting:

• Production memory crashes and unhandled fatal exceptions
• Multi-threaded synchronization deadlocks and lock cycle contention
• Large Object Heap (LOH) fragmentation and memory leaks
• Compiled third-party binaries lacking source code availability

Sharphy serves as a deterministic runtime forensic bridge implementing the open Model Context Protocol (MCP) specification. Over an isolated JSON-RPC 2.0 Stdio channel, Sharphy exposes Microsoft low-level diagnostics and decompilation engines directly to semantic AI reasoning loops.

┌─────────────────────────────────────────────────────────────┐

│ AI Coding Agent Client │ │ (Cursor / Claude Code / Windsurf / LLM) │ └──────────────────────────────┬──────────────────────────────┘ │ JSON-RPC 2.0 over Stdio ▼ ┌─────────────────────────────────────────────────────────────┐ │ Sharphy.Server (Host) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Pure Stdio Channel (stdout: Payloads / stderr: Log)│ │ │ │ JSON-RPC Dispatcher & Tool Registry (10 Tools) │ │ │ └──────────────────────────┬──────────────────────────┘ │ └──────────────────────────────┼──────────────────────────────┘ │ Strongly-Typed In-Process Calls ▼ ┌─────────────────────────────────────────────────────────────┐ │ Sharphy.Core Engine │ │ ┌───────────────────────┐ ┌───────────────────────┐ │ │ │ ClrMD Forensics │ │ ILSpy Engine │ │ │ │ (Crash Dump & Heap) │ │ (C# Decompilation) │ │ │ ├───────────────────────┤ ├───────────────────────┤ │ │ │ Mono.Cecil Engine │ │ Roslyn & Sandbox │ │ │ │ (Metadata & Mutation) │ │ (UnsafeAccessor & ALC)│ │ │ └───────────────────────┘ └───────────────────────┘ │ └──────────────────────────────┬──────────────────────────────┘ │ Deterministic Low-Level Inspection ▼ ┌─────────────────────────────────────────────────────────────┐ │ Runtime Analysis Target │ │ • Windows / Linux Crash Dump Files (.dmp / ELF core dump) │ │ • Compiled Binary Assemblies (.dll / .exe ECMA-335) │ │ • Active Runtime Processes & Isolated AssemblyLoadContext │ └─────────────────────────────────────────────────────────────┘

---

Package Ecosystem & Roles

The Sharphy solution is organized into three modular projects with distinct boundaries:

---

Operational Architecture: Zero-Footprint Production Forensics

A common enterprise architectural question is whether diagnostic servers must be deployed to live production machines.

Does Sharphy need to be installed on your production servers? NO.

Sharphy follows a Zero-Footprint, Post-Mortem Forensic Workflow. The analytical engines, decompilers, and AI agents run strictly in isolated development, CI/CD, or security analyst workstations:

┌──────────────────────────────────────────────┐

│ PRODUCTION ENVIRONMENT │ │ (Zero Sharphy Footprint Required) │ │ │ │ 1. Unhandled crash / freeze occurs │ │ 2. Collect memory dump via official CLI: │ │ dotnet-dump collect -p │ │ 3. Output: crash.dmp (Windows) / core (ELF) │ └──────────────────────┬───────────────────────┘ │ Secure SCP / S3 Dump Transfer ▼ ┌──────────────────────────────────────────────┐ │ ANALYST WORKSTATION / AI ENVIRONMENT │ │ (Isolated Off-Site Inspection) │ │ │ │ • AI Coding Agent (Cursor / Claude Code) │ │ • Sharphy MCP Server (Sharphy.Cli / Server) │ │ • Automated RCA: │ │ - sharphy_analyze_dump │ │ - sharphy_inspect_heap │ │ - sharphy_deadlock_detector │ └──────────────────────────────────────────────┘

Key Operational Benefits:

1. Zero Production Risk: No third-party daemons, background agents, or persistent listeners are installed on mission-critical production servers.
2. Standard Microsoft Tooling: Dump collection uses standard, officially supported Microsoft utilities (dotnet-dump, createdump, or OS crash reporting).
3. Regulatory & Audit Compliance: Keeps production environments compliant with strict compliance standards (PCI-DSS, ISO/IEC 27001, SOC 2) by avoiding intrusive monitoring hooks.
4. Air-Gapped & Offline Ready: Analysis can be performed in completely isolated, offline lab environments without remote runtime connectivity.

---

10 MCP Tools Catalog

Sharphy exposes ten specialized tools covering the full spectrum of .NET runtime analysis:

┌────────────────────────────────────────────────────────────────────────────┐

│ SHARPHY 10 MCP TOOLS CATALOG │ ├────────────────────────┬─────────────────────────┬─────────────────────────┤ │ Memory & Forensics │ Decompilation & Diff │ Bytecode & Metadata │ ├────────────────────────┼─────────────────────────┼─────────────────────────┤ │ • sharphy_analyze_dump │ • sharphy_decompile_... │ • sharphy_inspect_me... │ │ • sharphy_inspect_heap │ • sharphy_diff_assem... │ • sharphy_extract_to... │ │ • sharphy_deadlock_... │ • sharphy_clean_obfu... │ • sharphy_patch_il │ │ │ │ • sharphy_generate_w... │ └────────────────────────┴─────────────────────────┴─────────────────────────┘

1. sharphy_analyze_dump

Automated Root Cause Analysis (RCA) on Windows (.dmp) and Linux (ELF core dump) CoreCLR memory crash dumps. Extracts crashing thread call stacks, unhandled exception objects, and faulty HRESULT codes.

2. sharphy_inspect_heap

Deep managed heap inspection, traversing GC segments, measuring generation distribution (Gen 0, Gen 1, Gen 2, LOH, POH), calculating fragmentation, and pinpointing memory leak retainers.

3. sharphy_deadlock_detector

Traverses the CLR SyncBlock synchronization cache and active thread Monitor locks, building a Wait-For Graph (WFG) to detect thread synchronization deadlock cycles.

4. sharphy_decompile_method

Reconstructs clean, modern idiomatic C# source code from compiled CIL bytecode using the embedded ILSpy engine, reconstructing async state machines and lambda captures.

5. sharphy_diff_assemblies

Performs semantic binary comparisons between two versions of an assembly, flagging added/removed types, breaking changes to public/protected APIs, and CIL instruction size shifts.

6. sharphy_inspect_metadata

Inspects ECMA-335 metadata tables, decoding TypeDef, MethodDef, FieldDef, custom attributes, P/Invoke native imports, and embedded resources.

7. sharphy_clean_obfuscation

Analyzes obfuscated assemblies, demangling Control Flow Graph (CFG) switch-flattening patterns, trimming excessi