diff --git a/README.md b/README.md index a742d3d..d7397e8 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,28 @@ # mcilspy -A Model Context Protocol (MCP) server that provides .NET assembly decompilation capabilities using ILSpy. +[![PyPI version](https://img.shields.io/pypi/v/mcilspy.svg)](https://pypi.org/project/mcilspy/) +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) +[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/) -## Features +**Decompile, search, and analyze .NET assemblies with AI assistance.** -### ILSpy-based Tools (requires ilspycmd) -- **Decompile Assemblies**: Convert .NET assemblies back to readable C# source code -- **List Types**: Enumerate classes, interfaces, structs, delegates, and enums in assemblies -- **Search Types**: Find types by name pattern with regex support -- **Search Strings**: Find hardcoded strings in assembly code (URLs, credentials, etc.) -- **Generate Diagrammer**: Create interactive HTML visualizations of assembly structure -- **Assembly Information**: Get metadata about .NET assemblies (version, target framework, etc.) +An MCP server that gives Claude (or any MCP client) the power to reverse-engineer .NET binaries — find hardcoded secrets, understand obfuscated code, recover lost source, and explore assembly internals. -### Direct Metadata Tools (no ilspycmd required) -- **Search Methods**: Find methods by name pattern directly from metadata tables -- **Search Fields**: Find fields and constants in assemblies -- **Search Properties**: Find properties by name pattern -- **List Events**: Enumerate all events defined in an assembly -- **List Resources**: List embedded resources (files, images, etc.) -- **Metadata Summary**: Get comprehensive assembly metadata with statistics +--- -### Installation & Diagnostics -- **Check Installation**: Verify ilspycmd and dotnet CLI status -- **Install ILSpy**: Automatically install or update ilspycmd - -## Prerequisites - -1. **ILSpy Command Line Tool**: Install the global dotnet tool: - ```bash - dotnet tool install --global ilspycmd - ``` - -2. **Python 3.10+**: Required for running the MCP server - -## Installation - -Install from PyPI: +## Quick Start (30 seconds) ```bash +# Install pip install mcilspy + +# Add to Claude Code +claude mcp add ilspy -- python -m mcilspy.server + +# Or add to Claude Desktop's config.json ``` -Or for development: - -```bash -git clone https://github.com/Borealin/mcilspy.git -cd mcilspy -pip install -e . -``` - -## Usage - -### MCP Client Configuration - -Configure your MCP client (e.g., Claude Desktop) to use the server: - ```json { "mcpServers": { @@ -66,313 +34,364 @@ Configure your MCP client (e.g., Claude Desktop) to use the server: } ``` -### Available Tools +**That's it.** Ask Claude to analyze any `.dll` or `.exe`: -#### 1. `decompile_assembly` -Decompile a .NET assembly to C# source code. This is the primary tool for reverse-engineering .NET binaries. +> *"Decompile the LoginService class from this assembly and explain what it does"* -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file -- `output_dir` (optional): Output directory for decompiled files -- `type_name` (optional): Fully qualified type name to decompile (e.g., "MyNamespace.MyClass") -- `language_version` (optional): C# language version (default: "Latest") -- `create_project` (optional): Create a compilable project structure -- `show_il_code` (optional): Show IL bytecode instead of C# -- `remove_dead_code` (optional): Remove unreachable code during decompilation -- `remove_dead_stores` (optional): Remove unused variable assignments -- `show_il_sequence_points` (optional): Include debugging sequence points in IL output -- `nested_directories` (optional): Use nested directories for namespaces +--- + +## What Can You Do? + +### Find Hardcoded Secrets +``` +"Search for any URLs, API keys, or connection strings in MyApp.dll" +``` +Discovers hardcoded credentials, endpoints, and configuration that shouldn't be in code. + +### Reverse Engineer Unknown Binaries +``` +"List all the types in this DLL and identify the main entry points" +``` +Understand the structure of any .NET assembly without source code. + +### Recover Lost Source Code +``` +"Decompile the entire assembly to a project I can build" +``` +Recreate compilable C# projects from binaries when source is unavailable. + +### Analyze Malware Behavior +``` +"Find all network-related methods and show me what URLs this malware contacts" +``` +Safe static analysis of suspicious .NET executables. + +### Understand Third-Party Libraries +``` +"Show me how Newtonsoft.Json handles circular references" +``` +Learn from decompiled implementations when documentation falls short. + +--- + +## Features at a Glance + +| Tool | What It Does | Requires ilspycmd? | +|------|--------------|:------------------:| +| `decompile_assembly` | Full C# source recovery | Yes | +| `list_types` | Enumerate classes, interfaces, enums | Yes | +| `search_types` | Find types by name pattern | Yes | +| `search_strings` | Find hardcoded strings (URLs, keys) | Yes | +| `search_methods` | Find methods by name | No | +| `search_fields` | Find fields and constants | No | +| `search_properties` | Find properties by name | No | +| `list_events` | List all events | No | +| `list_resources` | Find embedded files/images | No | +| `get_metadata_summary` | Assembly stats and references | No | +| `generate_diagrammer` | Interactive HTML type diagrams | Yes | +| `get_assembly_info` | Version, framework, signing info | Yes | +| `check_ilspy_installation` | Diagnose setup issues | No | +| `install_ilspy` | Auto-install .NET SDK + ilspycmd | No | + +**6 tools work immediately** (via [dnfile](https://github.com/malwarefrank/dnfile)) — no .NET SDK required. +**8 more tools** unlock with `ilspycmd` for full decompilation power. + +--- + +## Installation Options + +### Option 1: Just the MCP Server (metadata tools only) +```bash +pip install mcilspy +``` +Gives you search and metadata tools immediately. + +### Option 2: Full Decompilation Power +```bash +# Install the MCP server +pip install mcilspy + +# Let the server install ilspycmd for you (detects your OS automatically) +# Just ask Claude: "Install ilspycmd" or call install_ilspy with install_dotnet_sdk=true +``` + +**Supported platforms for auto-install:** +- Arch Linux (`pacman`) +- Ubuntu/Debian (`apt`) +- Fedora/RHEL (`dnf`) +- macOS (`homebrew`) +- Windows (`winget` / `chocolatey`) + +### Option 3: Manual ilspycmd Setup +```bash +# Install .NET SDK from https://dotnet.microsoft.com/download +# Then: +dotnet tool install --global ilspycmd +``` + +--- + +## Table of Contents + +- [Quick Start](#quick-start-30-seconds) +- [What Can You Do?](#what-can-you-do) +- [Features at a Glance](#features-at-a-glance) +- [Installation Options](#installation-options) +- [Tool Reference](#tool-reference) + - [Decompilation Tools](#decompilation-tools-requires-ilspycmd) + - [Metadata Tools](#metadata-tools-no-ilspycmd-required) + - [Installation Tools](#installation--diagnostics) +- [Configuration](#configuration) +- [Troubleshooting](#troubleshooting) +- [License & Acknowledgments](#license) + +--- + +## Tool Reference + +### Decompilation Tools (requires ilspycmd) + +
+decompile_assembly — Convert binaries back to C# source + +The primary reverse-engineering tool. Decompiles .NET assemblies to readable C#. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | +| `type_name` | No | Specific type to decompile (e.g., `MyNamespace.MyClass`) | +| `output_dir` | No | Save decompiled files to directory | +| `create_project` | No | Generate compilable .csproj structure | +| `language_version` | No | C# version (default: Latest) | +| `show_il_code` | No | Output IL bytecode instead of C# | -**Example:** ```json { - "name": "decompile_assembly", - "arguments": { - "assembly_path": "/path/to/MyAssembly.dll", - "type_name": "MyNamespace.MyClass", - "language_version": "CSharp10_0" - } + "assembly_path": "/path/to/MyApp.dll", + "type_name": "MyApp.Services.AuthService" +} +``` +
+ +
+list_types — Enumerate types in an assembly + +Your starting point for exploring unknown assemblies. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | +| `entity_types` | No | Filter: `class`, `interface`, `struct`, `delegate`, `enum` | + +```json +{ + "assembly_path": "/path/to/MyApp.dll", + "entity_types": ["class", "interface"] +} +``` +
+ +
+search_types — Find types by name pattern + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | +| `pattern` | Yes | Search pattern | +| `namespace_filter` | No | Limit to specific namespace | +| `use_regex` | No | Enable regex matching | +| `case_sensitive` | No | Case-sensitive search | + +```json +{ + "assembly_path": "/path/to/MyApp.dll", + "pattern": "Controller", + "namespace_filter": "MyApp.Web" +} +``` +
+ +
+search_strings — Find hardcoded strings (secrets, URLs, config) + +Essential for security analysis. Finds strings embedded in IL code. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | +| `pattern` | Yes | String to search for | +| `use_regex` | No | Enable regex matching | +| `max_results` | No | Limit results (default: 100) | + +```json +{ + "assembly_path": "/path/to/MyApp.dll", + "pattern": "api\\..*\\.com" + "use_regex": true +} +``` +
+ +
+generate_diagrammer — Create interactive type relationship diagrams + +Generates an HTML visualization of type hierarchies and relationships. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | +| `output_dir` | No | Where to save the HTML | +| `include_pattern` | No | Regex for types to include | +| `exclude_pattern` | No | Regex for types to exclude | + +
+ +
+get_assembly_info — Get assembly metadata + +Returns version, target framework, strong name signing status, and debug info. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | + +
+ +### Metadata Tools (no ilspycmd required) + +These tools use direct PE/metadata parsing via [dnfile](https://github.com/malwarefrank/dnfile) and work without any .NET installation. + +
+search_methods — Find methods by name pattern + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | +| `pattern` | Yes | Method name pattern | +| `type_filter` | No | Limit to types containing this string | +| `namespace_filter` | No | Limit to specific namespace | +| `public_only` | No | Only public methods | +| `use_regex` | No | Enable regex matching | + +```json +{ + "assembly_path": "/path/to/MyApp.dll", + "pattern": "Handle", + "public_only": true +} +``` +
+ +
+search_fields — Find fields and constants + +Great for finding magic numbers, configuration values, and API keys stored as constants. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | +| `pattern` | Yes | Field name pattern | +| `constants_only` | No | Only literal/const fields | +| `public_only` | No | Only public fields | + +```json +{ + "assembly_path": "/path/to/MyApp.dll", + "pattern": "Key|Secret|Password", + "use_regex": true, + "constants_only": true +} +``` +
+ +
+search_properties — Find properties by name + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | +| `pattern` | Yes | Property name pattern | +| `type_filter` | No | Limit to types containing this string | +| `namespace_filter` | No | Limit to specific namespace | + +
+ +
+list_events — List all events in an assembly + +Useful for understanding event-driven architectures and observer patterns. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | +| `type_filter` | No | Limit to types containing this string | +| `namespace_filter` | No | Limit to specific namespace | + +
+ +
+list_resources — Find embedded resources + +Discovers embedded files, images, localization data, and other resources. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | + +
+ +
+get_metadata_summary — Comprehensive assembly statistics + +Returns type/method/field/property/event counts and referenced assemblies. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to .dll or .exe | + +
+ +### Installation & Diagnostics + +
+check_ilspy_installation — Diagnose your setup + +Shows whether dotnet CLI and ilspycmd are installed, with version info and troubleshooting tips. + +No parameters required. +
+ +
+install_ilspy — Auto-install everything you need + +Detects your platform and installs the .NET SDK and ilspycmd automatically. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `update` | No | Update ilspycmd to latest version | +| `install_dotnet_sdk` | No | Also install .NET SDK if missing | + +```json +{ + "install_dotnet_sdk": true } ``` -#### 2. `list_types` -List types in a .NET assembly. Typically the **first tool to use** when analyzing an unknown assembly. +**Auto-detected package managers:** pacman, apt, dnf, zypper, homebrew, winget, chocolatey +
-**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file -- `entity_types` (optional): Types to include (accepts full names or single letters): - - `"class"` or `"c"` (default) - - `"interface"` or `"i"` - - `"struct"` or `"s"` - - `"delegate"` or `"d"` - - `"enum"` or `"e"` - -**Example:** -```json -{ - "name": "list_types", - "arguments": { - "assembly_path": "/path/to/MyAssembly.dll", - "entity_types": ["class", "interface"] - } -} -``` - -#### 3. `search_types` -Search for types by name pattern. Essential for finding specific classes in large assemblies. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file -- `pattern` (required): Search pattern to match against type names -- `namespace_filter` (optional): Only search in namespaces containing this string -- `entity_types` (optional): Types to search (default: all types) -- `case_sensitive` (optional): Case-sensitive matching (default: false) -- `use_regex` (optional): Treat pattern as regular expression (default: false) - -**Example:** -```json -{ - "name": "search_types", - "arguments": { - "assembly_path": "/path/to/MyAssembly.dll", - "pattern": "Service", - "namespace_filter": "MyApp.Services" - } -} -``` - -#### 4. `search_strings` -Search for string literals in assembly code. Crucial for reverse engineering - finds hardcoded URLs, credentials, configuration, etc. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file -- `pattern` (required): String pattern to search for -- `case_sensitive` (optional): Case-sensitive matching (default: false) -- `use_regex` (optional): Treat pattern as regular expression (default: false) -- `max_results` (optional): Maximum matches to return (default: 100) - -**Example:** -```json -{ - "name": "search_strings", - "arguments": { - "assembly_path": "/path/to/MyAssembly.dll", - "pattern": "api.example.com" - } -} -``` - -#### 5. `generate_diagrammer` -Generate an interactive HTML diagram showing assembly type relationships. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file -- `output_dir` (optional): Output directory for the diagrammer -- `include_pattern` (optional): Regex pattern for types to include -- `exclude_pattern` (optional): Regex pattern for types to exclude - -#### 6. `get_assembly_info` -Get metadata and version information about an assembly. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file - -Returns: Assembly name, version, target framework, signing status, and debug info availability. - -### Direct Metadata Tools - -These tools use direct PE/metadata parsing via [dnfile](https://github.com/malwarefrank/dnfile) and don't require ilspycmd to be installed. - -#### 7. `search_methods` -Search for methods in an assembly by name pattern. Useful for finding entry points, event handlers, and API endpoints. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file -- `pattern` (required): Search pattern to match against method names -- `type_filter` (optional): Only search methods in types containing this string -- `namespace_filter` (optional): Only search in namespaces containing this string -- `public_only` (optional): Only return public methods (default: false) -- `case_sensitive` (optional): Case-sensitive matching (default: false) -- `use_regex` (optional): Treat pattern as regular expression (default: false) - -**Example:** -```json -{ - "name": "search_methods", - "arguments": { - "assembly_path": "/path/to/MyAssembly.dll", - "pattern": "Handle", - "public_only": true - } -} -``` - -#### 8. `search_fields` -Search for fields and constants in an assembly. Useful for finding configuration values and magic numbers. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file -- `pattern` (required): Search pattern to match against field names -- `type_filter` (optional): Only search fields in types containing this string -- `namespace_filter` (optional): Only search in namespaces containing this string -- `public_only` (optional): Only return public fields (default: false) -- `constants_only` (optional): Only return constant (literal) fields (default: false) -- `case_sensitive` (optional): Case-sensitive matching (default: false) -- `use_regex` (optional): Treat pattern as regular expression (default: false) - -#### 9. `search_properties` -Search for properties in an assembly by name pattern. Useful for finding data model fields and configuration properties. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file -- `pattern` (required): Search pattern to match against property names -- `type_filter` (optional): Only search properties in types containing this string -- `namespace_filter` (optional): Only search in namespaces containing this string -- `case_sensitive` (optional): Case-sensitive matching (default: false) -- `use_regex` (optional): Treat pattern as regular expression (default: false) - -#### 10. `list_events` -List all events defined in an assembly. Useful for understanding event-driven architecture and observer patterns. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file -- `type_filter` (optional): Only list events in types containing this string -- `namespace_filter` (optional): Only list events in namespaces containing this string - -#### 11. `list_resources` -List all embedded resources in an assembly. Finds embedded files, images, localization data, etc. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file - -#### 12. `get_metadata_summary` -Get a comprehensive metadata summary with statistics. More accurate than `get_assembly_info` for metadata counts. - -**Parameters:** -- `assembly_path` (required): Path to the .NET assembly file - -Returns: Assembly identity, type/method/field/property/event/resource counts, and referenced assemblies. - -### Installation & Diagnostics Tools - -#### 13. `check_ilspy_installation` -Check if ilspycmd and dotnet CLI are installed and working. Use this to diagnose issues. - -**Parameters:** None - -Returns: Installation status with version information and troubleshooting tips. - -#### 14. `install_ilspy` -Install or update ilspycmd automatically. Detects your platform and package manager for optimal installation experience. - -**Parameters:** -- `update` (optional): If true, update to the latest version even if already installed (default: false) -- `install_dotnet_sdk` (optional): If true, attempt to install .NET SDK when missing (default: false). Supports automatic detection for: - - **Arch Linux**: `pacman` - - **Ubuntu/Debian**: `apt` - - **Fedora/RHEL**: `dnf` - - **openSUSE**: `zypper` - - **macOS**: `homebrew` - - **Windows**: `winget` or `chocolatey` - -**Example - Update ilspycmd:** -```json -{ - "name": "install_ilspy", - "arguments": { - "update": true - } -} -``` - -**Example - Full installation (SDK + ilspycmd):** -```json -{ - "name": "install_ilspy", - "arguments": { - "install_dotnet_sdk": true - } -} -``` - -### Available Prompts - -#### 1. `analyze_assembly` -Analyze a .NET assembly and provide insights about its structure. - -#### 2. `decompile_and_explain` -Decompile a specific type and provide explanation of its functionality. - -## Supported Assembly Types - -- .NET Framework assemblies (.dll, .exe) -- .NET Core/.NET 5+ assemblies -- Portable Executable (PE) files with .NET metadata - -## Supported C# Language Versions - -- CSharp1 through CSharp12_0 -- Preview -- Latest (default) - -## Quick Start - -1. **Install the package**: - ```bash - pip install mcilspy - ``` - -2. **Configure your MCP client** (Claude Desktop example): - ```json - { - "mcpServers": { - "ilspy": { - "command": "python", - "args": ["-m", "mcilspy.server"] - } - } - } - ``` - -3. **Use the tools** in your MCP client: - - Ask to decompile a .NET assembly - - List types in an assembly - - Generate interactive diagrams - - Get assembly information - -## Error Handling - -The server provides detailed error messages for common issues: -- Assembly file not found -- Invalid assembly format -- ILSpyCmd not installed or not in PATH -- Permission issues -- Decompilation failures +--- ## Configuration ### Environment Variables -- `LOGLEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR). Default: INFO +| Variable | Default | Description | +|----------|---------|-------------| +| `LOGLEVEL` | `INFO` | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` | -### MCP Client Examples +### Debug Mode -**Claude Desktop** (`config.json`): -```json -{ - "mcpServers": { - "ilspy": { - "command": "python", - "args": ["-m", "mcilspy.server"], - "env": { - "LOGLEVEL": "INFO" - } - } - } -} -``` - -**Development/Testing**: ```json { "mcpServers": { @@ -387,40 +406,59 @@ The server provides detailed error messages for common issues: } ``` +--- + ## Troubleshooting -### Common Issues +### "ilspycmd not found" -1. **"ILSpyCmd not found"**: - ```bash - dotnet tool install --global ilspycmd - ``` +Ask Claude to run the installation tool: +> *"Install ilspycmd for me"* -2. **"Assembly file not found"**: - - Check the file path is correct - - Ensure the file has .dll or .exe extension - -3. **Permission errors**: - - Ensure read access to assembly files - - Check output directory permissions - -### Debug Mode - -Enable debug logging to see detailed operation info: -```json -{ - "env": { - "LOGLEVEL": "DEBUG" - } -} +Or manually: +```bash +dotnet tool install --global ilspycmd +export PATH="$PATH:$HOME/.dotnet/tools" # Add to your shell profile ``` +### "dotnet not installed" + +The `install_ilspy` tool can install it automatically: +```json +{"install_dotnet_sdk": true} +``` + +Or install manually from [dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) + +### Assembly parsing errors + +Some obfuscated or corrupted assemblies may fail to parse. The dnfile-based tools (search_methods, search_fields, etc.) are more tolerant than full decompilation. + +--- + +## Supported Formats + +- .NET Framework assemblies (2.0 - 4.8) +- .NET Core / .NET 5-9+ assemblies +- Any PE file with .NET metadata + +**C# Language Versions:** CSharp1 through CSharp12, Preview, Latest + +--- + ## License -This project is licensed under the MIT License - see the LICENSE file for details. +MIT License — see [LICENSE](LICENSE) for details. ## Acknowledgments -- **Original project by [Borealin](https://github.com/Borealin/ilspy-mcp-server)** - Thank you for creating the foundation for this MCP server! -- Built on top of the excellent [ILSpy](https://github.com/icsharpcode/ILSpy) decompiler -- Uses the [Model Context Protocol](https://modelcontextprotocol.io/) for integration \ No newline at end of file +- **Original project by [Borealin](https://github.com/Borealin/ilspy-mcp-server)** — foundation for this MCP server +- **[ILSpy](https://github.com/icsharpcode/ILSpy)** — the excellent open-source .NET decompiler +- **[dnfile](https://github.com/malwarefrank/dnfile)** — Python library for .NET metadata parsing +- **[Model Context Protocol](https://modelcontextprotocol.io/)** — the integration standard + +--- + +

+ Built for security researchers, reverse engineers, and curious developers. +