Skip to content

Pagonic v0.3.0 — Safe ZIP Inspector

Choose a tag to compare

View all tags
@SetraTheXX SetraTheXX released this 07 Jun 16:57
· 32 commits to main since this release
v0.3.0
b6d1dd0

Pagonic v0.3.0 — Safe ZIP Inspector

Pagonic v0.3.0 is the first public release of Pagonic’s new direction: a security-aware Python ZIP inspection and safe extraction toolkit.

The main idea is simple:

Inspect before you extract.

Pagonic focuses on ZIP archive inspection, deterministic risk reporting, safer extraction behavior, and Python/CLI automation workflows. It is not a 7-Zip or WinRAR replacement, and it is not presented as production-ready software.

Highlights

This release introduces and stabilizes the Safe ZIP Inspector product surface:

  • pagonic inspect
  • pagonic inspect --json
  • pagonic inspect --markdown
  • pagonic verify --max-risk
  • pagonic safe-extract --dry-run
  • pagonic list --tree

The public direction is now centered around inspecting ZIP files before extraction, validating risk signals, producing readable reports, and extracting only after a safety gate.

Security and Hardening

This release includes several important safety improvements:

  • Hardened ZIP path safety behavior against Zip Slip / path traversal cases.
  • Improved handling for POSIX absolute paths, Windows drive paths, mixed separators, and traversal entries.
  • safe-extract now refuses unsupported ZIP compression methods instead of continuing into unsafe or unclear extraction behavior.
  • Inspection reports now use deterministic risk flags and structured report fields.
  • The basic usage example now follows an inspect-first workflow.

Inspection Reports

Pagonic can report ZIP archive risk signals such as:

  • path traversal entries
  • absolute paths
  • Windows drive paths
  • hidden files
  • suspicious extensions
  • high compression ratio entries
  • large uncompressed size
  • too many files
  • unsupported compression methods
  • CRC or ZIP structure errors

Reports are available through terminal output, JSON, and Markdown-oriented output.

Validation

This release was validated on both the main development machine and a clean Linux Dev Node.

  • Main PC: 303 passed, 8 skipped
  • Setra Dev Node: 302 passed, 9 skipped
  • python -m build: success
  • python -m pip check: success
  • Wheel-installed CLI smoke: success
  • python examples/basic_usage.py: success with inspect-first flow

Current Scope and Limits

Pagonic v0.3.0 is an alpha-stage / early public release.

Important notes:

  • Not production-ready.
  • Not a 7-Zip or WinRAR replacement.
  • ZIP-focused; no broad multi-format archive manager claim.
  • No PyPI/TestPyPI package is published for this release.
  • GUI remains optional and secondary.
  • ZipHandler remains as a compatibility facade.
  • Future public API direction centers on ZipReader, ZipWriter, and inspection/reporting APIs.
  • Benchmark output is intended for local validation and regression tracking, not universal speed claims.

Install From Source

For this release, use the GitHub source checkout:

git clone https://github.com/SetraTheXX/pagonic.git
cd pagonic
python -m pip install -e .

Optional GUI dependencies:

python -m pip install -e ".[gui]"

Development dependencies:

python -m pip install -e ".[dev]"

Quick Start

Inspect an archive before extraction:

pagonic inspect archive.zip

Generate JSON output:

pagonic inspect archive.zip --json

Verify an archive for automation:

pagonic verify archive.zip --max-risk medium

Preview safe extraction:

pagonic safe-extract archive.zip ./out --dry-run

List archive contents as a tree:

pagonic list archive.zip --tree

Release Checklist

  • Tag: v0.3.0
  • GitHub release type: normal release
  • Pre-release checkbox: not checked
  • PyPI/TestPyPI: not published
Assets 2
Loading