packerscope 0.1.1__tar.gz

packerscope-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Salman Mallah
+
+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.

packerscope-0.1.1/PKG-INFO

@@ -0,0 +1,157 @@
+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.

packerscope-0.1.1/README.md

@@ -0,0 +1,107 @@
+# 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.

packerscope-0.1.1/packerscope/__init__.py

@@ -0,0 +1,4 @@
+"""PackerScope — Automatic packer detection, classification, and unpacking framework."""
+
+__version__ = "0.1.1"
+__author__ = "Salman Mallah"

packerscope-0.1.1/packerscope/cli.py

@@ -0,0 +1,266 @@
+"""PackerScope command-line interface.
+
+Provides the ``packerscope`` CLI for single file analysis and batch
+scanning.
+
+Usage:
+    packerscope scan sample.exe
+    packerscope scan --format json,html samples/
+    packerscope batch samples/ --workers 8
+    packerscope info sample.exe
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from packerscope import __version__
+from packerscope.config import Config
+from packerscope.orchestrator import Orchestrator
+from packerscope.utils.logger import setup_logging
+
+console = Console()
+
+
+@click.group()
+@click.version_option(__version__, prog_name="PackerScope")
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging")
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+@click.option("--json-log", is_flag=True, help="Output logs in JSON format")
+@click.option("--log-file", type=click.Path(), default=None, help="Log to file")
+@click.pass_context
+def main(ctx: click.Context, verbose: bool, debug: bool, json_log: bool, log_file: str | None) -> None:
+    """PackerScope — Automatic packer detection, classification & unpacking."""
+    level = "DEBUG" if debug else ("INFO" if verbose else "WARNING")
+    log_path = Path(log_file) if log_file else None
+    setup_logging(level=level, log_file=log_path, json_output=json_log)
+    ctx.ensure_object(dict)
+    ctx.obj["config"] = Config()
+
+
+@main.command()
+@click.argument("target", type=click.Path(exists=True))
+@click.option("--format", "-f", "formats", default="json", help="Report formats (comma-separated: json,csv,md,html)")
+@click.option("--output", "-o", type=click.Path(), default=None, help="Output directory")
+@click.option("--no-unpack", is_flag=True, help="Skip unpacking step")
+@click.option("--no-verify", is_flag=True, help="Skip unpacking verification")
+@click.pass_context
+def scan(
+    ctx: click.Context,
+    target: str,
+    formats: str,
+    output: str | None,
+    no_unpack: bool,
+    no_verify: bool,
+) -> None:
+    """Analyze a PE file or directory for packer detection."""
+    config: Config = ctx.obj["config"]
+
+    if output:
+        config.output_dir = Path(output)
+    if no_unpack:
+        config.enable_unpack = False
+    if no_verify:
+        config.enable_verification = False
+
+    # Parse report formats
+    from packerscope.core.enums import ReportFormat
+    fmt_map = {"json": ReportFormat.JSON, "csv": ReportFormat.CSV, "md": ReportFormat.MARKDOWN, "html": ReportFormat.HTML}
+    config.report_formats = [fmt_map[f.strip()] for f in formats.split(",") if f.strip() in fmt_map]
+
+    target_path = Path(target)
+    orch = Orchestrator(config)
+
+    if target_path.is_file():
+        _analyze_single(orch, target_path)
+    elif target_path.is_dir():
+        _analyze_directory(orch, target_path, config)
+    else:
+        console.print(f"[red]Error: {target} is not a valid file or directory[/red]")
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("directory", type=click.Path(exists=True, file_okay=False))
+@click.option("--workers", "-w", type=int, default=None, help="Number of concurrent workers")
+@click.option("--format", "-f", "formats", default="json,csv", help="Report formats")
+@click.option("--output", "-o", type=click.Path(), default=None, help="Output directory")
+@click.pass_context
+def batch(
+    ctx: click.Context,
+    directory: str,
+    workers: int | None,
+    formats: str,
+    output: str | None,
+) -> None:
+    """Batch-analyze all PE files in a directory."""
+    config: Config = ctx.obj["config"]
+    if output:
+        config.output_dir = Path(output)
+
+    from packerscope.core.enums import ReportFormat
+    fmt_map = {"json": ReportFormat.JSON, "csv": ReportFormat.CSV, "md": ReportFormat.MARKDOWN, "html": ReportFormat.HTML}
+    config.report_formats = [fmt_map[f.strip()] for f in formats.split(",") if f.strip() in fmt_map]
+
+    dir_path = Path(directory)
+    pe_files = _find_pe_files(dir_path)
+
+    if not pe_files:
+        console.print(f"[yellow]No PE files found in {directory}[/yellow]")
+        return
+
+    console.print(f"[cyan]Found {len(pe_files)} PE file(s) to analyze[/cyan]")
+    orch = Orchestrator(config)
+    orch.initialize()
+
+    reports = orch.analyze_batch(pe_files, max_workers=workers)
+
+    # Summary table
+    table = Table(title="Batch Analysis Results", show_lines=True)
+    table.add_column("File", style="cyan")
+    table.add_column("Packed", justify="center")
+    table.add_column("Packer", style="yellow")
+    table.add_column("Confidence")
+    table.add_column("Duration")
+
+    for r in reports:
+        packed_str = "[red]YES[/red]" if r.verdict.is_packed else "[green]NO[/green]"
+        table.add_row(
+            r.file_name,
+            packed_str,
+            r.verdict.packer.value,
+            f"{r.verdict.confidence:.1%}",
+            f"{r.analysis_duration_seconds:.2f}s",
+        )
+
+    console.print(table)
+    packed_count = sum(1 for r in reports if r.verdict.is_packed)
+    console.print(f"\n[bold]Summary:[/bold] {packed_count}/{len(reports)} files detected as packed")
+
+
+@main.command()
+@click.argument("file", type=click.Path(exists=True))
+@click.pass_context
+def info(ctx: click.Context, file: str) -> None:
+    """Show quick PE file information (no detection pipeline)."""
+    from packerscope.context import PEContext
+
+    file_path = Path(file)
+    with PEContext(file_path) as pctx:
+        pctx.initialize()
+
+        console.print(Panel(f"[bold cyan]{file_path.name}[/bold cyan]", subtitle=f"{file_path}"))
+
+        if pctx.metadata:
+            m = pctx.metadata
+            table = Table(title="File Metadata")
+            table.add_column("Property", style="cyan")
+            table.add_column("Value")
+            table.add_row("MD5", m.md5)
+            table.add_row("SHA256", m.sha256)
+            table.add_row("Imphash", m.imphash or "N/A")
+            table.add_row("Size", f"{m.file_size:,} bytes")
+            table.add_row("Machine", m.machine_type)
+            console.print(table)
+
+        if pctx.pe and pctx.pe.is_valid:
+            pe = pctx.pe
+            sec_table = Table(title="Sections")
+            sec_table.add_column("Name")
+            sec_table.add_column("VSize", justify="right")
+            sec_table.add_column("RSize", justify="right")
+            sec_table.add_column("Entropy", justify="right")
+            from packerscope.utils.entropy import calculate_entropy
+            for sec in pe.sections:
+                data = sec.data if sec.data else b""
+                ent = calculate_entropy(data) if data else 0.0
+                sec_table.add_row(
+                    sec.name, f"{sec.virtual_size:,}",
+                    f"{sec.raw_size:,}", f"{ent:.4f}",
+                )
+            console.print(sec_table)
+
+
+def _analyze_single(orch: Orchestrator, file_path: Path) -> None:
+    """Analyze a single file and print results."""
+    try:
+        report = orch.analyze(file_path)
+        _print_report(report)
+    except Exception as e:
+        console.print(f"[red]Analysis failed: {e}[/red]")
+        sys.exit(1)
+
+
+def _analyze_directory(orch: Orchestrator, dir_path: Path, config: Config) -> None:
+    """Analyze all PE files in a directory."""
+    pe_files = _find_pe_files(dir_path)
+    if not pe_files:
+        console.print(f"[yellow]No PE files found in {dir_path}[/yellow]")
+        return
+
+    console.print(f"[cyan]Found {len(pe_files)} PE file(s)[/cyan]")
+    orch.initialize()
+    for f in pe_files:
+        try:
+            report = orch.analyze(f)
+            _print_report_summary(report)
+        except Exception as e:
+            console.print(f"[red]{f.name}: Error — {e}[/red]")
+
+
+def _find_pe_files(directory: Path) -> list[Path]:
+    """Recursively find PE files in a directory."""
+    extensions = {".exe", ".dll", ".sys", ".drv", ".ocx", ".scr"}
+    files = []
+    for ext in extensions:
+        files.extend(directory.rglob(f"*{ext}"))
+    return sorted(files)
+
+
+def _print_report(report) -> None:
+    """Print a detailed Rich-formatted analysis report."""
+    v = report.verdict
+    color = "red" if v.is_packed else "green"
+    status = "PACKED" if v.is_packed else "NOT PACKED"
+
+    console.print(Panel(
+        Text.from_markup(f"[bold {color}]{status}[/bold {color}]"),
+        title=f"{report.file_name}",
+        subtitle=f"Confidence: {v.confidence:.1%} ({v.confidence_level.value})",
+    ))
+
+    if v.is_packed:
+        console.print(f"  Packer: [yellow bold]{v.packer.value}[/yellow bold]")
+
+    if v.reasons:
+        console.print("\n  [bold]Reasons:[/bold]")
+        for r in v.reasons[:8]:
+            console.print(f"    • {r}")
+
+    console.print(f"\n  MD5:    [dim]{report.metadata.md5}[/dim]")
+    console.print(f"  SHA256: [dim]{report.metadata.sha256}[/dim]")
+    console.print(f"  Size:   {report.metadata.file_size:,} bytes")
+    console.print(f"  Time:   {report.analysis_duration_seconds:.3f}s")
+    console.print()
+
+
+def _print_report_summary(report) -> None:
+    """Print a one-line summary for batch processing."""
+    v = report.verdict
+    status = "[red]PACKED[/red]" if v.is_packed else "[green]CLEAN[/green]"
+    packer = f" [{v.packer.value}]" if v.is_packed else ""
+    console.print(
+        f"  {report.file_name:40s} {status}{packer} "
+        f"({v.confidence:.0%}) {report.analysis_duration_seconds:.2f}s"
+    )
+
+
+if __name__ == "__main__":
+    main()