Skip to content
TPOALOSPublic

About

Inspect zip/tar archives for zip-slip, hostile links, special files, setuid and bombs without extracting (stdlib-only Python)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

zipcheck

Look inside an archive before you unpack it. Extracting an untrusted .zip or .tar.gz can write files outside the target folder (../../x, /etc/x, C:\x), follow a symlink planted earlier in the same archive, create device nodes or setuid binaries, or expand a few kilobytes into gigabytes. zipcheck reads only the archive headers and reports every suspicious member. It never extracts anything and never runs anything it finds.

$ zipcheck good.zip
good.zip: zip, 1 members, 2 bytes declared uncompressed
  clean
$ zipcheck evil.zip evil.tar.gz
evil.zip: zip, 6 members, 5242892 bytes declared uncompressed
  HIGH   path-traversal         [#1 ../../outside.txt] '..' components climb above the extraction root
  HIGH   symlink-escape         [#2 link] symlink -> '/etc': absolute target
  HIGH   write-through-symlink  [#3 link/passwd] path passes through symlink 'link' that points outside the root
  MEDIUM windows-reserved-name  [#4 CON.txt] component 'CON.txt' is a reserved Windows device name
  HIGH   bomb-member-ratio      [#5 zeros.bin] declared 5242880 bytes from 5110 compressed (ratio over 100)
  HIGH   bomb-ratio             overall ratio 914:1 (5242892 bytes from a 5736 byte archive) exceeds 100:1
evil.tar.gz: tar.gz, 4 members, 14 bytes declared uncompressed
  HIGH   setuid                 [#0 app/run.sh] setuid bit set (mode 4755)
  HIGH   device-file            [#1 app/dev] character/block device node
  HIGH   hardlink-escape        [#2 app/hl] hardlink -> '/etc/shadow': absolute target

One file, standard library only, Python 3.9+. Member numbers (#N) start at 0 in archive order.

Usage

python3 zipcheck.py ARCHIVE [ARCHIVE ...]
python3 zipcheck.py --json --min-severity medium upload.tar.gz

Formats (detected by content, not file extension): zip, tar, tar.gz/tgz, tar.bz2, tar.xz.

Option Meaning
--json machine-readable report (one object per archive, findings with rule, severity, member, index, detail)
--min-severity {low,medium,high} hide findings below this level
--max-total SIZE flag declared uncompressed total above this (default 1G)
--max-ratio N flag compression ratio above N:1 (default 100; ignored for outputs under 1 MiB)
--max-members N flag more than N members (default 10000)
--max-scan SIZE hard cap on decompressed bytes read from a tar stream (default 1G)
--scan-members N hard cap on members enumerated (default 200000)
--max-findings N keep at most N findings per archive (default 1000)

What it reports

Severity Rules
HIGH path-traversal, absolute-path, drive-letter, symlink-escape, hardlink-escape, write-through-symlink (via an escaping link), device-file, setuid, setgid, bomb-total-size, bomb-ratio, bomb-member-ratio, overlapping-entries
MEDIUM duplicate-name, windows-reserved-name, control-char, spoofing-char (bidi override, zero-width), special-file (FIFO, socket), empty-name, empty-link-target, link-unreadable, write-through-symlink (via an internal link), bomb-member-count, scan-truncated
LOW case-collision, dotdot-component (stays inside the root), windows-invalid-name, long-name, nested-archive, encrypted-member

Backslashes count as path separators, because extractors on Windows treat them that way. File names are printed with control characters escaped, so a hostile name cannot inject terminal escape sequences into the report.

How it stays safe on hostile input: zip members are never decompressed except symlink targets (at most 4096 bytes); tar streams are read through a decompressor with a byte cap (--max-scan) and a refusal of oversized header reads; the zip central directory is size-checked before it is parsed; xz memory is limited to 256 MiB; non-regular input files (FIFOs, devices, directories) are refused.

Exit codes

  • 0 every archive inspected and clean
  • 1 findings
  • 2 usage error, or an archive could not be read or fully inspected (corrupt, unknown format, truncated). This takes precedence over 1; the findings gathered so far are still printed.

Limits

zipcheck is a pre-extraction check, not a guarantee.

  • Sizes are what the headers claim. A zip entry can declare a small size and decompress to more; zipcheck does not decompress members to verify (that is the point), so extract with your own size limits as well. Tar sizes are structural and reliable, but the decompressed scan is capped, and hitting the cap is reported as scan-truncated, not as clean.
  • Nested archives are flagged, not opened. Scan the inner archives separately.
  • Symlink chains are not resolved. Only each link's own target is checked, plus later members written through it.
  • Encrypted zip members cannot be inspected beyond their headers. Formats other than the five above (7z, rar, zstd) are not supported.
  • It does not look at file contents (malware, scripts, zip files in disguise) and does not judge whether your extractor is safe. Python's own tarfile data filter or unzip -n into a scratch directory are still good habits.
  • Ratio and size thresholds are heuristics; legitimate archives of logs or zeros can trip them. Tune with --max-ratio / --max-total.
  • Name checks follow Windows, macOS and Linux conventions in general, not any one extractor's exact rules.

Tests

python3 -m unittest -v

All archives in the tests are built in memory or in a temp folder from zipfile and tarfile, with malicious headers crafted by hand.

License

MIT (c) TPOALOS


More tools by TPOALOS: csvguard · trojansrc · all 51 tools

About

Inspect zip/tar archives for zip-slip, hostile links, special files, setuid and bombs without extracting (stdlib-only Python)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages