ZIPDOCK Read-only archive inspector and safety scanner Techlosoft "Archive Vault" product line WHAT ZIPDOCK IS FOR ------------------- Somebody sent you an archive. Before you unpack it into your home directory or onto a build server, you would like to know what is inside it and whether unpacking it is going to hurt. zipdock answers that question without unpacking anything. It opens the archive read-only, walks the metadata, and reports what it finds. It is the inspection half of the Archive Vault line: its siblings VaultZip and ArchiveGuard produce archives, zipdock examines archives that arrived from somewhere else. THE FOUR COMMANDS ----------------- zipdock info [--json] Detect the format from magic bytes and summarise: format, size on disk, entry count split into files and directories, total compressed size, total uncompressed size, overall compression ratio. zipdock list [--json] One line per entry: path, uncompressed size, compressed size, per-entry ratio, modified time, whether it is a directory. For zip entries also the CRC32 recorded in the central directory and the compression method name (Store, Deflate, BZip2, LZMA, Zstandard, ...). For tar entries also the link type and link target. Sizes are printed as raw byte counts so they line up with "unzip -l", "unzip -v" and "tar -tvf" without any arithmetic. zipdock scan [--max-ratio N] [--max-total SIZE] [--json] The safety report. Five named checks, each PASS, WARN or FAIL: ZIP BOMB Any entry, or the archive as a whole, whose uncompressed:compressed ratio exceeds --max-ratio (default 100), or whose total uncompressed size exceeds --max-total (default 1GiB). A ratio inside 20% of the threshold is a WARN rather than a FAIL. PATH TRAVERSAL Entries that would write outside the directory you extract into: ".." segments anywhere in the path, absolute paths ("/etc/passwd"), Windows drive letters ("C:\..."). This is the "zip slip" class of bug. Backslash separators are a WARN on their own. SYMLINK ENTRIES tar symlink and hardlink members. A link whose target resolves outside the archive is a FAIL; a link that stays inside is a WARN, because an extractor that follows links can still be steered. NAME COLLISIONS Two entries that resolve to the same path is a FAIL (the second silently overwrites the first). Two entries that differ only in letter case is a WARN, because they collide on Windows and on the default macOS filesystem but not on Linux. SUSPICIOUS NAMES Control characters in a name is a FAIL. Trailing dots or spaces on a path component, reserved Windows device names (CON, NUL, COM1 ...), and names that are not valid UTF-8 are WARNs. Exit status is 2 if any check FAILs, 0 otherwise. WARNs do not change the exit status. zipdock verify [--json] Integrity checking, without writing anything anywhere. zip Every entry is decompressed in a streaming fashion straight into a CRC32 hash and discarded. The computed CRC32 is compared against the CRC32 stored in the central directory, and the byte count against the stored uncompressed size. Mismatches are reported by entry name. gzip The whole stream is decompressed into a hash and discarded; the trailing CRC32 and ISIZE are checked against it. tar tar carries no per-entry content checksum, so zipdock checks header checksums, structural integrity and declared sizes against the bytes actually present. For .tar.gz and .tar.bz2 the container's CRCs are checked as well. bzip2 Per-block CRCs are validated by the decompressor. Exit status is 2 on any mismatch. OPTIONS ------- --json Machine-readable output. Every command supports it. --max-ratio N Ratio threshold for scan. Default 100. --max-total SIZE Total uncompressed size threshold for scan. Default 1GiB. Accepts 500, 500B, 64K, 10MB, 2GiB. Both the KB and KiB spellings mean 1024 bytes. -h, --help, help Usage text. Flags may appear before or after the archive path; both orders work. FORMATS ------- Detected from magic bytes, never from the file extension. A zip renamed to .tar is still read as a zip, and a file with a misleading name is reported for what it actually is. zip PK\x03\x04 / PK\x05\x06 / PK\x07\x08 gzip \x1f\x8b bzip2 BZh tar "ustar" at offset 257 tar.gz gzip magic wrapping a tar header tar.bz2 bzip2 magic wrapping a tar header EXIT CODES ---------- 0 Success. scan found no FAILs; verify found no mismatches. 1 Usage error, unreadable file, unrecognised or damaged format. 2 scan produced at least one FAIL, or verify found a checksum mismatch. WHAT IS IMPLEMENTED ------------------- - Magic-byte format detection for zip, tar, tar.gz, gzip, tar.bz2, bzip2. - Full entry enumeration with sizes, ratios, timestamps, directory flags. - zip CRC32 and compression method from the central directory. - tar link type and link target. - All five scan checks described above, with configurable thresholds. - Real CRC32 verification of zip entries by streaming decompression. - gzip trailer CRC32/ISIZE verification. - JSON output for all four commands. - A hard internal limit on how much decompressed data will be pulled through a compressed container while enumerating it, so that a hostile archive cannot make the inspector itself run forever. WHAT IS NOT IMPLEMENTED ----------------------- Being explicit about this, because a safety tool that overstates its coverage is worse than no tool at all. - zipdock DOES NOT EXTRACT. There is no extract command and no flag that turns one on. Nothing is ever written to disk: decompressed bytes go to a hash function and are discarded. - zipdock DOES NOT CREATE OR MODIFY ARCHIVES. Files are opened read-only. Creating archives is VaultZip's job; sealing and shredding is ArchiveGuard's job. - No 7z, rar, xz, zstd, lz4, cab, iso or ar support. Those need external libraries or a large amount of new format code; zipdock is built on the Go standard library only. Such a file is reported as an unrecognised format, not silently mis-parsed. - No encrypted-zip handling. Encrypted entries are listed like any other, but zipdock will not detect that they are encrypted and cannot verify their CRC32 without the password. - No recursion into nested archives. A zip inside a zip is one opaque entry; its contents are not scanned. - No multi-volume or spanned archives, and no zip files with a prepended self-extracting stub. - Multi-member gzip streams are decompressed correctly, but the trailer CRC shown by verify is the final member's. - tar entries cannot be content-verified. The format simply does not carry a per-entry content checksum; anyone claiming otherwise is guessing. - scan reports risk; it does not rank it, score it, or decide for you. ROADMAP ------- 1. Safe sandboxed extraction. An "extract" command that refuses anything the scanner FAILs, sanitises every path against the destination root, drops symlink and device entries, and enforces --max-total as it writes rather than only reporting on it afterwards. 2. Encrypted-zip detection and password handling. Read the general-purpose bit flag to identify encrypted entries, distinguish legacy ZipCrypto from AES, and accept a password so that verify can check those entries too. This is the natural bridge to VaultZip, which produces AES-256-GCM archives. 3. Recursive scanning of nested archives. Walk into archives found inside archives, to a configurable depth, so that a bomb or a traversal entry hidden one layer down is still reported. Depth and cumulative expansion budget will both be capped. BUILDING -------- go build -o zipdock . Go standard library only. No third-party modules, no network access needed at build time. EXAMPLES -------- zipdock info incoming.zip zipdock list incoming.tar.gz --json zipdock scan incoming.zip --max-ratio 50 --max-total 200MB zipdock scan incoming.zip --json && echo "safe to unpack" zipdock verify incoming.zip