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 curated, deduplicated PEiD database signatures.
  • YARA Scanning: Deep static analysis utilizing community or custom YARA rules with PE section-name verification.
  • Heuristic Aggregator: Combines weighted multi-module signals with contextual correlation into an ensemble packing verdict (low false-positive rate on clean binaries, explicit PackerType.INVALID verdict for corrupted/non-PE inputs).

• Automated Unpacking & Memory Safety:

  • UPXUnpacker: Native decompression using a verified absolute upx binary path (protected against CWD binary hijacking).
  • GenericStaticUnpacker: Safe streaming static decompression (bounded to 32 MB) with strict PE header and structure validation before saving unpacked payloads.
  • 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 escaped, injection-safe structured reports in JSON, CSV, Markdown, and HTML formats.

• High Performance & Concurrency: Multi-threaded batch processing with worker thread safety clamping, thread-safe CSV output, and collision-free <sha256[:12]> unpacked filenames.

Installation

From PyPI

pip install packerscope

From Source

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

Optional Dependencies

For disassembly (capstone), YARA scanning (yara-python), and fuzzy hashing (ppdeep):

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(f"File is not packed (verdict: {result.packer}).")

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

# Standard scan with JSON and HTML reports
packerscope scan samples/sample.exe --format json,html --output results/

# Enable automatic unpacking and pass a custom YAML/JSON configuration file
packerscope scan samples/sample.exe --unpack --config config.yaml --output results/

# Explicitly disable unpacking even if enabled in config.yaml
packerscope scan samples/sample.exe --no-unpack --config config.yaml

Batch Analyze a Directory

# Batch scan with 8 workers, CSV output, and automatic unpacking
packerscope batch samples/ --workers 8 --unpack --format csv --output results/

# Batch scan with custom configuration file and unpacking disabled
packerscope batch samples/ --workers 4 --no-unpack --config config.yaml --format json,csv

Batch Scanning Memory Budget & Worker Guidance: Each concurrent worker holds at most one PE file buffer in memory (bounded by max_file_size_mb, default 100 MB, plus up to 32 MB during static stream decompression). Peak memory usage scales roughly as workers * max_file_size_mb. For large malware corpora on machines with 8–16 GB RAM, we recommend --workers 4 to --workers 8 (PackerScope automatically clamps --workers to a safe ceiling of 32).

Quick PE Information

packerscope info samples/sample.exe

Plugins & Extensibility

PackerScope dynamically loads custom detectors, unpackers, and reporters from:

1. User Plugin Directory: ~/.packerscope/plugins (or override via PACKERSCOPE_PLUGINS_DIR / plugins_dir in config).
2. Python Entry Points: packerscope.detectors, packerscope.unpackers, and packerscope.reporters.

Security Note: Loading plugins executes Python code via exec_module. Only install trusted plugins in ~/.packerscope/plugins, or disable external plugin discovery entirely with PACKERSCOPE_PLUGINS_ENABLED=false (plugins_enabled: false). See SECURITY.md and the Custom Unpacker Development Guide for details.

Architecture & Documentation

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, ctx.sections, 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.

Documentation Links

• Architecture & Design Document
• Adding Custom Unpackers Guide
• Security Policy & Safe Usage
• Changelog
• Provenance Note: The original initial design prompt for this project is archived in docs/history/prompt.txt.

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
├── docs/                      # Architecture, unpacker guide, and project history
├── tests/                     # Unit, false-positive, and corpus integration tests
├── CHANGELOG.md               # Release history
├── SECURITY.md                # Security policy and safe operational guidelines
├── pyproject.toml             # Packaging metadata and dependency definitions
└── requirements.txt           # Core runtime 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.