PackerScope

PackerScope is a production-grade Python framework for automated Windows PE packer detection, classification, and unpacking. Designed for defensive security analysts, reverse engineers, and malware analysis laboratories.

Features

• Interactive Terminal UI (TUI):

  • Launch packerscope with no arguments to enter a rich, menu-driven interactive shell with guided wizards, live scan results, settings tweaks, and session history tracking.

• Multi-layered Detection Pipeline:

  • Entropy Analysis: Measures Shannon entropy across whole files, sections, and via sliding-window heuristics.
  • 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 loader API usage with clean-binary whitelist protections.
  • Entry Point Analysis: Disassembles entry point instructions using Capstone to detect stubs, jump chains, NOP sleds, and trampolines.
  • Structure Analysis: Identifies structural PE header anomalies, misaligned headers, and invalid metadata with fast-path checksum bypass for large binaries.
  • Signature Matching: Built-in byte-pattern scanning using PEiD database signatures.
  • YARA Scanning: Deep static analysis utilizing community or custom YARA rules.
  • Heuristic Aggregator: Combines weighted multi-module signals with contextual correlation into an ensemble packing verdict (low false-positive rate on clean binaries).

• Automated Unpacking & Memory Safety:

  • UPXUnpacker: Native decompression using the UPX binary.
  • GenericStaticUnpacker: Safe streaming static decompression (bounded to 32 MB) to prevent memory exhaustion on large installers.
  • DynamicUnpacker: Dynamic emulation and instrumentation unpacker integration.

• Verification Subsystem: Automatically verifies unpacked binaries by validating PE integrity, entropy reduction, and IAT restoration.

• Multi-Format Reporting: Generates structured reports in JSON, CSV, Markdown, and HTML formats.

• High Performance & Concurrency: Multi-threaded batch processing with worker thread safety clamping and in-memory buffer deduplication.

Installation

From PyPI

pip install packerscope

From Source

git clone https://github.com/salmanmallah/packerscope.git
cd packerscope
pip install .

Optional Dependencies

For additional disassembly, YARA, or dynamic analysis capabilities:

pip install "packerscope[all]"

Quickstart (Python API)

PackerScope provides a simple, high-level Python API designed for rapid analysis and easy scripting.

Basic Analysis

import packerscope

# Analyze a single binary
result = packerscope.scan("path/to/sample.exe")

if result.is_packed:
    print(f"File is packed with {result.packer.upper()}")
    print(f"Confidence: {result.confidence:.2%}")
    print("Detection Reasons:")
    for reason in result.reasons:
        print(f"  - {reason}")
else:
    print("File is not packed.")

Dictionary Summary

import packerscope

result = packerscope.scan("path/to/sample.exe")
summary = result.summary()

print(summary)
# {
#     "file_name": "sample.exe",
#     "file_path": "C:\\samples\\sample.exe",
#     "is_packed": True,
#     "packer": "upx",
#     "confidence": 0.85,
#     "confidence_level": "high",
#     "reasons": [...],
#     "analysis_duration_seconds": 0.02
# }

Automatic Unpacking

import packerscope

# Analyze and unpack if a supported packer is found
result = packerscope.scan("path/to/sample.exe", unpack=True)

if result.unpack_result and result.unpack_result.success:
    print(f"Unpacked file saved to: {result.unpack_result.unpacked_path}")

Batch Scanning a Directory

import packerscope

# Scan all PE files in a directory concurrently
results = packerscope.batch_scan("samples_folder/", workers=8)

for res in results:
    status = "PACKED" if res.is_packed else "NOT PACKED"
    print(f"{res.file_name:<30} | {status:<10} | {res.packer:<10} | {res.confidence:.2%}")

Command Line Interface (CLI)

PackerScope can be executed in interactive mode or directly via subcommands:

Interactive Shell Mode (TUI)

Simply run packerscope without arguments to launch the interactive terminal wizard:

packerscope

Analyze a Single File

packerscope scan samples/sample.exe --format json,html --output results/

Batch Analyze a Directory

packerscope batch samples/ --workers 8 --format csv

Quick PE Information

packerscope info samples/sample.exe

Architecture

1. Interactive Shell: Rich-based terminal UI providing menu navigation, wizards, live status, and settings.
2. Orchestrator: Coordinates pipeline lifecycle: Initialization -> Detection -> Verdict -> Unpack -> Verify -> Report.
3. PEContext: Central blackboard state object. Parsed PE artifacts and detector results are shared here.
4. Plugin Manager: Dynamically discovers and loads detectors, unpackers, reporters, and verifiers.
5. Detectors: Independent modules implementing BaseDetector, executed in priority order.
6. Unpackers: Modules implementing BaseUnpacker, invoked based on verdict classification.

Project Structure

packer_identifier_framework/
├── packerscope/
│   ├── __init__.py            # Top-level public API (scan, detect, batch_scan)
│   ├── cli.py                 # Command-line interface & subcommand dispatcher
│   ├── shell.py               # Interactive Shell & TUI wizard
│   ├── 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      # Dynamic plugin discovery
│   ├── core/                  # Interfaces, Enums, and Pydantic Models
│   ├── detectors/             # Detection modules (Entropy, IAT, YARA, etc.)
│   ├── reporters/             # Report generators (JSON, CSV, HTML, MD)
│   ├── signatures/            # PEiD signature database & parser
│   ├── unpackers/             # Unpacker implementations
│   ├── utils/                 # Binary analysis helpers, concurrency & structured logging
│   └── verification/          # Post-unpack verification logic
├── tests/                     # Unit and Integration tests (116 passing tests)
├── pyproject.toml             # Packaging metadata and dependency definitions
└── requirements.txt           # Flat dependency list

Running Tests

Execute the automated test suite using pytest:

python -m pytest

Author & Maintainer

• Salman Mallah
• GitHub: @salmanmallah
• Email: mallahsalman06@gmail.com
• Repository: https://github.com/salmanmallah/packerscope
• PyPI: https://pypi.org/project/packerscope/

Citation

If you use PackerScope in academic research, security tooling, or malware analysis publications, please cite:

@software{packerscope2026,
  author = {Salman Mallah},
  title = {PackerScope: Automated Windows PE Packer Detection and Unpacking Framework},
  year = {2026},
  url = {https://github.com/salmanmallah/packerscope}
}

License

This project is licensed under the MIT License. See LICENSE for details.

Disclaimer

Educational and Defensive Research Purposes Only. This framework is intended strictly for defensive security research, malware analysis, and educational use within authorized environments.