README_EN.md

ZipCracker (New Version) — User Guide

中文

ZipCracker is a comprehensive ZIP cracking and recovery tool developed by Team Hx0. It is a strong fit for common ZIP challenges in CTF, as well as authorized security testing and recovering your own encrypted backups. It combines pseudo-encryption detection and repair, dictionary attacks, mask attacks, short-plaintext CRC32 preimage search, and known-plaintext attack (KPA) into one workflow, with fast loading of huge wordlists, multi-threaded scheduling, and automatic extraction after success so you can analyze and recover ZIPs efficiently.

Use ZipCracker_en.py for English UI; ZipCracker.py is the Chinese UI. Both call the same core.

Main capabilities at a glance:

• Pseudo-encryption detection and repair
• Standard dictionary attacks
• Custom wordlist file or directory of wordlists
• Mask attacks
• Short-plaintext recovery via CRC32 enumeration (1–6 byte entries)
• Known-plaintext attack (-kpa)
• Auto-extract after a successful crack

If you are new here, these three sections are enough to get started:

1. Quick start
2. Common usage
3. FAQ

Quick start

Typical first commands:

# 1. Pseudo-encryption check and repair
python3 ZipCracker_en.py test01.zip

# 2. Default dictionary attack
python3 ZipCracker_en.py test02.zip

# 3. Known-plaintext attack
python3 ZipCracker_en.py test05.zip -kpa test05_plain.txt

# 4. Huge wordlist (recommended)
ZIPCRACKER_SKIP_DICT_COUNT=1 python3 ZipCracker_en.py target.zip huge_dict.txt

Runtime environment

Item	Notes
Python	Minimum Python 3.7; Python 3.10+ recommended
OS	Linux / macOS / Windows
Required	Python standard library only
Optional	pyzipper — AES ZIP support
Optional	bkcrack — faster KPA recovery when applicable

If you see:

TypeError: 'type' object is not subscriptable

your Python is likely too old. Check:

python --version

Upgrade to Python 3.10+ when possible.

Optional dependencies

1. pyzipper

Used for AES ZIP entries.

Behavior:

• If installed, AES support is enabled automatically.
• If missing, the script may prompt to install; you can enter n to skip.
• In Chinese UI mode, one-key install prefers the Tsinghua PyPI mirror and falls back to the official index.

Manual install (example):

python3 -m pip install pyzipper

If the archive uses AES, the script also reminds you that:

1. AES verification and extraction are usually much slower than legacy ZipCrypto.
2. Without pyzipper, AES entry checks or extraction may fail — install it first when dealing with AES.

2. bkcrack

Mainly used for dictionary-free recovery during -kpa known-plaintext attacks.

Behavior:

• If bkcrack is detected, a faster path is tried first.
• If not found, the script suggests how to install it for your OS; n skips and other methods continue.
• If you pass --bkcrack, bkcrack is required; the program exits if it is not available.

On Windows, if runtime libraries are missing, the program prints:

• Microsoft docs: Latest supported VC++ Redistributable
• Direct download links for your architecture

Common usage

1. Pseudo-encryption detection and repair

python3 ZipCracker_en.py test01.zip

2. Default dictionary attack

python3 ZipCracker_en.py test02.zip

By default it tries, in order:

1. password_list.txt
2. Numeric passwords from 1 to 6 digits

If you run:

python3 ZipCracker_en.py your.zip

and the usual paths fail, the tool also looks inside the archive for entries that look like template KPA candidates (e.g. png, zip, exe, pcapng). When confidence is high enough, it may ask whether to switch to template KPA mode automatically.

Example:

python3 ZipCracker_en.py test06_image.zip

3. Custom wordlists

Single file:

python3 ZipCracker_en.py test02.zip YourDict.txt

Directory of wordlists (tried in sequence):

python3 ZipCracker_en.py test02.zip YourDictDirectory

4. Short-plaintext CRC32 enumeration

For ZIP entries 1–6 bytes long, the tool can enumerate printable plaintexts whose CRC32 matches the stored value. When a candidate matches, the terminal prompts whether to proceed.

python3 ZipCracker_en.py test03.zip

5. Mask attack

python3 ZipCracker_en.py test04.zip -m '?uali?s?d?d?d'

Mask placeholders:

Placeholder	Meaning
?d	Digits 0-9
?l	Lowercase a-z
?u	Uppercase A-Z
?s	Special characters
??	Literal ?

6. Known-plaintext attack (-kpa)

Tries bkcrack first when available, then falls back to dictionary/mask flows:

python3 ZipCracker_en.py test05.zip -kpa test05_plain.txt

If you have an unencrypted reference ZIP instead of a loose file:

python3 ZipCracker_en.py C.zip -kpa M.zip

Notes:

1. After -kpa you can pass either a normal file or a passwordless ZIP.
2. If you pass a ZIP, the tool prefers an entry with the same name as in the target.
3. If you pass a plain file, it still prefers same-name matching inside the target ZIP.
4. If the plaintext ZIP contains only one normal file, that file is used automatically.

Important:

