Pagonic

Pagonic is an alpha Python ZIP toolkit focused on safe archive inspection, secure extraction, and repeatable local benchmarking. Its main idea is simple:

Inspect before you extract.

The intended workflow is visible in the demo: inspect the archive, verify it against an explicit risk threshold, and let safe-extract refuse unsafe input before it writes files.

• A core library for inspecting, writing, reading, and validating ZIP archives.
• A pagonic command-line interface for inspect, verify, safe extract, and ZIP utilities.
• An optional PyQt6 GUI launched with pagonic-gui.

This repository contains the v0.5.0 alpha release. The import package remains Pagonic for compatibility; the distribution name is pagonic. No PyPI or TestPyPI package is published, so install from a local checkout or use the artifacts attached to the GitHub release.

Project Story

Pagonic started more than a year ago as one of my earliest software-learning projects. Its first direction was much broader and more experimental: a ZIP/archive engine with compression, extraction, GUI ideas, benchmarking, and performance experiments.

After many iterations, I revised the project direction and narrowed the public scope into something clearer:

Pagonic is not trying to be another desktop archive manager. It is becoming a security-aware ZIP inspection and safe extraction toolkit.

This v0.5.0 release builds on the first cleaned-up public direction from v0.4.0. It keeps the useful ZIP core, CLI, tests, and safety work while making the inspection policy, regression corpus, automation examples, package surface, and compatibility boundaries explicit.

Pagonic is still evolving, but its purpose is now clearer: inspect first, extract safely.

Install

No PyPI or TestPyPI package is published for this release, so install from a local checkout after cloning the repository.

For CLI-only use from a local checkout:

python -m pip install .

For local development:

python -m pip install -e .[dev,gui]

For CLI-only development with test dependencies:

python -m pip install -e .[dev]

Experimental performance helpers are optional and are not required by inspection or safe extraction:

python -m pip install -e .[performance]

The GUI is optional. If PyQt6 is not installed, pagonic-gui exits with a clear install message.

CLI Quick Start

pagonic --help
pagonic inspect suspicious.zip
pagonic inspect suspicious.zip --json
pagonic inspect suspicious.zip --markdown
pagonic verify release.zip
pagonic verify release.zip --max-risk medium
pagonic safe-extract upload.zip output/
pagonic safe-extract upload.zip output/ --dry-run
pagonic list archive.zip --tree
pagonic compress path/to/file.txt -o archive.zip
pagonic config list

Use inspect before extraction for untrusted ZIP files. safe-extract applies the inspection gate before writing files, supports --dry-run, and refuses ZIP entries that use unsupported compression methods.

Python API Quick Start

from Pagonic.core.formats.zip_writer import ZipWriter
from Pagonic.core.formats.zip_reader import ZipReader

writer = ZipWriter("archive.zip", compression_level=6)
writer.add_file("file.txt")
writer.finalize()

reader = ZipReader("archive.zip")
report = reader.inspect()

if report.risk_level in {"ok", "low"}:
    reader.extract_all("output")

Project Layout

Pagonic/          Python package
tests/            pytest suite
docs/             public documentation
examples/         small runnable examples
pyproject.toml    package metadata and tool config

Documentation

• Architecture
• User Guide
• Inspection Policy Contract
• Inspection JSON Schema Contract
• CI Integration
• Package Surface Audit
• 0.5 Migration Notes
• 0.5 Release Audit
• SARIF Evaluation
• ZipHandler Compatibility Policy
• Developer Guide
• 0.4 Migration Notes
• Roadmap
• Changelog
• Contributing
• Security Policy
• Code of Conduct

Contributing

Focused contributions are welcome, especially improvements to inspection determinism, security regression coverage, safe extraction policy, CI integration, and documentation. Read CONTRIBUTING.md, check the 0.5 roadmap, and use the issue templates before opening a pull request. Do not include private plans, local paths, secrets, generated archives, or benchmark output in public changes.

Risk Signals

Inspection reports are deterministic and do not use runtime AI. Current risk flags include:

pagonic inspect --json emits a stable alpha report with archive totals, overall risk_level, top-level risk_flags, recommended_action, and per-entry metadata. Entries preserve archive order and risk flags use a deterministic catalog order. See the Inspection JSON Schema Contract for canonical fields, compatibility aliases, ordering guarantees, and clean, risky, and invalid report examples. pagonic inspect --markdown renders the same inspection as a saved human-readable report.

Command Policy

Use inspect before extraction when the archive is untrusted. For automation, verify returns exit code 0 only when the report is within --max-risk and has no validation errors. safe-extract applies the same inspection gate before writing files and supports --dry-run.

See the inspection policy contract for the exact clean/risky/invalid decision table, defaults, unsupported-method rule, and exit codes.

The older extract command remains as a compatibility command for trusted archives. It uses secure path handling, but it is not an inspection policy gate; use safe-extract for untrusted input. list and info are read-only display commands and do not replace an inspection report.

Status

The current public release is 0.5.0: an alpha-stage, test-backed release with security-aware ZIP inspection, explicit policy gates, a synthetic security regression corpus, gated safe extraction, core ZIP behavior, CLI support, optional GUI packaging, MIT license, and CI-ready tests.

Pagonic is not intended for production-critical automation yet and is not positioned as a general multi-format desktop archive manager. The next work is evidence-driven maintenance: collect real usage signals, expand the security corpus when new rules are added, and revisit deferred integrations only when a concrete consumer justifies them.