entropystrip 1.0.0__tar.gz

entropystrip-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EntropyStrip Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

entropystrip-1.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: entropystrip
+Version: 1.0.0
+Summary: Algorithmic PE de-obfuscator, Shannon entropy radar, and incident triage engine.
+Author-email: dwexi <dwexi@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dwexi/entropystrip
+Project-URL: Repository, https://github.com/dwexi/entropystrip
+Project-URL: Issues, https://github.com/dwexi/entropystrip/issues
+Keywords: malware-analysis,reverse-engineering,pe,entropy,shannon-entropy,incident-response,security,dfir
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Disassemblers
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pefile>=2024.8.26
+Requires-Dist: rich>=13.7.0
+Dynamic: license-file
+
+# entropystrip
+
+```text
+___________       __                               _________ __         .__        
+\_   _____/ _____/  |________  ____ ______ ___.__./   _____//  |________|__|_____  
+ |    __)_ /    \   __\_  __ \/  _ \\____ <   |  |\_____  \\   __\_  __ \  \____ \ 
+ |        \   |  \  |  |  | \(  <_> )  |_> >___  |/        \|  |  |  | \/  |  |_> >
+/_______  /___|  /__|  |__|   \____/|   __// ____/_______  /|__|  |__|  |__|   __/ 
+        \/     \/                   |__|   \/            \/                |__|    
+```
+
+
+---
+
+## What it does
+
+Most modern malware hides behind packers (like UPX, VMProtect, or Themida) or stashes encrypted payloads in PE resource directories or trailing file overlays. Rather than relying on static byte signatures, `entropystrip` evaluates:
+
+1. **Section Entropy:** Calculates block-level Shannon entropy across every PE section to locate encrypted or compressed buffers ($H > 7.20$).
+2. **Memory Permissions:** Identifies sections marked simultaneously as Writable and Executable (`IMAGE_SCN_MEM_WRITE` and `IMAGE_SCN_MEM_EXECUTE`), which indicates self-modifying code or runtime unpackers.
+3. **PE Overlays:** Measures trailing bytes appended past the end of the last mapped section.
+4. **Import Table Size & Composition:** Flags binaries with unusually small IATs (e.g. only importing `LoadLibrary` / `GetProcAddress`) or sensitive process injection primitives (`VirtualAlloc`, `WriteProcessMemory`, `QueueUserAPC`).
+5. **.NET Classification:** Inspects the COM descriptor directory to separate managed CLR assemblies from native binaries, avoiding false positives on standard C# applications.
+6. **Payload Carving:** Extracts identified high-entropy sections or overlays straight to raw binary files on disk for further analysis.
+7. **Directory Triage:** Walks directories or drives and ranks all found binaries by threat score.
+
+---
+
+## Installation
+
+Requirements: Python 3.8+ on Windows, Linux, or macOS.
+
+```bash
+pip install entropystrip
+```
+
+Or install directly from source:
+
+```bash
+git clone https://github.com/dwexi/entropystrip.git
+cd entropystrip
+pip install -e .
+```
+
+---
+
+## Usage
+
+```text
+usage: main.py [-h] [-r] [--dump] [--deep] [--html HTML] [--json JSON] target
+
+EntropyStrip: PE De-obfuscator & Triage Engine
+
+positional arguments:
+  target         Path to Windows executable (.exe / .dll) or directory to scan
+
+options:
+  -h, --help     show this help message and exit
+  -r, --recursive
+                 recursively scan subdirectories if target is a folder
+  --dump         carve and write high-entropy payloads to extracted_payloads/
+  --deep         deep forensic triage: MITRE ATT&CK mapping, entry point disassembly, hashes
+  --html HTML    write minimalist HTML report to specified path
+  --json JSON    write machine-readable JSON telemetry to specified path
+```
+
+### Examples
+
+**Analyze a single binary:**
+```bash
+python main.py target.exe
+```
+
+**Deep forensic triage with MITRE ATT&CK mapping & disassembly:**
+```bash
+python main.py suspicious.exe --deep
+```
+
+**Analyze and extract hidden payload buffers:**
+```bash
+python main.py suspicious.exe --dump
+```
+Carved payloads are written to `extracted_payloads/<target>_<section>.bin`.
+
+**Export a standalone HTML report:**
+```bash
+python main.py sample.exe --html report.html
+```
+
+**Triage an entire directory of unknown files:**
+```bash
+python main.py "C:\IncidentTriage" -r
+```
+
+---
+
+## Entropy Scale Reference
+
+Shannon entropy measures information density from 0.00 to 8.00 bits per byte:
+
+$$H(X) = -\sum_{i=0}^{255} P(x_i) \log_2 P(x_i)$$
+
+| Entropy Range | Expected Content | Notes |
+|---|---|---|
+| `0.00 - 2.00` | Zero-padding, sparse tables | Common in uninitialized data or alignment padding |
+| `2.00 - 5.50` | Standard ASCII, configurations | Normal application metadata, strings |
+| `5.50 - 6.60` | Native compiled machine code | Standard x86/x64 instructions (`.text`) |
+| `6.60 - 7.30` | Compressed assets | Bitmaps, icons, zlib/deflate streams |
+| `7.40 - 8.00` | Cryptographic ciphertext | AES/RC4 encrypted payloads or tightly packed shellcode |
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

entropystrip-1.0.0/README.md

