zipcheck 0.1.0__tar.gz

zipcheck-0.1.0/.dockerignore

@@ -0,0 +1,25 @@
+.git/
+.github/
+.venv/
+.smoke/
+.uv-cache/
+.uv-python/
+.hypothesis/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.linTools/
+build/
+dist/
+htmlcov/
+**/__pycache__/
+**/*.egg-info/
+.coverage
+*.sarif
+docs/
+fuzz/
+packaging/
+tests/
+tools/
+pytest-of-*
+tmp*/

zipcheck-0.1.0/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-24
+
+First public release.
+
+### Added
+
+- Static metadata scanners for ZIP/ZIP64, TAR (including GNU/PAX sparse),
+  gzip, bzip2, xz/LZMA, Zstandard, 7-Zip and RAR 4/5.
+- Expansion-ratio and absolute-size policy with `clean` / `suspicious` /
+  `dangerous` / `unknown` verdicts.
+- Detection of impossible DEFLATE ratios, stored-size mismatches, overlapping
+  entries, shared local headers and inconsistent totals.
+- Bounded nested-archive inspection (ZIP, TAR, gzip, bzip2, xz) with depth,
+  archive-count, byte and time budgets.
+- Bounded in-memory decompression probe for formats without declared sizes.
+- Bounded content verification (`--verify`, `--verify-limit`,
+  `--require-verified`) that decompresses supported content into an in-memory
+  counting sink, never to disk.
+- `--production` fail-closed preset for user-upload pipelines; it implies
+  `--verify --require-verified`.
+- Recursive verification of nested archives: images up to 8 MiB are captured
+  and scanned with a shared 256 MiB nested-output budget.
+- New integrity findings: `HEADER_MISMATCH`, `ENTRY_COUNT_MISMATCH`,
+  `UNDERSTATED_COMPRESSED_SIZE`, `OVERSTATED_COMPRESSED_SIZE`,
+  `VERIFICATION_FAILED` and `UNVERIFIED`.
+- `nested_unverified` in JSON output, propagated from child scans to the parent.
+- CLI with human and JSON output, directory recursion, configurable fail
+  thresholds and documented exit codes.
+- PEP 517/621 packaging with a typed-package marker, wheel/sdist smoke tests,
+  and PyPI trusted publishing through GitHub OIDC.
+- CI across Linux, macOS and Windows on Python 3.10-3.14, with branch coverage,
+  ruff and mypy gates.
+- Hypothesis property tests and a coverage-guided Atheris fuzz harness with a
+  seed corpus and a weekly fuzz workflow.
+- Arch Linux AUR packaging under `packaging/aur`.
+- Safe test corpus generators, sandbox benchmark tool, Dockerfile, and
+  documentation of where each format stores its uncompressed size and why a
+  magic "bomb signature" does not exist.
+
+### Fixed
+
+- The ZIP parser now parses the central directory to its declared end instead of
+  stopping at the attacker-controlled EOCD entry count, exposing hidden entries.
+- Local headers are cross-checked against central-directory metadata, so tools
+  cannot be played against each other with contradictory sizes or methods.
+- Verification detects compressed streams that continue past their declared
+  `csize`, catching forged one-byte members.
+- xz content verification drained the decoder's buffered output correctly;
+  highly compressible streams were previously under-measured and reported as
+  `METADATA_OVERSTATED` instead of being fully verified.
+- Verification failures and unverifiable nested content now fail closed
+  (`suspicious`, or `unknown` under `--require-verified`) instead of reporting
+  `clean`.
+- Nested gzip inspection now follows concatenated members instead of stopping at
+  the first one, so an archive split across members is still inspected.
+- Nested xz and bzip2 prefix capture now drains the decoders' buffered output,
+  so a highly compressible inner archive is captured completely.
+- ZIP LZMA members are now decoded for nested-archive sniffing (bounded), not
+  skipped silently.
+- Hitting the central-directory parse limit is reported as truncation
+  (`MEDIUM`) instead of being misclassified as hidden entries (`HIGH`).
+- A malformed-header unpack in the nested ZIP prefix parser shifted `csize` and
+  `usize` by two bytes; fixed.
+- `scan_file` now opens the file before `fstat`ing the same descriptor,
+  removing a stat-then-open race.
+- Human-readable output now groups repeated nested siblings correctly instead of
+  printing each one at the same indentation.
+
+[0.1.0]: https://github.com/spaxe-dev/zipcheck/releases/tag/v0.1.0