• In ZIP known-plaintext attacks, “plaintext” means the byte stream before ZipCrypto encryption, not necessarily the original extracted file.
• If the target entry is ZIP_STORED, the original file can usually be used directly as -kpa input.
• If the target entry is ZIP_DEFLATED / ZIP_BZIP2 / ZIP_LZMA, the encrypted bytes are usually the compressed data stream. Passing the uncompressed original file may lead to ciphertext is smaller than plaintext.
• --kpa-offset only describes where known bytes start inside the pre-encryption byte stream; it cannot map an uncompressed file to compressed data.
• See the bilingual note in docs/KPA_KNOWN_PLAINTEXT_NOTE.md.

Force a specific entry inside the target ZIP:

python3 ZipCracker_en.py test05.zip -kpa test05_plain.txt -c test05_plain.txt

Partial plaintext — offset and extra known bytes:

python3 ZipCracker_en.py secret.zip -kpa part.bin --kpa-offset 78 -x 0 4d5a

Notes:

1. --kpa-offset — start offset of this plaintext inside the target file.
2. -x — extra known bytes: -x <offset> <hex> (repeatable).
3. Shorthand: -x 0:4d5a.

Built-in file-header templates:

python3 ZipCracker_en.py target.zip --kpa-template png -c image.png
python3 ZipCracker_en.py target.zip --kpa-template exe -c app.exe
python3 ZipCracker_en.py target.zip --kpa-template pcapng -c capture.pcapng
python3 ZipCracker_en.py target.zip --kpa-template zip -c inside.zip

Available templates: png, zip, exe, pcapng.

bkcrack only:

python3 ZipCracker_en.py test05.zip -kpa test05_plain.txt --bkcrack

Difference:

• -kpa — if bkcrack fails, other methods can still run.
• -kpa --bkcrack — only bkcrack; stop if it fails.

7. Output directory

python3 ZipCracker_en.py test02.zip -o output_dir

Huge wordlists

ZipCracker can handle very large wordlists without loading the entire file into memory.

For 10GB+ lists, skip the pre-count pass:

ZIPCRACKER_SKIP_DICT_COUNT=1 python3 ZipCracker_en.py your.zip your_big_dict.txt

Benefits:

1. Faster startup
2. Lower, steadier memory use
3. Progress switches to streaming mode (by bytes read)

FAQ

1. Why is AES so slow?

That is normal. AES password checks and decryption are usually much slower than ZipCrypto. The script warns you when AES is detected.

2. What if pyzipper is not installed?

For AES entries, without pyzipper:

1. The script may prompt you to install (or skip with n).
2. Verification or extraction of AES entries may fail.

Safest approach: install first.

python3 -m pip install pyzipper

3. Windows: CERTIFICATE_VERIFY_FAILED when installing bkcrack

This is usually Python HTTPS certificate verification, not “GitHub is blocked” alone.

The script tries, in order: Python’s downloader, then curl.exe on Windows, then PowerShell.

If it still fails, check:

1. System clock accuracy
2. Proxies, gateways, or AV intercepting HTTPS
3. Whether a browser can open the GitHub release page

4. Windows: bkcrack exit code 3221225477

Hex:

0xC0000005

This is an Access Violation — bkcrack.exe crashed. It is usually not “wrong password”. Try:

set BKCRACK_JOBS=1
python ZipCracker_en.py test05.zip -kpa test05_plain.txt

Also try:

1. Install or repair Microsoft Visual C++ Redistributable
2. Temporarily disable AV or allowlist bkcrack.exe
3. If it still crashes, prefer WSL / Linux for bkcrack

5. Fan still spinning after extraction succeeded?

The script may still be trying to recover the original ZIP password after a successful extract.

To skip that:

ZIPCRACKER_SKIP_ORIG_PW_RECOVERY=1 python3 ZipCracker_en.py test05.zip -kpa test05_plain.txt

6. Huge wordlist looks idle at first?

By default the script counts total candidates first. For faster startup:

ZIPCRACKER_SKIP_DICT_COUNT=1 python3 ZipCracker_en.py your.zip your_big_dict.txt

Common environment variables

Variable	Effect
ZIPCRACKER_SKIP_DICT_COUNT=1	Skip pre-count for huge wordlists
ZIPCRACKER_SKIP_ORIG_PW_RECOVERY=1	After KPA extract, do not keep recovering the original ZIP password
ZIPCRACKER_AUTO_INSTALL_PYZIPPER=0	Skip automatic pyzipper install prompts
ZIPCRACKER_AUTO_INSTALL_BKCRACK=0	Skip automatic bkcrack install prompts
BKCRACK_JOBS=1	Lower bkcrack thread count (useful on Windows)

Special Acknowledgments

Thanks to LANDY for support and feedback on this project.

ClawHub AI skill integration (New!)

ZipCracker is listed on the ClawHub skill hub. In OpenClaw you can invoke it with natural language so the assistant builds and runs decrypt/crack flows — handy for CTF and authorized self-checks.

Skill page: https://clawhub.ai/asaotomo/zipcracker

Install: Set up the ClawHub client, then run:

clawhub install zipcracker

Then you can say things like: “Crack this ZIP with ZipCracker, try a mask of four digits,” and the assistant will construct the right command.

Disclaimer

Use this tool only where you have legal permission, for example:

• CTF / practice ranges
• Recovering your own data
• Authorized security testing

Do not use it for unauthorized access or other illegal purposes.

---

Support with tips — The code is open source; every bit of help keeps the project going.

Team official account — Follow for updates.

Team knowledge planet