diff --git a/README.md b/README.md index 99749d3..0df90c6 100644 --- a/README.md +++ b/README.md @@ -1,323 +1,353 @@ # MalwareAnalysisTool -> [!WARNING] -> IN DEVELOPMENT. PLEASE DO NOT ATTEMPT TO USE IT ON UNKNOWN FILES OUTSIDE AN ISOLATED ENVIRONMENT. +> 🚨 **WARNING / DΔ°KKAT** +> +> This tool is intended for educational malware analysis and defensive security research only. +> Use dynamic analysis **only inside an isolated Windows virtual machine**. Do not run suspicious files on your main system. +> +> Bu araΓ§ eğitim, zararlΔ± yazΔ±lΔ±m analizi ve savunma amaΓ§lΔ± gΓΌvenlik araştΔ±rmalarΔ± iΓ§in geliştirilmiştir. +> Dinamik analiz modunu **sadece izole edilmiş Windows sanal makinesinde** kullanΔ±n. Şüpheli dosyalarΔ± ana sisteminizde Γ§alıştΔ±rmayΔ±n. -MalwareAnalysisTool is a C++17-based Windows security tool for static and experimental dynamic analysis of PE (Portable Executable) files. +MalwareAnalysisTool is a Windows-focused malware analysis project that combines a C++ PE analysis engine with a modern Tauri desktop GUI. -The project currently provides a command-line interface. +The project supports static PE analysis, experimental dynamic analysis, TXT/JSON report generation, risk scoring, SHA-256 hashing, suspicious API detection, suspicious DLL summaries, section entropy analysis, and a Matrix-themed desktop interface. -Static analysis inspects PE metadata without executing the target file. - -Dynamic analysis launches the target executable under the Windows debugging API and must only be used in an isolated Windows virtual machine. +The main goal of this project is to provide a lightweight malware analysis workflow for learning, triage, and defensive research. --- -## Features +## GUI Preview -### Static Analysis +![MalwareAnalysisTool GUI 1](assets/1.png) -* DOS header validation -* PE signature validation -* 32-bit and 64-bit PE detection -* Section table parsing -* Section-based Shannon entropy calculation -* Section risk classification -* Imported DLL listing -* Imported API function listing -* Suspicious API detection -* Suspicious API category classification -* Suspicious API severity classification -* Suspicious DLL summary -* Static category summary -* Static severity summary -* Overall static risk score -* Overall static risk level -* TXT static report export -* JSON static report export -* Custom report output directory support - -### Experimental Dynamic Analysis - -* Launching a target executable with the Windows debugging API -* Debug event loop handling -* Experimental breakpoint-based API monitoring -* Captured dynamic event logging -* Dynamic analysis timeout option -* Dynamic analysis duration reporting -* TXT dynamic report export -* JSON dynamic report export -* Custom report output directory support +![MalwareAnalysisTool GUI 2](assets/2.png) ---- +![MalwareAnalysisTool GUI 3](assets/3.png) -## Safety Warning +--- -Dynamic analysis executes the selected file. +## Main Features -Do not run unknown or suspicious executables on a personal computer. +### Static Analysis -Use dynamic mode only inside an isolated Windows virtual machine with: +Static analysis inspects PE files without executing the target file. -* A clean snapshot -* No personal accounts -* No personal files -* Controlled or disabled network access -* No shared clipboard -* No shared folders unless required +It can extract and report: -Static analysis does not execute the selected file. +* DOS header validation +* PE header validation +* Section information +* Section entropy values +* Section risk levels +* Imported DLLs +* Imported APIs +* Suspicious API usage +* Suspicious API categories +* Suspicious API severity levels +* Suspicious DLL summary +* Target file size +* SHA-256 hash +* Static risk score +* Static risk level +* TXT and JSON reports -Dynamic analysis is experimental and must be treated as unsafe for real malware outside a controlled lab. +Static mode is safer because it does not execute the analyzed file. --- -## Requirements +### Dynamic Analysis -| Tool | Minimum Requirement | -| ----------------- | ------------------- | -| Windows | Required | -| CMake | 3.15 or newer | -| MSVC or MinGW-w64 | C++17 support | -| Git | Any recent version | +Dynamic analysis executes the target file using Windows debugging APIs. ---- +It can capture runtime-related events such as: -## Compilation +* Process-related events +* File-related events +* Captured API activity +* Event timestamps +* Event IDs +* Analysis duration +* Timeout status -Clone the repository: +Dynamic analysis is experimental. -```bash -git clone https://github.com/Bor-Code/MalwareAnalysisTool.git -cd MalwareAnalysisTool -``` +Use this mode only inside an isolated Windows virtual machine. -Configure the build: +--- -```bash -cmake -B build -DCMAKE_BUILD_TYPE=Release -``` +### Desktop GUI -Build the project: +The project includes a modern Tauri-based desktop GUI. -```bash -cmake --build build --config Release -``` +The GUI provides: -The executable is generated inside the `build` directory. +* Static analysis mode +* Dynamic analysis mode +* Native file selection +* TR/EN language switching +* Matrix-themed interface +* Clean / suspicious / high-risk verdict display +* Risk score display +* Risk level display +* SHA-256 display +* File size display +* TXT/JSON report preview +* Dynamic mode timeout input +* Validation for dynamic analysis file type + +The GUI uses the existing `pe_analyzer.exe` analysis engine in the background. -With Visual Studio generators, the executable is usually created here: +--- + +## Project Structure ```text -build\Release\pe_analyzer.exe +MalwareAnalysisTool/ +β”œβ”€β”€ include/ +β”‚ └── analyzer/ +β”‚ β”œβ”€β”€ pe_parser.hpp +β”‚ └── dynamic_analyzer.hpp +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ main.cpp +β”‚ β”œβ”€β”€ pe_parser.cpp +β”‚ └── dynamic_analyzer.cpp +β”œβ”€β”€ gui/ +β”‚ β”œβ”€β”€ src/ +β”‚ β”‚ β”œβ”€β”€ main.ts +β”‚ β”‚ └── styles.css +β”‚ └── src-tauri/ +β”‚ β”œβ”€β”€ src/ +β”‚ β”‚ └── lib.rs +β”‚ β”œβ”€β”€ capabilities/ +β”‚ └── tauri.conf.json +β”œβ”€β”€ assets/ +β”‚ β”œβ”€β”€ 1.png +β”‚ β”œβ”€β”€ 2.png +β”‚ └── 3.png +β”œβ”€β”€ CMakeLists.txt +β”œβ”€β”€ README.md +└── LICENSE ``` --- -## Usage +## Requirements -### Static Analysis +### CLI Requirements -```bash -pe_analyzer.exe -static -``` +* Windows +* CMake +* C++17 compatible compiler +* Visual Studio Build Tools or Visual Studio Community -Example: - -```bash -pe_analyzer.exe -static C:\samples\example.exe -``` +### GUI Requirements -Static analysis does not execute the target file. +* Node.js +* npm +* Rust +* Cargo +* Tauri dependencies for Windows +* WebView2 Runtime --- -### Static Analysis With Custom Output Directory - -```bash -pe_analyzer.exe -static -out -``` +## Build CLI -Example: +From the project root: -```bash -pe_analyzer.exe -static C:\samples\example.exe -out reports +```powershell +cmake -B build +cmake --build build --config Release ``` -This creates the static analysis reports inside the selected output directory. - -Generated files: +The CLI executable will be generated at: ```text -reports\static_analysis_report.txt -reports\static_analysis_report.json +build/Release/pe_analyzer.exe ``` --- -### Dynamic Analysis +## CLI Usage -```bash -pe_analyzer.exe -dynamic +### Help + +```powershell +.\build\Release\pe_analyzer.exe -help ``` -Example: +You can also use: -```bash -pe_analyzer.exe -dynamic C:\samples\example.exe +```powershell +.\build\Release\pe_analyzer.exe --help +.\build\Release\pe_analyzer.exe -h ``` -Use dynamic analysis only inside an isolated Windows virtual machine. - --- -### Dynamic Analysis With Timeout +### Static Analysis -```bash -pe_analyzer.exe -dynamic -timeout +```powershell +.\build\Release\pe_analyzer.exe -static C:\Windows\System32\notepad.exe ``` -Example: +With a custom output directory: -```bash -pe_analyzer.exe -dynamic C:\samples\example.exe -timeout 60 +```powershell +.\build\Release\pe_analyzer.exe -static C:\Windows\System32\notepad.exe -out reports ``` -The timeout value limits how long the dynamic analysis session can run. +Static analysis does not execute the target file. --- -### Dynamic Analysis With Custom Output Directory +### Dynamic Analysis -```bash -pe_analyzer.exe -dynamic -out +```powershell +.\build\Release\pe_analyzer.exe -dynamic C:\Windows\System32\notepad.exe ``` -Example: +With timeout: -```bash -pe_analyzer.exe -dynamic C:\samples\example.exe -out reports +```powershell +.\build\Release\pe_analyzer.exe -dynamic C:\Windows\System32\notepad.exe -timeout 30 ``` -Generated files: +With timeout and custom output directory: -```text -reports\dynamic_analysis_report.txt -reports\dynamic_analysis_report.json +```powershell +.\build\Release\pe_analyzer.exe -dynamic C:\Windows\System32\notepad.exe -timeout 30 -out reports ``` ---- +Dynamic analysis executes the target file. -### Combined Dynamic Options +Use it only inside an isolated Windows VM. -```bash -pe_analyzer.exe -dynamic -timeout -out -``` +--- -Example: +## Run GUI -```bash -pe_analyzer.exe -dynamic C:\samples\example.exe -timeout 60 -out reports +From the project root: + +```powershell +cd gui +npm install +npm run tauri dev ``` ---- +To build the GUI: -## Static Report Output +```powershell +cd gui +npm run build +npm run tauri build +``` -Static analysis creates both TXT and JSON reports. +The GUI uses the C++ CLI engine in the background. -## Static File Metadata +Before running GUI analysis, make sure the CLI has been built: -Static analysis reports include file metadata that helps identify the analyzed target and compare results across different analysis runs. +```powershell +cmake -B build +cmake --build build --config Release +``` -TXT reports include: +--- -```text -Target File Size: 360448 bytes -SHA-256: ab15a95de88ab0624307ae0e28e333756a2a522f650... +## Report Output -### TXT Report +### Static Analysis Reports -The TXT report includes: +Static analysis generates: -* Target file path -* Generated time -* Architecture -* Section count -* Section details -* Section entropy values -* Section risk levels -* Section risk summary -* Imported DLLs -* Imported API functions -* Suspicious APIs -* Suspicious DLL summary -* Category summary -* Severity summary -* Overall static risk score -* Overall static risk level -* General summary +```text +static_analysis_report.txt +static_analysis_report.json +``` -Example TXT section: +When using `-out reports`, the files are generated under: ```text -Overall Risk -Risk Score: 39 -Risk Level: Medium +reports/ +β”œβ”€β”€ static_analysis_report.txt +└── static_analysis_report.json ``` ---- +Example JSON metadata: -### JSON Report - -The JSON report includes structured output for automation and external tooling. +```json +{ + "targetFileSize": 360448, + "sha256": "ab15a95de88ab0624307ae0e28e333756a2a522f650a0be78749901f7dc32ecf" +} +``` -Main JSON fields: +Example risk summary: ```json { - "target": "C:\\Windows\\System32\\notepad.exe", - "generatedAt": "01:11:50", - "architecture": "64-bit", - "sectionCount": 8, - "sections": [], - "imports": [], - "suspiciousApis": [], - "summary": {} + "summary": { + "risk": { + "score": 39, + "level": "Medium" + } + } } ``` --- -## Static Risk Score +### Dynamic Analysis Reports -Static analysis calculates an overall risk score by combining suspicious API severity levels and section entropy risk levels. +Dynamic analysis generates: -The score is heuristic and does not prove that a file is malicious. +```text +dynamic_analysis_report.txt +dynamic_analysis_report.json +``` + +When using `-out reports`, the files are generated under: + +```text +reports/ +β”œβ”€β”€ dynamic_analysis_report.txt +└── dynamic_analysis_report.json +``` + +Dynamic reports can include captured runtime events such as: -It is used to prioritize files that may need deeper manual review. +* Event ID +* Timestamp +* API name +* Captured event count +* Timeout status +* Analysis duration + +--- -### Risk Score Rules +## Static Risk Score -| Finding | Score | -| ------------------------------ | ----- | -| High severity suspicious API | +5 | -| Medium severity suspicious API | +2 | -| Low severity suspicious API | +1 | -| High section risk | +3 | -| Medium section risk | +1 | +The static risk score is calculated using suspicious API severity and section risk indicators. -The final score is capped at 100. +| Indicator | Score | +| ------------------------------ | ----: | +| High severity suspicious API | +5 | +| Medium severity suspicious API | +2 | +| Low severity suspicious API | +1 | +| High section risk | +3 | +| Medium section risk | +1 | -### Risk Levels +The score is capped at 100. + +Risk levels: | Score Range | Risk Level | -| ----------- | ---------- | -| 0 - 19 | Low | -| 20 - 49 | Medium | -| 50 - 100 | High | +| ----------: | ---------- | +| 0-19 | Low | +| 20-49 | Medium | +| 50+ | High | -### TXT Example +Example: ```text Overall Risk @@ -325,84 +355,40 @@ Risk Score: 39 Risk Level: Medium ``` -### JSON Example - -```json -"risk": { - "score": 39, - "level": "Medium" -} -``` - --- ## Suspicious API Detection -The static analyzer flags imported APIs that may be interesting during malware analysis. +The static analyzer checks imported APIs and classifies suspicious functions by category and severity. -Flagged APIs are grouped by: +Example categories include: -* API name -* DLL name -* Category -* Severity +* File activity +* Registry activity +* Process activity +* Memory activity +* Network activity +* Service activity +* Anti-analysis related activity -Example JSON entry: +Example JSON output: ```json { "api": "CreateFileW", "dll": "api-ms-win-core-file-l1-1-0.dll", - "category": "Dosya", + "category": "File", "severity": "Medium" } ``` -Suspicious API findings are not proof of malware by themselves. - -They only indicate that the file imports APIs that may require manual review. - ---- - -## Suspicious API Categories - -The analyzer currently groups suspicious APIs into categories such as: - -| Category | Meaning | -| -------------- | ----------------------------------- | -| Dosya | File operations | -| Surec | Process operations | -| Bellek | Memory operations | -| Ag | Network operations | -| Kayit Defteri | Registry operations | -| Servis | Service operations | -| Analiz Tespiti | Anti-analysis or debugger detection | - ---- - -## Suspicious API Severity - -Suspicious APIs are classified by severity. - -| Severity | Meaning | -| -------- | -------------------------------------- | -| Low | Interesting but weak signal | -| Medium | Requires manual review | -| High | Stronger suspicious behavior indicator | - -A high severity API does not automatically mean the file is malicious. - -Context matters. - --- ## Suspicious DLL Summary -Static reports include a suspicious DLL summary that groups flagged suspicious API findings by the DLL they were imported from. - -This helps identify which imported libraries contain the highest number of APIs that may need manual review. +The analyzer also summarizes suspicious DLL usage. -### TXT Example +Example TXT output: ```text Suspicious DLL Summary @@ -411,192 +397,91 @@ api-ms-win-core-registry-l1-1-0.dll: 3 api-ms-win-core-processthreads-l1-1-0.dll: 2 ``` -### JSON Example +Example JSON output: ```json -"suspiciousDlls": { - "api-ms-win-core-file-l1-1-0.dll": 5, - "api-ms-win-core-registry-l1-1-0.dll": 3, - "api-ms-win-core-processthreads-l1-1-0.dll": 2 +{ + "suspiciousDlls": { + "api-ms-win-core-file-l1-1-0.dll": 5, + "api-ms-win-core-registry-l1-1-0.dll": 3, + "api-ms-win-core-processthreads-l1-1-0.dll": 2 + } } ``` --- -## Section Entropy Analysis - -Static analysis calculates Shannon entropy for each PE section. - -Entropy can help identify packed, compressed, or encrypted content. - -| Entropy Range | Section Risk | -| ------------- | ------------ | -| 0.00 - 6.00 | Low | -| 6.01 - 7.00 | Medium | -| 7.01 - 8.00 | High | - -Entropy alone is not proof of malicious behavior. - -Some legitimate binaries may contain high-entropy sections. - ---- +## SHA-256 and File Metadata -## Dynamic Report Output +Static reports include file metadata for identification and comparison. -Dynamic analysis creates dynamic report files when executed. - -Generated files: - -```text -dynamic_analysis_report.txt -dynamic_analysis_report.json -``` - -With custom output directory: +TXT reports include: ```text -reports\dynamic_analysis_report.txt -reports\dynamic_analysis_report.json -``` - -Dynamic reports may include: - -* Target file path -* Generated time -* Runtime duration -* Timeout value -* Captured dynamic events -* API event names -* Event IDs -* Event timestamps - -Dynamic analysis is experimental. - ---- - -## Example Workflow - -Build the project: - -```bash -cmake -B build -cmake --build build --config Release -``` - -Run static analysis: - -```bash -.\build\Release\pe_analyzer.exe -static C:\Windows\System32\notepad.exe -out reports +Target File Size: 360448 bytes +SHA-256: ab15a95de88ab0624307ae0e28e333756a2a522f650a0be78749901f7dc32ecf ``` -Check generated reports: +JSON reports include: -```bash -notepad reports\static_analysis_report.txt -notepad reports\static_analysis_report.json +```json +{ + "targetFileSize": 360448, + "sha256": "ab15a95de88ab0624307ae0e28e333756a2a522f650a0be78749901f7dc32ecf" +} ``` -Run dynamic analysis in a VM: - -```bash -.\build\Release\pe_analyzer.exe -dynamic C:\samples\example.exe -timeout 60 -out reports -``` +This helps identify analyzed files even if the file name changes. --- -## Project Structure +## Safety Notes -```text -MalwareAnalysisTool/ -β”œβ”€β”€ include/ -β”‚ └── analyzer/ -β”‚ β”œβ”€β”€ pe_parser.hpp -β”‚ β”œβ”€β”€ dynamic_analyzer.hpp -β”‚ └── utils.hpp -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ main.cpp -β”‚ β”œβ”€β”€ pe_parser.cpp -β”‚ └── dynamic_analyzer.cpp -β”œβ”€β”€ CMakeLists.txt -β”œβ”€β”€ LICENSE -└── README.md -``` +* Static analysis does not execute the target file. +* Dynamic analysis executes the target file. +* Dynamic mode should only be used inside an isolated Windows VM. +* Do not run unknown or suspicious files on your main system. +* This project is for educational and defensive research purposes. +* This is not a replacement for professional malware sandboxing solutions. --- ## Current Limitations * Dynamic analysis is experimental. -* Dynamic analysis executes the selected file. -* Dynamic monitoring currently focuses on an early Windows debugging API prototype. -* Network monitoring is not implemented. -* Behavioral classification is limited. -* Static analysis results are heuristic. -* Suspicious API findings are not proof of malware. -* Entropy findings are not proof of packing or encryption. -* The command-line interface is the active application entry point. -* GUI support is not currently available. +* Dynamic mode is Windows-only. +* DLL files should be analyzed with static mode. +* Dynamic mode is intended for executable files. +* API capture coverage is limited to implemented hooks. +* The tool does not perform full behavioral sandboxing. +* The tool does not replace antivirus or EDR products. --- ## Roadmap -* Improve parser boundary validation for malformed PE files -* Improve static import analysis -* Expand suspicious API database -* Add more suspicious API categories -* Improve static risk scoring -* Add richer JSON metadata -* Improve dynamic hook address resolution -* Restore breakpoints reliably after each captured event -* Add more dynamic event types -* Add automated build checks -* Add unit tests for parser helpers -* Reintroduce a GUI after the analysis core is stable - ---- - -## Development Notes - -Generated report files should not be committed. +Possible future improvements: -Examples of generated files: - -```text -static_analysis_report.txt -static_analysis_report.json -dynamic_analysis_report.txt -dynamic_analysis_report.json -reports/ -build/ -``` - -Only source files, headers, build configuration files, documentation, and project metadata should be committed. +* Open TXT/JSON report buttons in GUI +* Export GUI results as PDF +* More suspicious API categories +* More detailed process behavior tracking +* Network behavior summary +* Registry behavior summary +* YARA rule support +* Hash database lookup +* Improved dynamic analysis stability +* Better report visualization in GUI +* Installer support for GUI builds --- -## Desktop GUI - -MalwareAnalysisTool includes a Tauri-based desktop GUI. - -The GUI provides: - -- Static and dynamic analysis modes -- Native file selection -- TR/EN language switching -- Matrix-themed interface -- Verdict display -- Risk score and risk level -- SHA-256 and file size display -- TXT/JSON report preview +## License -To run the GUI in development mode: +This project is released under the MIT License. -```powershell -cd gui -npm install -npm run tauri dev +--- -## License +## AI Assistance Notice -MIT β€” see the `LICENSE` file for details. +This project was developed with AI-assisted guidance for planning, code organization, documentation, debugging, UI iteration, and technical explanations. diff --git a/assets/1.png b/assets/1.png new file mode 100644 index 0000000..0bfd001 Binary files /dev/null and b/assets/1.png differ diff --git a/assets/2.png b/assets/2.png new file mode 100644 index 0000000..1d66a3a Binary files /dev/null and b/assets/2.png differ diff --git a/assets/3.png b/assets/3.png new file mode 100644 index 0000000..3cfc6e7 Binary files /dev/null and b/assets/3.png differ