Sharphy

注意

法律免责声明与责任限制 Sharphy 专为善意安全研究、生产环境崩溃转储诊断、漏洞评估、事件响应和合法软件工程而设计。用户须独自承担民事和刑事责任，确保遵守适用地区的网络法律、第三方最终用户许可协议（EULA）和知识产权。开发者不对恶意滥用或非法逆向工程承担任何责任。详情请参阅：DISCLAIMER.md。

重要

仅通过官方分发渠道安装和运行 Sharphy：经验证的 NuGet 包（位于已验证的 Sharphy.* 保留前缀下的 Sharphy.Cli）、官方模型上下文协议（MCP）注册表（io.github.baharmaulidiii/sharphy），或直接从 github.com/baharmaulidiii/sharphy 官方仓库编译。

---

架构概述与设计理念

主流 AI 编码 Agent（Cursor、Claude Code、Windsurf、Copilot）主要在编辑器中依据原始源代码启发式进行操作。面对以下情况时，它们会因无法感知运行时而束手无策：

• 生产环境中的内存崩溃和未处理的致命异常
• 多线程同步死锁和锁循环争用
• 大对象堆（LOH）碎片化和内存泄漏
• 无法获取源代码的已编译第三方二进制文件

Sharphy 充当确定性的运行时取证桥梁，实现开放的 Model Context Protocol（MCP） 规范。通过隔离的 JSON-RPC 2.0 Stdio 通道，Sharphy 将 Microsoft 底层诊断和反编译引擎直接提供给语义 AI 推理循环。

┌─────────────────────────────────────────────────────────────┐
│                   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  │
└─────────────────────────────────────────────────────────────┘

---

软件包生态与职责

Sharphy 解决方案由三个边界明确的模块化项目组成：

软件包 / 模块	分发方式	目标受众	架构职责与技术范围
Sharphy.Cli	.NET Global Tool	终端用户与 Agent	命令行入口。作为即时的零配置启动器运行 MCP 主机服务（sharphy mcp start），也可用于快速检查。
Sharphy.Server	Class Library / Host	Agent 框架与主机	使用 JSON-RPC 2.0 实现官方 Model Context Protocol（MCP）。严格隔离 Stdio 流：stdout 专用于 JSON-RPC 负载，所有内部诊断日志则路由至 stderr。
Sharphy.Core	Class Library Engine	CLR 工程师与构建者	不依赖 MCP 协议的纯分析引擎。封装底层库：Microsoft.Diagnostics.Runtime（ClrMD）、ICSharpCode.Decompiler（ILSpy）、Mono.Cecil 和 Microsoft.CodeAnalysis.CSharp（Roslyn）。

---

运行架构：零部署痕迹的生产环境取证

一个常见的企业架构问题是：诊断服务是否必须部署到正在运行的生产机器上？

Sharphy 需要安装在生产服务器上吗？不需要。

Sharphy 采用 零部署痕迹的事后取证工作流。分析引擎、反编译器和 AI Agent 严格在隔离的开发、CI/CD 或安全分析师工作站中运行：

┌──────────────────────────────────────────────┐
│         PRODUCTION ENVIRONMENT               │
│  (Zero Sharphy Footprint Required)           │
│                                              │
│  1. Unhandled crash / freeze occurs          │
│  2. Collect memory dump via official CLI:    │
│     dotnet-dump collect -p <PID>             │
│  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               │
└──────────────────────────────────────────────┘

主要运行优势：

1. 零生产风险： 不会在关键生产服务器上安装第三方守护进程、后台 Agent 或持久监听器。
2. 标准 Microsoft 工具： 转储文件的采集使用标准且受官方支持的 Microsoft 实用工具（dotnet-dump、createdump 或操作系统崩溃报告工具）。
3. 符合法规与审计要求： 避免使用侵入式监控钩子，使生产环境符合严格的合规标准（PCI-DSS、ISO/IEC 27001、SOC 2）。
4. 适用于隔离网与离线环境： 无需远程运行时连接，即可在完全隔离的离线实验室环境中进行分析。

---

10 个 MCP 工具目录

Sharphy 提供十种专用工具，覆盖 .NET 运行时分析的各个方面：

┌────────────────────────────────────────────────────────────────────────────┐
│                     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

对 Windows（.dmp）和 Linux（ELF core dump）CoreCLR 内存崩溃转储执行自动化根因分析（RCA）。提取发生崩溃的线程调用堆栈、未处理的异常对象和错误的 HRESULT 代码。

2. sharphy_inspect_heap

深入检查托管堆，遍历 GC 段，测量各代分布（Gen 0、Gen 1、Gen 2、LOH、POH），计算碎片化程度，并确定持有内存泄漏对象的引用。

3. sharphy_deadlock_detector

遍历 CLR SyncBlock 同步缓存和活动线程的 Monitor 锁，构建等待图（WFG），以检测线程同步死锁循环。

4. sharphy_decompile_method

使用内置 ILSpy 引擎，从已编译的 CIL 字节码还原简洁、现代且符合习惯用法的 C# 源代码，并重建异步状态机和 Lambda 捕获。

5. sharphy_diff_assemblies

对两个版本的程序集执行语义二进制比较，标记新增／移除的类型、对公共／受保护 API 的破坏性更改，以及 CIL 指令大小变化。

6. sharphy_inspect_metadata

检查 ECMA-335 元数据表，解码 TypeDef、MethodDef、FieldDef、自定义特性、P/Invoke 本机导入项和嵌入式资源。

7. sharphy_clean_obfuscation

分析混淆程序集，反混淆控制流图（CFG）的 switch 扁平化模式、裁剪过多的 NOP 序列，并识别动态代理委托。

8. sharphy_extract_tokens

通过将程序集加载到隔离的、可回收的 AssemblyLoadContext（isCollectible: true）中来提取令牌和类型，不会锁定磁盘上的文件，也不会污染宿主进程。

9. sharphy_patch_il

通过替换目标操作码、调整分支偏移量并重新生成修补后的二进制程序集，精确修改 CIL 字节码指令。

10. sharphy_generate_wrapper

生成零开销、强类型的 C# 包装器代码，利用 .NET 8+ [UnsafeAccessor] 特性访问私有成员和字段，无需承担反射开销。

---

安装与 Agent 集成

快速开始

通过 .NET SDK 安装全局 CLI 工具：

dotnet tool install -g Sharphy.Cli

Agent 配置（MCP 设置）

将 Sharphy 添加到 AI 编码客户端配置中：

Cursor（~/.cursor/mcp.json）或 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "sharphy": {
      "command": "sharphy",
      "args": ["mcp", "start"]
    }
  }
}

---

多目标架构

Sharphy 采用原生多目标架构，不依赖仿真层：

• .NET 8.0（LTS）： 长期企业级稳定性。
• .NET 9.0（STS）： 现代 GC 和性能优化。
• .NET 10.0（Latest）： 前沿编译器 API 和运行时功能。

---

社区规范、安全与法律政策

• CONTRIBUTING.md 中的工程标准和工作流。
• CODE_OF_CONDUCT.md 中的社区行为准则。
• SECURITY.md 中的威胁建模和漏洞报告。
• ACCESSIBILITY.md 中的无障碍承诺。
• TRADEMARK.md 中的商标和品牌指南。
• DISCLAIMER.md 中的责任限制。
• THIRD_PARTY_NOTICE.md 中的第三方归属和许可信息。

许可证

Sharphy 根据 Apache License, Version 2.0 发行。版权所有 (c) 2026 Moh. Baharudin Yuda Maulidi。保留所有权利。