Metadata-Version: 2.4
Name: packerscope
Version: 0.1.1
Summary: Automatic packer detection, classification, and unpacking framework for Windows PE files.
Author-email: Salman Mallah <mallahsalman06@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/salmanmallah/packerscope
Project-URL: Repository, https://github.com/salmanmallah/packerscope
Project-URL: Issues, https://github.com/salmanmallah/packerscope/issues
Keywords: packer,unpacker,pe,malware,reverse-engineering,binary-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Disassemblers
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pefile>=2024.8.26
Requires-Dist: pydantic>=2.9
Requires-Dist: pydantic-settings>=2.5
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.9
Requires-Dist: structlog>=24.4
Requires-Dist: pyyaml>=6.0
Requires-Dist: colorama>=0.4.6; sys_platform == "win32"
Provides-Extra: analysis
Requires-Dist: lief>=0.15; extra == "analysis"
Requires-Dist: capstone>=5.0; extra == "analysis"
Provides-Extra: yara
Requires-Dist: yara-python>=4.5; extra == "yara"
Provides-Extra: dynamic
Requires-Dist: frida>=16.5; extra == "dynamic"
Requires-Dist: qiling>=1.4; extra == "dynamic"
Provides-Extra: hashing
Requires-Dist: ppdeep>=20200723; extra == "hashing"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Provides-Extra: all
Requires-Dist: packerscope[analysis,dynamic,hashing,yara]; extra == "all"
Dynamic: license-file

# PackerScope

**PackerScope** is a production-quality Python framework for automatic packer detection, classification, and unpacking of Windows PE files. It is designed for defensive security research, malware analysis labs, and educational purposes.

## Features

- **Multi-layered Detection Pipeline:**
  - **Entropy Analysis:** Measures Shannon entropy across the whole file, sections, and via a sliding window.
  - **Section Analysis:** Detects anomalous section names (e.g., `UPX0`, `.vmp0`), extreme virtual-to-raw size ratios, and abnormal permissions (RWX).
  - **IAT Analysis:** Analyzes Import Address Table sparseness and suspicious API usage (e.g., `LoadLibrary`, `VirtualAlloc`).
  - **Entry Point Analysis:** Disassembles entry point instructions using Capstone to detect jump chains, NOP sleds, and push/ret trampolines.
  - **Structure Analysis:** Identifies anomalies in PE optional and file headers, missing directories, or invalid timestamps.
  - **Signature Matching:** Fast byte-pattern matching using PEiD-style `userdb.txt` databases.
  - **YARA Scanning:** Deep static analysis utilizing community or custom YARA rules.
  - **Heuristics Engine:** Aggregates weak signals across all modules to form a high-confidence final verdict.

- **Automated Unpacking (Pluggable):**
  - **UPXUnpacker:** Native fast decompression using the `upx` system binary.
  - **GenericStaticUnpacker:** Template for static algorithmic decompression (aPLib, LZMA).
  - **DynamicUnpacker:** Template for dynamic unpacking via emulation (Qiling/Unicorn) or instrumentation (Frida).

- **Verification Subsystem:** Automatically verifies the success of an unpacking attempt by checking PE validity, entropy reduction, IAT restoration, and section normalization.

- **Reporting:** Generates comprehensive analysis reports in JSON, CSV, Markdown, and HTML formats.

- **Developer-Friendly:** Written in modern Python 3.13+, completely type-hinted, and modular using Pydantic v2 data models and the Blackboard design pattern (`PEContext`).

## Requirements

- Python 3.13+
- Windows (Primary target OS, though the framework runs on Linux/macOS)
- Recommended external tools: `upx`, Capstone

## Installation

1. Clone the repository or navigate to the framework directory.
2. Install the required dependencies:

```bash
pip install -r requirements.txt
```

*(Optional)* For advanced features like disassembly and dynamic analysis, you can install optional dependency groups defined in `pyproject.toml`.

## Usage

PackerScope provides an easy-to-use Command Line Interface (CLI):

### Analyze a Single File
```bash
python -m packerscope.cli scan samples/malware.exe --format json,html --output results/
```

### Batch Analyze a Directory
```bash
python -m packerscope.cli batch samples/ --workers 8 --format csv
```

### View Quick PE Information
```bash
python -m packerscope.cli info samples/malware.exe
```

## Architecture

1. **Orchestrator:** Manages the entire pipeline (Initialization → Detection → Verdict → Unpack → Verify → Report).
2. **PEContext:** The central Blackboard state object. Parsed PE data and detector results are shared here.
3. **Plugin Manager:** Dynamically discovers and loads detectors, unpackers, and reporters from the framework and external directories.
4. **Detectors:** Implement `BaseDetector`. Executed in priority order.
5. **Unpackers:** Implement `BaseUnpacker`. Selected dynamically based on the final packer verdict.

## Project Structure

```
packer_identifier_framework/
├── packerscope/
│   ├── cli.py                 # Command-line interface
│   ├── config.py              # Central configuration (Pydantic Settings)
│   ├── constants.py           # Thresholds and heuristics constants
│   ├── context.py             # PEContext (Blackboard state)
│   ├── exceptions.py          # Custom exceptions
│   ├── orchestrator.py        # Pipeline execution logic
│   ├── plugin_manager.py      # Plugin discovery and registration
│   ├── core/                  # Interfaces, Enums, and Pydantic Models
│   ├── detectors/             # Detection modules (Entropy, IAT, YARA, etc.)
│   ├── reporters/             # Output generators (JSON, CSV, HTML, MD)
│   ├── signatures/            # PEiD signature parsing
│   ├── unpackers/             # Unpacking strategies
│   ├── utils/                 # Helpers (disasm, entropy, hasher, pe_parser)
│   └── verification/          # Unpack verification logic
├── plugins/                   # Directory for custom third-party plugins
├── tests/                     # Unit and Integration tests
├── pyproject.toml             # Project metadata and dependencies
└── requirements.txt           # Flat dependency list
```

## Running Tests

PackerScope comes with a comprehensive test suite covering core models, utility functions, detectors, config, and orchestrator integration.

```bash
pytest tests/ -v
```

## Disclaimer

**Educational and Research Purposes Only.** This framework is intended strictly for defensive security research, malware analysis, and educational use within isolated malware analysis lab environments. Do not use this tool on systems or files you do not have permission to analyze.