@@ -0,0 +1,115 @@
+# entropystrip
+
+```text
+___________       __                               _________ __         .__        
+\_   _____/ _____/  |________  ____ ______ ___.__./   _____//  |________|__|_____  
+ |    __)_ /    \   __\_  __ \/  _ \\____ <   |  |\_____  \\   __\_  __ \  \____ \ 
+ |        \   |  \  |  |  | \(  <_> )  |_> >___  |/        \|  |  |  | \/  |  |_> >
+/_______  /___|  /__|  |__|   \____/|   __// ____/_______  /|__|  |__|  |__|   __/ 
+        \/     \/                   |__|   \/            \/                |__|    
+```
+
+
+---
+
+## What it does
+
+Most modern malware hides behind packers (like UPX, VMProtect, or Themida) or stashes encrypted payloads in PE resource directories or trailing file overlays. Rather than relying on static byte signatures, `entropystrip` evaluates:
+
+1. **Section Entropy:** Calculates block-level Shannon entropy across every PE section to locate encrypted or compressed buffers ($H > 7.20$).
+2. **Memory Permissions:** Identifies sections marked simultaneously as Writable and Executable (`IMAGE_SCN_MEM_WRITE` and `IMAGE_SCN_MEM_EXECUTE`), which indicates self-modifying code or runtime unpackers.
+3. **PE Overlays:** Measures trailing bytes appended past the end of the last mapped section.
+4. **Import Table Size & Composition:** Flags binaries with unusually small IATs (e.g. only importing `LoadLibrary` / `GetProcAddress`) or sensitive process injection primitives (`VirtualAlloc`, `WriteProcessMemory`, `QueueUserAPC`).
+5. **.NET Classification:** Inspects the COM descriptor directory to separate managed CLR assemblies from native binaries, avoiding false positives on standard C# applications.
+6. **Payload Carving:** Extracts identified high-entropy sections or overlays straight to raw binary files on disk for further analysis.
+7. **Directory Triage:** Walks directories or drives and ranks all found binaries by threat score.
+
+---
+
+## Installation
+
+Requirements: Python 3.8+ on Windows, Linux, or macOS.
+
+```bash
+pip install entropystrip
+```
+
+Or install directly from source:
+
+```bash
+git clone https://github.com/dwexi/entropystrip.git
+cd entropystrip
+pip install -e .
+```
+
+---
+
+## Usage
+
+```text
+usage: main.py [-h] [-r] [--dump] [--deep] [--html HTML] [--json JSON] target
+
+EntropyStrip: PE De-obfuscator & Triage Engine
+
+positional arguments:
+  target         Path to Windows executable (.exe / .dll) or directory to scan
+
+options:
+  -h, --help     show this help message and exit
+  -r, --recursive
+                 recursively scan subdirectories if target is a folder
+  --dump         carve and write high-entropy payloads to extracted_payloads/
+  --deep         deep forensic triage: MITRE ATT&CK mapping, entry point disassembly, hashes
+  --html HTML    write minimalist HTML report to specified path
+  --json JSON    write machine-readable JSON telemetry to specified path
+```
+
+### Examples
+
+**Analyze a single binary:**
+```bash
+python main.py target.exe
+```
+
+**Deep forensic triage with MITRE ATT&CK mapping & disassembly:**
+```bash
+python main.py suspicious.exe --deep
+```
+
+**Analyze and extract hidden payload buffers:**
+```bash
+python main.py suspicious.exe --dump
+```
+Carved payloads are written to `extracted_payloads/<target>_<section>.bin`.
+
+**Export a standalone HTML report:**
+```bash
+python main.py sample.exe --html report.html
+```
+
+**Triage an entire directory of unknown files:**
+```bash
+python main.py "C:\IncidentTriage" -r
+```
+
+---
+
+## Entropy Scale Reference
+
+Shannon entropy measures information density from 0.00 to 8.00 bits per byte:
+
+$$H(X) = -\sum_{i=0}^{255} P(x_i) \log_2 P(x_i)$$
+
+| Entropy Range | Expected Content | Notes |
+|---|---|---|
+| `0.00 - 2.00` | Zero-padding, sparse tables | Common in uninitialized data or alignment padding |
+| `2.00 - 5.50` | Standard ASCII, configurations | Normal application metadata, strings |
+| `5.50 - 6.60` | Native compiled machine code | Standard x86/x64 instructions (`.text`) |
+| `6.60 - 7.30` | Compressed assets | Bitmaps, icons, zlib/deflate streams |
+| `7.40 - 8.00` | Cryptographic ciphertext | AES/RC4 encrypted payloads or tightly packed shellcode |
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

entropystrip-1.0.0/entropystrip/__init__.py

@@ -0,0 +1,23 @@
+"""
+EntropyStrip: Algorithmic PE De-obfuscator, Shannon Entropy Radar, and Incident Triage Engine.
+"""
+
+__version__ = "1.0.0"
+__author__ = "dwexi"
+
+from .core import (
+    calculate_entropy,
+    calculate_dilution_metrics,
+    analyze_single_file,
+    scan_directory,
+    main,
+)
+
+__all__ = [
+    "calculate_entropy",
+    "calculate_dilution_metrics",
+    "analyze_single_file",
+    "scan_directory",
+    "main",
+    "__version__",
+]

entropystrip-1.0.0/entropystrip/__main__.py

@@ -0,0 +1,5 @@
+"""CLI entry point when executed via python -m entropystrip."""
+from .core import main
+
+if __name__ == "__main__":
+    main()