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.
python3 zipcheck.py ARCHIVE [ARCHIVE ...]
python3 zipcheck.py --json --min-severity medium upload.tar.gzFormats (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) |
| 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.
0every archive inspected and clean1findings2usage error, or an archive could not be read or fully inspected (corrupt, unknown format, truncated). This takes precedence over1; the findings gathered so far are still printed.
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
tarfiledatafilter orunzip -ninto 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.
python3 -m unittest -vAll archives in the tests are built in memory or in a temp folder from zipfile and tarfile, with malicious headers crafted by hand.
MIT (c) TPOALOS
More tools by TPOALOS: csvguard · trojansrc · all 51 tools