diff --git a/README.md b/README.md index b51665b..6ab812d 100644 --- a/README.md +++ b/README.md @@ -1,559 +1,570 @@ # MalwareAnalysisTool > [!WARNING] -> IN DEVELOPMENT. PLEASE DO NOT ATTEMPT TO USE IT ON REAL MALWARE OUTSIDE AN ISOLATED LAB ENVIRONMENT. +> IN DEVELOPMENT. PLEASE DO NOT ATTEMPT TO USE IT ON UNKNOWN FILES OUTSIDE AN ISOLATED ENVIRONMENT. -MalwareAnalysisTool is a C++17-based Windows security tool developed for performing static and experimental dynamic analysis on PE files. +MalwareAnalysisTool is a C++17-based Windows security tool for static and experimental dynamic analysis of PE (Portable Executable) files. -The project currently operates through a command-line interface. Static analysis examines PE metadata without running the target file. Dynamic analysis launches the target executable under the Windows Debugging API and must only be used inside isolated, secure virtual machine environments. +The project currently provides a command-line 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. + +--- ## Features ### Static Analysis -* DOS header verification -* PE signature verification +* DOS header validation +* PE signature validation * 32-bit and 64-bit PE detection * Section table parsing * Section-based Shannon entropy calculation -* Entropy-based section risk levels -* High entropy alerts for packed or encrypted content -* Section risk summary output +* Section risk classification * Imported DLL listing * Imported API function listing -* PE32 and PE32+ thunk parsing -* Ordinal import support -* Boundary validation for corrupted or malformed PE files -* Suspicious API classification by category -* Suspicious API severity levels -* Suspicious API category summary output -* Suspicious API severity summary output -* Static analysis summary showing total and flagged API function counts -* Static analysis TXT report output -* Static analysis JSON report output - -### Static Risk Score - -Static analysis calculates an overall risk score by combining suspicious API severity levels and section entropy risk levels. - -The score is heuristic and does not prove that a file is malicious. It is used to prioritize files that may need deeper manual review. +* 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 -Risk levels: - -| Score Range | Risk Level | -| ----------- | ---------- | -| 0 - 19 | Low | -| 20 - 49 | Medium | -| 50 - 100 | High | +### Experimental Dynamic Analysis -TXT reports include: +* 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 -```text -Overall Risk -Risk Score: 39 -Risk Level: Medium +--- -### Experimental Dynamic Analysis +## Safety Warning -* Starts the target executable with the Windows Debugging API -* Processes debug events -* Resolves target process hook addresses from DLL load events -* Restores breakpoints after captured events -* Captures recurring events with single-step execution -* Stores time-stamped dynamic event records -* Tracks API-based event counters -* Generates dynamic analysis summaries -* Exports TXT reports -* Exports JSON reports -* Uses a default 30-second timeout to avoid infinite waiting -* Supports configurable timeout values from the command line -* Tracks elapsed dynamic analysis duration +Dynamic analysis executes the selected file. -The current dynamic analysis prototype monitors these API calls: +Do not run unknown or suspicious executables on a personal computer. -* `NtCreateFile` -* `NtWriteFile` -* `NtOpenProcess` -* `NtTerminateProcess` +Use dynamic mode only inside an isolated Windows virtual machine with: -## Security Warning +* A clean snapshot +* No personal accounts +* No personal files +* Controlled or disabled network access +* No shared clipboard +* No shared folders unless required -Dynamic analysis runs the selected file. +Static analysis does not execute the selected file. -Do not run unknown or suspicious executable files on your personal computer. Use dynamic mode only inside a Windows virtual machine with a snapshot, isolated filesystem, and controlled network configuration. +Dynamic analysis is experimental and must be treated as unsafe for real malware outside a controlled lab. -Static analysis does not run the target file. +--- ## Requirements | Tool | Minimum Requirement | | ----------------- | ------------------- | -| CMake | 3.15 | -| MSVC or MinGW-w64 | C++17 support | -| Git | Any current version | | Windows | Required | +| CMake | 3.15 or newer | +| MSVC or MinGW-w64 | C++17 support | +| Git | Any recent version | + +--- ## Compilation +Clone the repository: + ```bash git clone https://github.com/Bor-Code/MalwareAnalysisTool.git cd MalwareAnalysisTool -cmake -B build +``` + +Configure the build: + +```bash +cmake -B build -DCMAKE_BUILD_TYPE=Release +``` + +Build the project: + +```bash cmake --build build --config Release ``` -The executable file is created inside the `build` folder. The exact output path may vary depending on the selected CMake generator and build configuration. +The executable is generated inside the `build` directory. -When using the Visual Studio generator, the executable file is typically generated at: +With Visual Studio generators, the executable is usually created here: ```text build\Release\pe_analyzer.exe ``` +--- + ## Usage -General usage format: +### Static Analysis + +```bash +pe_analyzer.exe -static +``` + +Example: ```bash -pe_analyzer.exe [-out ] +pe_analyzer.exe -static C:\samples\example.exe ``` -Available modes and options: +Static analysis does not execute the target file. -```text --static --dynamic --timeout --out --help ---help --h +--- + +### Static Analysis With Custom Output Directory + +```bash +pe_analyzer.exe -static -out ``` -### Help Screen +Example: ```bash -pe_analyzer.exe -help -pe_analyzer.exe --help -pe_analyzer.exe -h +pe_analyzer.exe -static C:\samples\example.exe -out reports ``` -The help command displays the available modes, expected arguments, timeout option, and dynamic analysis security warning. +This creates the static analysis reports inside the selected output directory. -## Static Analysis +Generated files: + +```text +reports\static_analysis_report.txt +reports\static_analysis_report.json +``` + +--- + +### Dynamic Analysis ```bash -pe_analyzer.exe -static +pe_analyzer.exe -dynamic ``` Example: ```bash -pe_analyzer.exe -static C:\samples\example.exe +pe_analyzer.exe -dynamic C:\samples\example.exe ``` -When running from the project root after a Visual Studio Release build, use: +Use dynamic analysis only inside an isolated Windows virtual machine. -```powershell -.\build\Release\pe_analyzer.exe -static C:\Windows\System32\notepad.exe +--- + +### Dynamic Analysis With Timeout + +```bash +pe_analyzer.exe -dynamic -timeout ``` -The static analysis output includes: +Example: -* PE architecture -* Section information -* Section entropy values -* Section risk levels -* Imported DLL names -* Imported API function names -* Suspicious API categories -* Suspicious API severity levels -* Section risk summary counters -* Suspicious API category summary counters -* Suspicious API severity summary counters -* Static API summary counters -* Static TXT report output -* Static JSON report output +```bash +pe_analyzer.exe -dynamic C:\samples\example.exe -timeout 60 +``` -A flagged API function does not definitively prove that the file is malicious. It only indicates that the corresponding function may require additional review. +The timeout value limits how long the dynamic analysis session can run. -Static analysis does not accept dynamic-only options such as `-timeout`. +--- + +### Dynamic Analysis With Custom Output Directory + +```bash +pe_analyzer.exe -dynamic -out +``` + +Example: + +```bash +pe_analyzer.exe -dynamic C:\samples\example.exe -out reports +``` -### Section Risk Levels +Generated files: -Section risk levels are based on Shannon entropy values: +```text +reports\dynamic_analysis_report.txt +reports\dynamic_analysis_report.json +``` -| Entropy Range | Risk | -| ------------- | ------ | -| `<= 6.00` | Low | -| `> 6.00` | Medium | -| `> 7.00` | High | +--- -High entropy sections may indicate packed, encrypted, compressed, or otherwise unusual content. This is not proof of malware by itself. +### Combined Dynamic Options -### Suspicious API Severity Levels +```bash +pe_analyzer.exe -dynamic -timeout -out +``` -Suspicious API findings include both a category and a severity level. +Example: -Example categories: +```bash +pe_analyzer.exe -dynamic C:\samples\example.exe -timeout 60 -out reports +``` -* File -* Process -* Memory -* Network -* Registry -* Service -* Analysis detection +--- -Example severity levels: +## Static Report Output -| Severity | Meaning | -| -------- | ------------------------------------------ | -| Low | Usually informational or context-dependent | -| Medium | Worth reviewing during static analysis | -| High | Stronger suspicious behavior indicator | +Static analysis creates both TXT and JSON reports. -Severity values are heuristic labels. They are intended to help prioritize review, not to make a final malware verdict. +### TXT Report -### Static Report Files +The TXT report includes: -After static analysis completes, the tool creates the following files: +* 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 + +Example TXT section: ```text -static_analysis_report.txt -static_analysis_report.json +Overall Risk +Risk Score: 39 +Risk Level: Medium ``` -### Sample Static TXT Report +--- -```text -Static Analysis Report -Target: C:\Windows\System32\notepad.exe -Generated At: 20:10:12 -Architecture: 64-bit -Section Count: 8 - -Sections -Name: .text -Virtual Size: 157666 -Raw Size: 159744 -Entropy: 6.24 -Risk: Medium - -Name: .rsrc -Virtual Size: 123344 -Raw Size: 126976 -Entropy: 6.97 -Risk: Medium - -Section Risk Summary -Low: 6 -Medium: 2 - -Suspicious APIs -CreateProcessW | Category: Surec | Severity: Medium -TerminateProcess | Category: Surec | Severity: High -IsDebuggerPresent | Category: Analiz Tespiti | Severity: Low -CreateFileW | Category: Dosya | Severity: Medium -DeleteFileW | Category: Dosya | Severity: High - -Category Summary -Analiz Tespiti: 1 -Dosya: 2 -Surec: 2 - -Severity Summary -High: 2 -Low: 1 -Medium: 2 - -Summary -Total Imported APIs: 315 -Flagged APIs: 13 -Note: Flagged API functions are not proof of malware by themselves. -``` - -### Sample Static JSON Report +### JSON Report + +The JSON report includes structured output for automation and external tooling. + +Main JSON fields: ```json { "target": "C:\\Windows\\System32\\notepad.exe", - "generatedAt": "20:10:12", + "generatedAt": "01:11:50", "architecture": "64-bit", "sectionCount": 8, - "sections": [ - { - "name": ".text", - "virtualSize": 157666, - "rawSize": 159744, - "entropy": 6.24, - "risk": "Medium" - }, - { - "name": ".rsrc", - "virtualSize": 123344, - "rawSize": 126976, - "entropy": 6.97, - "risk": "Medium" - } - ], - "imports": [ - { - "dll": "KERNEL32.dll", - "functions": [ - "CreateFileW", - "ReadFile" - ] - } - ], - "suspiciousApis": [ - { - "api": "CreateFileW", - "category": "Dosya", - "severity": "Medium" - }, - { - "api": "TerminateProcess", - "category": "Surec", - "severity": "High" - } - ], - "summary": { - "totalImportedApis": 315, - "flaggedApis": 13, - "sectionRisks": { - "Low": 6, - "Medium": 2 - }, - "categories": { - "Dosya": 5, - "Surec": 2, - "Bellek": 2, - "Kayit Defteri": 3, - "Analiz Tespiti": 1 - }, - "severities": { - "High": 4, - "Low": 1, - "Medium": 8 - } - } + "sections": [], + "imports": [], + "suspiciousApis": [], + "summary": {} } ``` -## Report Output Directory -The `-out ` option writes generated report files into a selected directory. The directory is created automatically when needed. +--- -Static example: +## Static Risk Score -```powershell -.\build\Release\pe_analyzer.exe -static C:\Windows\System32\notepad.exe -out reports +Static analysis calculates an overall risk score by combining suspicious API severity levels and section entropy risk levels. -## Dynamic Analysis +The score is heuristic and does not prove that a file is malicious. -```bash -pe_analyzer.exe -dynamic -``` +It is used to prioritize files that may need deeper manual review. -Example: +### Risk Score Rules -```bash -pe_analyzer.exe -dynamic C:\samples\example.exe +| 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 final score is capped at 100. + +### Risk Levels + +| Score Range | Risk Level | +| ----------- | ---------- | +| 0 - 19 | Low | +| 20 - 49 | Medium | +| 50 - 100 | High | + +### TXT Example + +```text +Overall Risk +Risk Score: 39 +Risk Level: Medium ``` -When running from the project root after a Visual Studio Release build, use: +### JSON Example -```powershell -.\build\Release\pe_analyzer.exe -dynamic C:\Windows\System32\notepad.exe +```json +"risk": { + "score": 39, + "level": "Medium" +} ``` -Dynamic analysis has a default timeout of 30 seconds. The timeout can be configured from the command line with `-timeout `. +--- + +## Suspicious API Detection + +The static analyzer flags imported APIs that may be interesting during malware analysis. + +Flagged APIs are grouped by: -Example with custom timeout: +* API name +* DLL name +* Category +* Severity -```powershell -.\build\Release\pe_analyzer.exe -dynamic C:\Windows\System32\notepad.exe -timeout 60 +Example JSON entry: + +```json +{ + "api": "CreateFileW", + "dll": "api-ms-win-core-file-l1-1-0.dll", + "category": "Dosya", + "severity": "Medium" +} ``` -If the target process does not exit before the timeout, the analyzer terminates the process and still exports TXT and JSON reports. +Suspicious API findings are not proof of malware by themselves. -Dynamic analysis reports also include the elapsed analysis duration. This value is exported as `Duration Seconds` in TXT reports and `durationSeconds` in JSON reports. +They only indicate that the file imports APIs that may require manual review. -Dynamic analysis produces time-stamped event output and a summary: +--- -```text -[19:59:06] [EVENT 1] NtCreateFile -[19:59:06] [EVENT 2] NtCreateFile -[19:59:06] [EVENT 3] NtCreateFile -[19:59:06] [EVENT 4] NtCreateFile +## Suspicious API Categories -[ Dinamik Analiz Ozeti ] - -> Durum: timeout - -> Sure: 5 saniye - -> NtCreateFile: 4 - -> NtWriteFile: 0 - -> NtOpenProcess: 0 - -> NtTerminateProcess: 0 - -> Toplam yakalanan olay: 4 -``` +The analyzer currently groups suspicious APIs into categories such as: -After the process exits or the timeout is reached, the tool creates the following files: +| 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 | -```text -dynamic_analysis_report.txt -dynamic_analysis_report.json -``` +--- -### Sample Dynamic TXT Report +## Suspicious API Severity -```text -Dynamic Analysis Report -Target: C:\Windows\System32\notepad.exe -Generated At: 19:59:11 -Status: timeout -Timeout Seconds: 5 -Duration Seconds: 5 +Suspicious APIs are classified by severity. -Summary -NtCreateFile: 4 -NtWriteFile: 0 -NtOpenProcess: 0 -NtTerminateProcess: 0 -Total Events: 4 +| Severity | Meaning | +| -------- | -------------------------------------- | +| Low | Interesting but weak signal | +| Medium | Requires manual review | +| High | Stronger suspicious behavior indicator | -Event Log -[19:59:06] [EVENT 1] NtCreateFile -[19:59:06] [EVENT 2] NtCreateFile -[19:59:06] [EVENT 3] NtCreateFile -[19:59:06] [EVENT 4] NtCreateFile +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. + +### TXT Example + +```text +Suspicious DLL Summary +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 ``` -### Sample Dynamic JSON Report +### JSON Example ```json -{ - "target": "C:\\Windows\\System32\\notepad.exe", - "generatedAt": "19:59:11", - "status": "timeout", - "timeoutSeconds": 5, - "durationSeconds": 5, - "summary": { - "events": { - "NtCreateFile": 4, - "NtWriteFile": 0, - "NtOpenProcess": 0, - "NtTerminateProcess": 0 - }, - "totalEvents": 4 - }, - "eventLog": [ - { - "id": 1, - "timestamp": "19:59:06", - "api": "NtCreateFile" - }, - { - "id": 2, - "timestamp": "19:59:06", - "api": "NtCreateFile" - }, - { - "id": 3, - "timestamp": "19:59:06", - "api": "NtCreateFile" - }, - { - "id": 4, - "timestamp": "19:59:06", - "api": "NtCreateFile" - } - ] +"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 } ``` -Use dynamic analysis only inside an isolated, secure environment. +--- + +## Section Entropy Analysis -## Timeout Validation +Static analysis calculates Shannon entropy for each PE section. -The `-timeout` option is only valid with dynamic analysis. +Entropy can help identify packed, compressed, or encrypted content. -Valid timeout range: +| 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. + +--- + +## Dynamic Report Output + +Dynamic analysis creates dynamic report files when executed. + +Generated files: ```text -1 - 3600 seconds +dynamic_analysis_report.txt +dynamic_analysis_report.json ``` -Examples: +With custom output directory: -```powershell -.\build\Release\pe_analyzer.exe -dynamic C:\Windows\System32\notepad.exe -timeout 5 -.\build\Release\pe_analyzer.exe -dynamic C:\Windows\System32\notepad.exe -timeout 60 +```text +reports\dynamic_analysis_report.txt +reports\dynamic_analysis_report.json ``` -Invalid examples: +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. -```powershell -.\build\Release\pe_analyzer.exe -dynamic C:\Windows\System32\notepad.exe -timeout abc -.\build\Release\pe_analyzer.exe -dynamic C:\Windows\System32\notepad.exe -timeout 0 -.\build\Release\pe_analyzer.exe -static C:\Windows\System32\notepad.exe -timeout 5 +--- + +## Example Workflow + +Build the project: + +```bash +cmake -B build +cmake --build build --config Release ``` -## Generated Report Files +Run static analysis: -The following files are generated during analysis and should not be committed: +```bash +.\build\Release\pe_analyzer.exe -static C:\Windows\System32\notepad.exe -out reports +``` -```text -static_analysis_report.txt -static_analysis_report.json -dynamic_analysis_report.txt -dynamic_analysis_report.json +Check generated reports: + +```bash +notepad reports\static_analysis_report.txt +notepad reports\static_analysis_report.json ``` -## Automatic Build Control +Run dynamic analysis in a VM: -The repository contains a GitHub Actions workflow file that runs a Windows Release build for pull requests opened against the `main` branch and for changes merged into the `main` branch. +```bash +.\build\Release\pe_analyzer.exe -dynamic C:\samples\example.exe -timeout 60 -out reports +``` + +--- ## Project Structure ```text MalwareAnalysisTool/ -|-- .github/ -| `-- workflows/ -| `-- windows-build.yml -|-- include/ -| `-- analyzer/ -| |-- pe_parser.hpp -| |-- dynamic_analyzer.hpp -| `-- utils.hpp -|-- src/ -| |-- main.cpp -| |-- pe_parser.cpp -| `-- dynamic_analyzer.cpp -|-- CMakeLists.txt -|-- LICENSE -`-- README.md +├── include/ +│ └── analyzer/ +│ ├── pe_parser.hpp +│ ├── dynamic_analyzer.hpp +│ └── utils.hpp +├── src/ +│ ├── main.cpp +│ ├── pe_parser.cpp +│ └── dynamic_analyzer.cpp +├── CMakeLists.txt +├── LICENSE +└── README.md ``` +--- + ## Current Limitations * Dynamic analysis is experimental. -* Dynamic monitoring currently supports four `ntdll.dll` API functions. -* Dynamic analysis reports API calls but does not yet decode call parameters. -* Network monitoring has not been implemented yet. -* Dynamic reports include event counters, elapsed duration, and time-stamped event records, but not detailed API arguments. -* Static suspicious API categories, severity levels, and section risk levels are heuristic indicators. -* The active application entry point is the command-line interface. -* GUI development will continue after the analysis core becomes stable. +* 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. + +--- ## Roadmap -* Add configurable report output directory support -* Decode selected dynamic API parameters -* Add controlled network monitoring -* Expand automated testing coverage -* Improve static suspicious API rules and severity tuning -* Re-add the GUI interface after the analysis core becomes stable +* 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. + +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. + +--- ## License -MIT - see the [LICENSE](LICENSE) file for details. +MIT — see the `LICENSE` file for details.