zipcheck-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing
+
+Thanks for helping make archive handling less exciting.
+
+## Setup
+
+```bash
+git clone <this repository>
+cd zipcheck
+python -m pip install -e ".[dev]"
+python -m pytest
+ruff check src tests tools
+mypy src/zipcheck
+```
+
+Python 3.10+ is required. Runtime code must stay dependency-free; if a feature
+ever needs a third-party package, put it in an optional extra and make the
+feature degrade gracefully when that extra is not installed.
+
+## Ground rules
+
+1. **Never extract member data.** Parsers may read metadata, and may decompress
+   a *bounded* prefix into memory for nested-archive inspection. They must
+   never write extracted content to disk, emit temp files, or call external
+   archive tools.
+2. **Never allocate from a declared size.** A header claiming 10 TiB must not
+   cause a 10 TiB allocation. Read in fixed-size chunks and stop at a cap.
+3. **Fail closed.** If metadata cannot be read reliably, the result must be
+   `unknown` — not `clean`.
+4. **No exceptions escape `scan_file`.** Malformed input is normal input.
+5. **Add a test for every parser change.** Prefer a metadata-only fixture (a
+   few dozen bytes) over a real bomb.
+6. **Keep the output stable.** JSON field names are part of the public API.
+
+## Adding a format
+
+1. Add magic/extension routing in `detect.py`.
+2. Add a parser module under `src/zipcheck/formats/` exposing
+   `scan(fp, size, limits, deadline) -> Facts`.
+3. Read sizes from headers or indexes. If the format has no size field, use
+   `formats/probe.py` with a bounded output and explain the limitation in the
+   module docstring.
+4. Register it in `engine.PARSERS` and decide whether nested inspection is
+   feasible.
+5. Add tests: a clean sample, a declared-huge sample, and a malformed sample.
+6. Document where the size lives in `docs/metadata-map.md` and add the format to
+   the README table.
+
+## Adding a detection rule
+
+- Emit a `Finding` with a stable `code`, a severity, and a human explanation.
+- Policy thresholds belong in `Limits`, not hard-coded in a parser.
+- Keep false positives explainable: "this is a large expansion", not "this is
+  malware".
+- Update the rules table in `README.md`.
+
+## Test fixtures
+
+Use `tests/helpers.py` to build archives. Tests must not contain or download
+live bombs. If a real archive is essential to reproduce a bug, minimise it to a
+metadata-only file first.
+
+For integration testing against real bombs, use `tools/generate_samples.py`
+inside a disposable VM/container. The generated files are small on disk but
+enormous when extracted.
+
+## Fuzzing
+
+Hypothesis property tests run with the normal suite. The coverage-guided
+Atheris harness is Linux-only:
+
+```bash
+python -m pip install -e .[fuzz]
+python fuzz/generate_seeds.py fuzz/corpus
+python fuzz/fuzz_scan.py fuzz/corpus -max_total_time=120
+```
+
+The weekly `fuzz` workflow runs the same harness and uploads crashing inputs.
+
+## Releasing
+
+1. Bump `__version__` in `src/zipcheck/__init__.py`; the package version is read
+   from that attribute. Add a `CHANGELOG.md` entry.
+2. Run the full gate: `pytest`, `mypy src/zipcheck`, `ruff check src tests tools`,
+   `python -m build` and `twine check dist/*`.
+3. Commit, then tag and push `vX.Y.Z`. `.github/workflows/release.yml` builds and
+   smoke-tests the sdist/wheel, publishes to PyPI through OIDC trusted
+   publishing, and creates a GitHub release.
+4. One-time setup: register a trusted publisher on PyPI for owner `spaxe-dev`,
+   repository `zipcheck`, workflow `release.yml`, environment `pypi`; create the
+   same `pypi` environment in the GitHub repository.
+5. For AUR, wait for the GitHub release, update `pkgver` and checksums in
+   `packaging/aur/PKGBUILD`, then run `updpkgsums` and
+   `makepkg --printsrcinfo > .SRCINFO` before pushing to the AUR repository.
+
+## Style
+
+- `ruff check src tests tools` must pass.
+- `mypy src/zipcheck` must pass.
+- Line length 100.
+- Type hints on public functions.
+- Comments explain *why*, not *what*.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for how to report parser vulnerabilities
+privately.

zipcheck-0.1.0/Dockerfile

@@ -0,0 +1,26 @@
+# Small, non-root image for scanning untrusted archives.
+#
+#   docker build -t zipcheck .
+#   docker run --rm -v "$PWD:/data:ro" zipcheck /data/file.zip
+#
+# The container only needs the archive mounted read-only. zipcheck never writes
+# extracted data, so the filesystem can be read-only as well:
+#
+#   docker run --rm --read-only -v "$PWD:/data:ro" zipcheck /data/file.zip
+
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE /app/
+COPY src /app/src
+
+RUN pip install --no-cache-dir .
+
+RUN useradd --create-home --shell /usr/sbin/nologin scanner
+USER scanner
+
+ENTRYPOINT ["zipcheck"]

zipcheck-0.1.0/LICENSE

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

zipcheck-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include CHANGELOG.md
+include CONTRIBUTING.md
+include Dockerfile
+include SECURITY.md
+include .dockerignore
+recursive-include docs *.md
+recursive-include fuzz *.py
+recursive-include packaging *
+recursive-include tests *.py
+recursive-include tools *.py