MemScan-EDR/README_EN.md

# MemScan-EDR

> **Open-Source, Lightweight, Memory-Focused Windows Endpoint Detection & Response (EDR) Tool**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![.NET 8](https://img.shields.io/badge/.NET-8.0-purple.svg)](https://dotnet.microsoft.com/)
[![Platform: Windows](https://img.shields.io/badge/Platform-Windows%2010%2F11-lightgrey.svg)](https://www.microsoft.com/windows)
[![CS-WPF](https://img.shields.io/badge/UI-WPF-green.svg)](https://github.com/dotnet/wpf)

MemScan-EDR scans all running processes, inspects memory for shellcode/injection/C2 patterns, and uses AI (OpenAI / Claude / local models) to classify threats in real time. Built with C# WPF for zero-dependency deployment as a single `.exe`.

---

## TODO / Roadmap

| Priority | Status | Task | Assignee | Notes |
|:---:|:---:|---|---|---|
| 🔴 High | ⬜ Todo | YARA rule file loading & matching engine | | Parse `rules/*.yar` |
| 🔴 High | ⬜ Todo | TCP connection PID association | | `GetConnectionPid()` impl |
| 🔴 High | ⬜ Todo | Memory dump & PE structure analysis | | Export suspicious process memory |
| 🟡 Medium | ⬜ Todo | Audit log persistence (JSON/SQLite) | | Scan history query |
| 🟡 Medium | ⬜ Todo | PDF/HTML report export | | One-click from Dashboard |
| 🟡 Medium | ⬜ Todo | Scheduled scan (daily/hourly) | | Background timer |
| 🟡 Medium | ⬜ Todo | One-click terminate high-risk processes | | `TerminateProcess` P/Invoke |
| 🟡 Medium | ⬜ Todo | Hidden process detection (EPROCESS walk) | | Kernel-level via CE-MCP |
| 🟢 Low | ⬜ Todo | System tray minimize | | NotifyIcon + background |
| 🟢 Low | ⬜ Todo | Custom signature rule editor | | In-GUI YARA/sig editor |
| 🟢 Low | ⬜ Todo | Dark theme toggle | | White/Dark dual theme |
| ✅ Done | ✅ Done | Multi AI provider + pre-filter + anti-FP prompt | | v1.2 |
| ✅ Done | ✅ Done | CE-MCP auto-start subprocess management | | v1.1 |
| ✅ Done | ✅ Done | Chinese/English UI one-click toggle | | v1.1 |
| ✅ Done | ✅ Done | 12 built-in memory signature detections | | v1.0 |
| ✅ Done | ✅ Done | WPF white-theme modern UI | | v1.0 |

---

## Features

### Core Capabilities

| Capability | Description |
|---|---|
| **Process Enumeration** | Full process list with PID, name, path, parent tree, command line, digital signature, thread count, memory usage |
| **Memory Scanning** | `VirtualQueryEx` traversal of every committed region; detects RWX private memory, unbacked executable pages |
| **Signature Matching** | 12 built-in detection rules: NOP sled, CALL/POP EIP, ROR13 hash, CobaltStrike Beacon, Meterpreter, ReflectiveLoader, Mimikatz, etc. |
| **AI Threat Classification** | Multi-provider support (OpenAI-compatible / Claude / Ollama / LM Studio) + heuristic fallback engine |
| **CE-MCP Integration** | Auto-launch Cheat Engine MCP server for kernel-level memory operations |
| **Chinese / English UI** | One-click language toggle; all labels, buttons, and alerts switch instantly |
| **Single-File EXE** | `dotnet publish` produces a self-contained `MemScan-EDR.exe` — no .NET runtime needed on target |

### AI Providers

| Provider | Description | Base URL Example |
|---|---|---|
| **OpenAI-Compatible** | OpenAI / DeepSeek / Qwen / Zhipu / any OpenAI-format API | `https://api.openai.com/v1` |
| **Claude** | Anthropic Claude via Messages API | `https://api.anthropic.com` |
| **Local** | Ollama / LM Studio / vLLM / llama.cpp server | `http://127.0.0.1:11434` |
| **Heuristic** | Built-in rule engine (no API key needed) | N/A |

### Built-in Signatures

| Signature | Category | Severity |
|---|---|---|
| `SHELLCODE_NOP_SLED` | Shellcode | Medium |
| `SHELLCODE_GETEIP` | Shellcode | Medium |
| `SHELLCODE_ROR13` | Shellcode | Medium |
| `C2_COBALTSTRIKE` | C2 | High |
| `C2_METERPRETER` | C2 | Medium |
| `INJECTION_REFLECTIVE` | Injection | High |
| `INJECTION_CRT` | Injection | Medium |
| `INJECTION_VAE` | Injection | Medium |
| `MALWARE_MIMIKATZ` | Malware | High |
| `CRYPTO_MINER` | Crypto | High |
| `RANSOM_NOTE` | Malware | High |
| `PS_DOWNLOAD` | Malware | Medium |

---

## Architecture

```
TitleBar ── Window Chrome (Min/Max/Close, Language Toggle)
Sidebar ── Navigation (Dashboard / Processes / Scan / Settings)
Content ── 4 Views (WPF Grid Visibility switching)

Services:
  ProcessCollector ── CreateToolhelp32Snapshot + WMI → ProcessInfo[]
  MemoryScanner    ── VirtualQueryEx + signature walk  → SignatureMatch[]
  AIAnalyzer       ── HTTP → OpenAI/Claude/Ollama API  → ScanResult
  CeMcpManager     ── Process.Start → python server.py
```

Data flow:
```
[Start Scan] → ProcessCollector.CollectAll()
    → for each ProcessInfo:
        → MemoryScanner.ScanProcess() → signature matches
        → MemoryScanner.GetSuspiciousRegions() → RWX private regions
        → QuickPreScore() — skip API if score < 0.05
        → AIAnalyzer.AnalyzeProcessAsync() → ScanResult
    → Update DataGrid / Stats in real-time via IProgress<>
```

---

## Quick Start

### Prerequisites

- Windows 10 / 11 (x64)
- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
- Administrator privileges (for memory scanning)

### Build

```powershell
git clone https://github.com/Huang-158/MemScan-EDR.git
cd MemScan-EDR\src-csharp

dotnet build MemScanEDR.sln

dotnet publish MemScanEDR\MemScanEDR.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o publish

.\publish\MemScan-EDR.exe
```

Or:

```powershell
.\scripts\build_csharp.bat
```

### CE-MCP Setup (Optional)

1. Place [ce-mcp-server](https://github.com/Huang-158/ce-mcp-server) next to the project
2. Or configure the path in Settings → CE-MCP Server Path
3. Set to `disabled` to run without CE-MCP

### AI Configuration

1. Select provider: Heuristic / OpenAI-Compatible / Claude / Local
2. Enter API Base URL
3. Enter API Key (stored locally)
4. Enter Model name
5. Click Save

---

## How AI Analysis Works

1. **Pre-filter**: Clean processes (signed, system path, no RWX, no sig matches) → `Safe`, skip API
2. **Structured Prompt**: Each process gets metadata, connections, signatures, suspicious regions
3. **Safe-by-Default**: AI told >95% are benign; needs multiple concurring indicators
4. **Heuristic Fallback**: Conservative thresholds (≥0.50 suspicious, ≥0.75 high) when API is down

---

## Project Structure

```
MemScan-EDR/
├── src-csharp/
│   ├── MemScanEDR.sln
│   └── MemScanEDR/
│       ├── MemScanEDR.csproj
│       ├── App.xaml / App.xaml.cs
│       ├── MainWindow.xaml / MainWindow.xaml.cs
│       ├── Models/
│       │   ├── ProcessInfo.cs
│       │   ├── AIConfig.cs
│       │   └── AppSettings.cs
│       └── Services/
│           ├── ProcessCollector.cs
│           ├── MemoryScanner.cs
│           ├── AIAnalyzer.cs
│           └── CeMcpManager.cs
├── rules/
│   ├── shellcode.yar
│   ├── injection.yar
│   └── malware_strings.yar
├── scripts/
│   └── build_csharp.bat
├── LICENSE
├── README.md       # Language switch entry
├── README_CN.md    # 中文文档
└── README_EN.md    # English docs (current)
```

---

## Disclaimer

> This project is not affiliated with Cheat Engine, Dark Byte, or any AI provider (OpenAI, Anthropic, etc.).
>
> This tool is intended for **legitimate security research, education, and authorized security assessments only**. Unauthorized use is illegal. Users are responsible for complying with all applicable laws.

---

## License

MIT License — see [LICENSE](LICENSE).