{"id":27854250,"url":"https://github.com/glooring/archive-password-cracker","last_synced_at":"2025-05-04T09:01:17.572Z","repository":{"id":289408695,"uuid":"971157939","full_name":"Glooring/archive-password-cracker","owner":"Glooring","description":"A high-performance archive password cracker with Python/CustomTkinter GUI \u0026 C++ core. Supports brute-force, pattern matching, and state persistence (skip list).","archived":false,"fork":false,"pushed_at":"2025-04-23T05:37:50.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T06:20:00.809Z","etag":null,"topics":["7zip","archive","bloom-filter","brute-force","cli","customtkinter","gui-app","multi-threading","password-cracker","pattern-matching","rar","security-tools"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Glooring.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-23T05:25:35.000Z","updated_at":"2025-04-23T05:37:53.000Z","dependencies_parsed_at":"2025-04-23T06:30:08.812Z","dependency_job_id":null,"html_url":"https://github.com/Glooring/archive-password-cracker","commit_stats":null,"previous_names":["glooring/archive-password-cracker"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glooring%2Farchive-password-cracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glooring%2Farchive-password-cracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glooring%2Farchive-password-cracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glooring%2Farchive-password-cracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Glooring","download_url":"https://codeload.github.com/Glooring/archive-password-cracker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252310952,"owners_count":21727516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["7zip","archive","bloom-filter","brute-force","cli","customtkinter","gui-app","multi-threading","password-cracker","pattern-matching","rar","security-tools"],"created_at":"2025-05-04T09:00:38.350Z","updated_at":"2025-05-04T09:01:17.498Z","avatar_url":"https://github.com/Glooring.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔐 Archive Password Cracker (Python GUI + C++ Core + Pattern Matching + State Persistence)\r\n\r\nA high-performance, multi-threaded archive password cracker featuring a **modern Python GUI** (built with CustomTkinter) controlling a robust **C++ backend** for maximum cracking speed. It supports standard brute-force attacks within a defined character set and length range, **pattern matching** to target specific password structures, and utilizes the external 7-Zip command-line tool (`7z.exe`/`7z`) for efficient password verification against various archive types (ZIP, 7z, RAR, etc.). Crucially, it includes **state persistence** using a Bloom filter (`skip_list.bf`) to avoid re-testing previously tried passwords across sessions, even for interrupted runs.\r\n\r\nThis hybrid architecture leverages the strengths of both languages:\r\n*   **Python/CustomTkinter:** Provides a sleek, user-friendly, and configurable interface. It handles user input (charset, min/max length, pattern, cracking mode, skip list usage), loads default settings from JSON files, manages the C++ process lifecycle (including graceful stops via a flag file), displays real-time progress, and provides controls for managing the skip list state. Includes enhancements like drag-and-drop, undo/redo, dynamic UI updates for pattern matching, and high-DPI support.\r\n*   **C++:** Executes the computationally intensive password generation and testing logic. It uses native multi-threading (`std::thread`) for parallel processing across CPU cores and efficient OS primitives (`CreateProcessW`/`fork`) for launching 7-Zip, minimizing overhead. Supports multiple cracking strategies (ascending, descending, pseudo-random) within the specified constraints (length range or pattern). Implements **pattern-based password generation** and validation. Includes a **Bloom filter** for efficient tracking of tested passwords, with optional **checkpointing** for resilience and a **stop flag mechanism** for graceful termination and state saving. Robustly handles large search spaces and potential memory allocation limits for the Bloom filter.\r\n\r\n---\r\n\r\n### GUI Preview\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"doc/screenshots/window.png\" alt=\"GUI\" width=\"450\"/\u003e\r\n\u003c/p\u003e\r\n\u003cp align=\"center\"\u003e\u003cem\u003eScreenshot of Archive Password Cracker GUI\u003c/em\u003e\u003c/p\u003e\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n1.  [Overview](#overview)\r\n2.  [Features](#features)\r\n    *   [Core Functionality](#core-functionality)\r\n    *   [GUI Enhancements](#gui-enhancements-python)\r\n3.  [How it Works](#how-it-works)\r\n4.  [Pattern Matching Syntax](#pattern-matching-syntax)\r\n5.  [Project Structure](#project-structure)\r\n6.  [Requirements](#requirements)\r\n7.  [Setup Instructions](#setup-instructions)\r\n    1.  [Get the Code](#1-get-the-code)\r\n    2.  [Install 7-Zip](#2-install-7-zip)\r\n    3.  [Compile the C++ Backend](#3-compile-the-c-backend)\r\n    4.  [Place C++ Executable](#4-place-c-executable)\r\n    5.  [Install Python Dependencies](#5-install-python-dependencies)\r\n    6.  [(Optional) Edit Default Values](#6-optional-edit-default-values)\r\n8.  [Usage](#usage)\r\n9. [Building](#building)\r\n    1.  [Building the C++ Backend (CLI)](#building-the-c-backend-cli)\r\n    2.  [Building the Python GUI Standalone Executable](#building-the-python-gui-standalone-executable)\r\n10. [License](#license)\r\n11. [Acknowledgements](#acknowledgements)\r\n\r\n---\r\n\r\n## Overview\r\n\r\nThis tool attempts to find the password for encrypted archive files using a multi-threaded approach. Users can define a character set (`Charset`), a **minimum (`Min Length`)** and **maximum (`Max Length`)** password length for standard brute-force, or enable **Pattern Matching** to specify the exact structure of the passwords to test. A cracking `Mode` (Ascending, Descending, Pseudo-Random) dictates the generation order.\r\n\r\n---\r\n\r\n**Key Architecture \u0026 Features:**\r\n\r\n*   **Python GUI (`archive_password_cracker.py`):** Manages the user interface, loads defaults (from `helpers/json/`), gathers settings, validates input (including dynamic adjustments based on pattern matching), launches the C++ backend process, reads its output in real-time via separate threads, and updates the log display without blocking the UI. Controls the skip list feature and provides a button to clear its state. Creates the `.stop` flag for graceful termination.\r\n*   **C++ Backend (`helpers/ArchivePasswordCrackerCLI.exe`):** A command-line application that receives the charset, min/max length, archive path, cracking mode, and optional skip list/pattern parameters as arguments.\r\n    *   It finds the required `7z` executable (expected in `helpers/bin/`).\r\n    *   **Pattern Handling:** If the `--pattern` argument is provided, it parses the pattern and generates only passwords matching that specific structure, adjusting length constraints automatically.\r\n    *   **Standard Brute-Force:** If no pattern is provided, it generates passwords sequentially or randomly within the specified `Min Length` and `Max Length`.\r\n    *   Spawns multiple worker threads for parallel processing.\r\n    *   **Skip List:** If enabled (`--skip-file \u003cpath\u003e`), it loads/creates a **Bloom filter** (`helpers/skip_list.bf`). Before testing a password, it checks the filter (`contains()`). If potentially seen, it skips the test. If tested and fails, it's added (`insert()`). Includes checks to prevent creating excessively large filters that might exhaust memory.\r\n    *   **Checkpointing:** If enabled (`--checkpoint-interval \u003cseconds\u003e`), the Bloom filter state is periodically saved (`serialize()`).\r\n    *   **Graceful Stop:** Monitors for a `.stop` flag file (`helpers/skip_list.bf.stop`). If detected, sets an internal flag, ensures worker threads terminate, triggers a final save of the Bloom filter state (if valid and enabled), and terminates the cracking process cleanly.\r\n    *   Efficiently calls the 7-Zip process (`tryPassword`) to verify each password candidate.\r\n    *   Status messages and the final result (if found) are printed to standard output for the Python GUI to capture.\r\n\r\nThis separation ensures the UI remains responsive while the C++ backend utilizes CPU resources effectively, with the added benefits of targeted pattern attacks and persistent state to avoid redundant work.\r\n\r\n---\r\n\r\n## Features\r\n\r\n### Core Functionality\r\n\r\n| Category              | Feature                                       | Details                                                                                                                                                            |\r\n| :-------------------- | :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| **✨ GUI (Python)**    | Modern Interface                          | Built with CustomTkinter (Dark/Light themes). High-DPI aware.                                                                                                     |\r\n|                       | Configurable Defaults                     | Loads initial Charset, Min/Max Length, Archive Path from `helpers/json/*.json`.                                                                                   |\r\n|                       | **Versatile Generation**                  | Supports both **Length Range (Min/Max)** brute-force and targeted **Pattern Matching**.                                                                           |\r\n|                       | **Pattern Control**                       | Checkbox to enable pattern mode. Dedicated input field for the pattern string. Dynamically enables/disables Min/Max Length fields based on pattern content (`*`). |\r\n|                       | **Mode Selection**                        | Choose cracking strategy: **Ascending**, **Descending**, or **Pseudo-Random**. Applies to length range or pattern generation where applicable.                     |\r\n|                       | **Skip List Management**                  | Checkbox to enable/disable skipping previously tried passwords (`helpers/skip_list.bf`). Button to clear the stored skip list state.                                |\r\n|                       | Live Output Log                           | Displays real-time, timestamped status/results from the C++ backend.                                                                                              |\r\n|                       | Responsive Controls                       | Run/Stop buttons control the C++ backend; UI remains interactive. Graceful stop via flag file.                                                                     |\r\n|                       | Input Validation                          | Checks lengths, charset, archive path, pattern interactions, preventing invalid C++ calls.                                                                       |\r\n| **⚡ Core (C++)**     | **High Performance**                      | Native C++ speed, `std::thread` parallelism, efficient OS process calls (`CreateProcessW`/`fork`).                                                               |\r\n|                       | **Pattern Matching Engine**               | Parses patterns (`?`, `*`, `\\\\`), generates candidates matching the exact structure. Handles fixed vs. variable length patterns.                                  |\r\n|                       | **Standard Brute-Force**                  | Efficiently generates passwords within Min/Max length range if no pattern is specified.                                                                          |\r\n|                       | **Multiple Cracking Modes**               | Implements Ascending, Descending, and Pseudo-Random strategies for both standard and applicable pattern modes.                                                  |\r\n|                       | **State Persistence (Skip List)**         | Uses a **Bloom Filter** (`bloom_filter.h/.cpp`) to efficiently track tested passwords (low memory, fast checks) via `helpers/skip_list.bf`.                           |\r\n|                       |                                               | Loads state if `--skip-file` is used. Skips known attempts (`contains()`). Adds new failures (`insert()`).                                                         |\r\n|                       | **Memory Safety**                         | Checks estimated Bloom filter size against a limit (`MAX_FILTER_BITS`) before allocation to prevent excessive memory usage; disables skip list if limit exceeded. |\r\n|                       | **Checkpointing**                         | Periodically saves Bloom filter state (`serialize()`) if `--checkpoint-interval` is used.                                                                        |\r\n|                       | **Graceful Stop \u0026 Resume**                | Checks for `.stop` flag file. Saves valid skip list state on stop/completion, allowing continuation.                                                               |\r\n|                       | Efficient 7-Zip Integration               | Directly calls `7z.exe`/`7z` for password verification. Finds `7z` in `helpers/bin/`.                                                                          |\r\n|                       | Robust Random Mode                        | Uses `std::shuffle` with a non-deterministic seed for standard and pattern-based random modes (where applicable).                                             |\r\n| **⚙️ Architecture**    | **Hybrid Design**                         | Python UI/Management + C++ Performance/Logic.                                                                                                                      |\r\n|                       | Process Communication                     | Python `subprocess` launches C++, passes config via args, reads `stdout`/`stderr` via threads.                                                                     |\r\n|                       | Clear Separation                          | GUI and cracking logic are distinct processes.                                                                                                                   |\r\n|                       | Robust Error Handling                     | Detects missing backend/7z, handles invalid args, pattern issues, reports C++ exit codes (0-4+), handles Bloom filter I/O/memory errors.                      |\r\n|                       | Cross-Platform (Potential)                | C++ includes basic Linux/macOS process handling. Python GUI is cross-platform. Tested primarily on Windows.                                                        |\r\n\r\n### GUI Enhancements (Python)\r\n\r\n*   **🖱️ Drag \u0026 Drop:** Drag an archive file onto the \"Archive File\" input field (requires optional `windnd` library on Windows).\r\n*   **✍️ Undo/Redo:** Standard `Ctrl+Z` / `Ctrl+Y` / `Ctrl+Shift+Z` support on Charset, Min/Max Length, Pattern, and Archive Path fields.\r\n*   **🖼️ High DPI Support:** Adapts to high-resolution displays.\r\n*   **🧭 Dynamic UI:** Min/Max Length fields become disabled/enabled automatically based on the pattern content when Pattern Matching is active.\r\n*   **🤫 Improved Stop UX:** Correctly handles stop requests, ensures C++ saves state (if enabled), and avoids unnecessary \"Not Found\" popups.\r\n*   **💾 Log Saving:** Automatically saves the Output Log to `helpers/log.txt` on process completion or application close.\r\n\r\n---\r\n\r\n## How it Works\r\n\r\n1.  **Initialization (Python):** The GUI loads default values for Charset, Min/Max Length, Archive Path from `helpers/json/*.json`.\r\n2.  **Configuration (User):**\r\n    *   Adjusts **Charset**, **Min/Max Length**.\r\n    *   Selects **Mode** (Ascending, Descending, Pseudo-Random).\r\n    *   Selects **Archive File** (Browse or Drag \u0026 Drop).\r\n    *   Toggles **\"Exclude previously tried passwords\"** checkbox (controls skip list usage).\r\n    *   Toggles **\"Enable Pattern Matching\"** checkbox.\r\n    *   If pattern matching is enabled, enters a **Pattern** string (see [Syntax](#pattern-matching-syntax)). The GUI dynamically adjusts the Min/Max Length fields based on the pattern.\r\n3.  **Launch Backend (Python):** On \"Run C++ Backend\":\r\n    *   Python validates all inputs, including pattern constraints if enabled.\r\n    *   Constructs the C++ command: `helpers/ArchivePasswordCrackerCLI.exe \u003ccharset\u003e \u003cmin_len\u003e \u003cmax_len\u003e \u003cabs_archive_path\u003e \u003cmode\u003e`\r\n    *   Appends optional arguments:\r\n        *   If Skip List checked: `--skip-file \"helpers/skip_list.bf\" --checkpoint-interval \u003cseconds\u003e`\r\n        *   If Pattern Matching checked: `--pattern \"\u003cpattern_string\u003e\"`\r\n    *   Launches the C++ process via `subprocess.Popen`, redirecting I/O, setting CWD to `helpers/`.\r\n4.  **Execution (C++):** `ArchivePasswordCrackerCLI.exe`:\r\n    *   Parses all arguments.\r\n    *   Locates `7z.exe` in `helpers/bin/`. Reports error code `3` if not found.\r\n    *   **Skip List Setup:** If `--skip-file` used: attempts `deserialize()`. On failure/no file, calculates estimated items based on length range or pattern constraints. Checks if required filter size exceeds `MAX_FILTER_BITS`. If safe, creates a new `BloomFilter`. If unsafe or error, disables skip list for the run.\r\n    *   **Pattern Mode:** If `--pattern` used: parses the pattern (`parse_pattern`). Determines fixed length, number of wildcards. Enters pattern generation logic.\r\n    *   **Standard Mode:** If no pattern, enters standard length-based generation logic.\r\n    *   **Worker Dispatch:** Divides the work (lengths, indices, or pattern combinations) among worker threads (`numThreads`).\r\n    *   **Password Generation \u0026 Testing (Workers/Main):**\r\n        *   Generates candidate password based on mode (standard or pattern).\r\n        *   **Skip Check:** If filter enabled and valid, calls `filter-\u003econtains(pwd)`. Skips if `true`.\r\n        *   **7-Zip Test:** If not skipped, calls `tryPassword()` to invoke `7z`.\r\n        *   **Filter Update:** If filter enabled/valid and `tryPassword` fails, calls `filter-\u003einsert(pwd)` (thread-safe via mutex).\r\n        *   **Stop Check:** Periodically checks `stop_flag_exists()`. If true, sets atomic `stop_requested` flag and worker exits its loop.\r\n    *   **Checkpointing:** Main thread periodically calls `checkpoint_filter_func` to save valid filter state via `serialize()` if interval elapsed.\r\n    *   **Output:** Prints status (INFO, WARN, ERROR). If password found, prints `FOUND:the_password`.\r\n    *   **Termination:** Exits with code `0` (found), `1` (not found/exhausted), `2` (args error), `3` (7z missing), `4` (path error). Crucially, before exiting (if stopped or found), performs a final check and calls `filter-\u003eserialize()` if the filter is valid and enabled.\r\n5.  **Real-time Logging (Python):** Background threads read C++ `stdout`/`stderr`.\r\n6.  **GUI Update (Python):** Lines displayed in the log text box via `app.after`.\r\n7.  **Result Parsing (Python):** Watches for `FOUND:`.\r\n8.  **Monitoring (Python):** `_monitor_process` polls for C++ process exit.\r\n9.  **Completion/Stop (Python):**\r\n    *   **Normal/Found:** `_monitor_process` detects exit, shows popups (unless stopped by user), saves log, re-enables UI.\r\n    *   **Manual Stop:** User clicks \"Stop\". Python sets `stopped_by_user = True`, creates `helpers/skip_list.bf.stop`. C++ detects flag, saves state (if valid/enabled), exits. Python removes flag. `_monitor_process` cleans up UI *without* final result popups.\r\n    *   **Clear Skip List:** Deletes `helpers/skip_list.bf` after confirmation.\r\n\r\n---\r\n\r\n## Pattern Matching Syntax\r\n\r\nWhen \"Enable Pattern Matching\" is checked, the **Pattern** field accepts a string defining the password structure:\r\n\r\n*   **Literal Characters:** Any character not listed below represents itself (e.g., `pass`, `123`).\r\n*   **`?` (Question Mark):** Represents exactly **one** character from the specified **Charset**.\r\n*   **`*` (Asterisk):** Represents **zero or more** characters from the specified **Charset**.\r\n    *   If a pattern contains `*`, the **Min Length** and **Max Length** fields remain active and define the total allowed password length range. The `*` will expand to fill the difference.\r\n    *   If a pattern contains **no** `*`, the password length is fixed by the pattern itself, and the Min/Max Length fields will be automatically set and disabled in the GUI.\r\n    *   **Note:** Currently, complex patterns with *multiple* `*` characters might fall back to simpler generation modes in the C++ backend (specifically, random mode is disabled, and index-based generation relies on single `*` logic).\r\n*   **`\\` (Backslash):** Escapes the next character. Use `\\?`, `\\*`, or `\\\\` to match a literal question mark, asterisk, or backslash.\r\n\r\n**Examples:**\r\n\r\n| Pattern         | Charset     | Min Len | Max Len | Meaning                                                                 | Length Fields |\r\n| :-------------- | :---------- | :------ | :------ | :---------------------------------------------------------------------- | :------------ |\r\n| `pass????`      | `a-z0-9`    | 8       | 8       | \"pass\" followed by exactly 4 alphanumeric characters.                   | Disabled      |\r\n| `Test*!`        | `a-zA-Z`    | 6       | 10      | \"Test\", followed by 0 to 4 letters, ending with \"!\". (Total len 6-10) | Enabled       |\r\n| `???\\\\?*`       | `abc`       | 4       | 8       | 3 `abc` chars, literal `\\`, 1 `abc` char, 0-3 `abc` chars. (Total 4-8) | Enabled       |\r\n| `User\\?1*pass`  | `0-9`       | 9       | 12      | \"User?1\", 0-3 digits, \"pass\". (Total len 9-12)                         | Enabled       |\r\n| `abc`           | `a-z`       | 3       | 3       | Exactly \"abc\".                                                          | Disabled      |\r\n\r\n---\r\n\r\n## Project Structure\r\n\r\n```\r\narchive-password-cracker/\r\n│\r\n├── cpp_backend/              # C++ Backend Source Code\r\n│   ├── archive-password-cracker-cli-vX.Y.Z/ # Example build output folder\r\n│   │   └── ArchivePasswordCrackerCLI.exe # --\u003e Copy this to helpers/\r\n│   ├── src/\r\n│   │   ├── bloom_filter.cpp\r\n│   │   ├── bloom_filter.h\r\n│   │   ├── brute_force.cpp\r\n│   │   ├── brute_force.h\r\n│   │   └── main.cpp\r\n│   └── compile_cli.bat       # Build script for C++ backend (Windows)\r\n│\r\n├── helpers/                  # Resources \u0026 Runtime Location for C++ Backend\r\n│   ├── bin/                  # **REQUIRED:** Place 7z.exe \u0026 7z.dll here\r\n│   │   ├── 7z.dll\r\n│   │   └── 7z.exe\r\n│   ├── json/                 # Default configuration files for GUI\r\n│   │   ├── archive_file_map.json\r\n│   │   ├── charset_map.json\r\n│   │   ├── max_length_map.json\r\n│   │   └── min_length_map.json\r\n│   ├── ArchivePasswordCrackerCLI.exe # **REQUIRED:** COMPILED C++ backend\r\n│   ├── log.txt               # (Generated at runtime) Log file\r\n│   └── skip_list.bf          # (Generated at runtime) Bloom filter state\r\n│\r\n├── archive_password_cracker.py # Python GUI Application Script (RUN THIS)\r\n└── README.md                 # This file\r\n```\r\n\r\n**Key Locations \u0026 Runtime Expectations:**\r\n\r\n*   **Run Python:** `python archive_password_cracker.py` from the project root.\r\n*   **Compile C++:** Run `compile_cli.bat` inside `cpp_backend/`.\r\n*   **Place Compiled C++ Exe:** Copy the generated executable (e.g., `ArchivePasswordCrackerCLI.exe`) from the C++ build output folder into the **`helpers/`** directory.\r\n*   **Place 7-Zip:** Copy `7z.exe` and `7z.dll` (on Windows) into the **`helpers/bin/`** directory.\r\n*   **C++ Runtime:** Launched by Python, `ArchivePasswordCrackerCLI.exe` runs with its CWD set to `helpers/`. It finds 7-Zip by looking in `./bin/` (relative to itself). It reads/writes `skip_list.bf` and the `.stop` flag file in its CWD (`helpers/`).\r\n*   **Python Runtime:** Finds the C++ exe in `helpers/`. Reads JSON defaults from `helpers/json/`. Saves logs to `helpers/log.txt`. Creates the `.stop` flag file in `helpers/`.\r\n\r\n---\r\n\r\n## Requirements\r\n\r\n*   **Python:** Python 3.7+ recommended.\r\n*   **Python Libraries:**\r\n    *   `customtkinter`: Modern GUI toolkit (`pip install customtkinter`).\r\n    *   `windnd` (Optional, Windows only): For drag-and-drop support (`pip install windnd`).\r\n*   **C++ Compiler:** A modern C++ compiler supporting C++17 (e.g., g++ via MinGW/MSYS2 on Windows, clang/g++ on Linux/macOS). Must be accessible from the command line/PATH.\r\n*   **7-Zip:** The **command-line executable** (`7z.exe` + `7z.dll` on Windows, or `7z` on Linux/macOS). Required for password testing by the C++ backend.\r\n\r\n---\r\n\r\n## Setup Instructions\r\n\r\n1.  **Get the Code:** Clone the repository or download the project files, maintaining the directory structure.\r\n2.  **Install 7-Zip:**\r\n    *   Download 7-Zip from [www.7-zip.org](https://www.7-zip.org/). Ensure you get the command-line components.\r\n    *   Create a `bin` folder inside the `helpers` directory (`archive-password-cracker/helpers/bin/`).\r\n    *   Copy `7z.exe` and `7z.dll` (on Windows) into this **`helpers/bin/` folder**.\r\n3.  **Compile the C++ Backend:**\r\n    *   Open a terminal/command prompt in the `cpp_backend` directory.\r\n    *   Ensure your C++ compiler (e.g., g++) is in your system's PATH.\r\n    *   *(Windows)* If needed, edit `compile_cli.bat` to point `MINGW_ROOT` to your MinGW/MSYS2 installation directory.\r\n    *   Run the compilation script: `.\\compile_cli.bat` (Windows) or the equivalent `g++` command for your OS (see script for example). This links `main.cpp`, `brute_force.cpp`, and `bloom_filter.cpp`.\r\n4.  **Place C++ Executable:**\r\n    *   Locate the compiled executable (e.g., `ArchivePasswordCrackerCLI.exe`) inside the C++ build output folder (e.g., `cpp_backend/archive-password-cracker-cli-vX.Y.Z/`).\r\n    *   Copy this executable into the **`helpers/`** directory at the project root (`archive-password-cracker/helpers/`).\r\n5.  **Install Python Dependencies:**\r\n    *   Open a terminal in the main project root directory (`archive-password-cracker/`).\r\n    *   Run: `pip install customtkinter`\r\n    *   (Optional, Windows) Run: `pip install windnd`\r\n6.  **(Optional) Edit Default Values:**\r\n    *   Modify the content of the `.json` files inside `helpers/json/` to set your preferred default values for the GUI fields (Charset, Min Length, Max Length, Archive File). Each file should contain a JSON list with a single string element (use empty string `\"\"` for no default).\r\n\r\n---\r\n\r\n## Usage\r\n\r\n1.  Complete all **Setup Instructions**.\r\n2.  Open a terminal in the main project root directory (`archive-password-cracker/`).\r\n3.  Run the Python GUI: `python archive_password_cracker.py`\r\n4.  The application window will appear.\r\n5.  Configure the cracking parameters:\r\n    *   Enter the **Charset**.\r\n    *   Check **Enable Pattern Matching** *or* set **Min Length** / **Max Length**.\r\n    *   If Pattern Matching is enabled, enter the **Pattern** (see [Syntax](#pattern-matching-syntax)). Note how Min/Max Length fields may disable.\r\n    *   Select the cracking **Mode**.\r\n    *   Select the target **Archive File**.\r\n    *   Check/Uncheck the **\"Exclude previously tried passwords\"** checkbox to control usage of `helpers/skip_list.bf`.\r\n6.  Click **Run C++ Backend**.\r\n7.  Monitor the **Output Log** for progress and status.\r\n8.  If found, the password will be printed (`FOUND:password`) and shown in a success pop-up.\r\n9.  If the search completes without finding the password, a \"Finished\" message appears.\r\n10. Click **Stop Backend** to terminate early. The C++ backend will attempt to save the current skip list state (if enabled and valid) before exiting.\r\n11. Click **Clear Skip List** to discard the learned state (prompts for confirmation).\r\n\r\n---\r\n\r\n## Building\r\n\r\n### Building the C++ Backend (CLI)\r\n\r\nUse the `cpp_backend/compile_cli.bat` script (Windows) or adapt the `g++` command for Linux/macOS, as done during setup. This creates the `ArchivePasswordCrackerCLI.exe` (or similar) needed in `helpers/`.\r\n\r\n### Building the Python GUI Standalone Executable\r\n\r\nUse PyInstaller to package the Python script and all necessary resources (C++ backend, 7-Zip binaries, JSON defaults) into a single distributable folder.\r\n\r\n1.  **Install PyInstaller:** `pip install pyinstaller`\r\n2.  **Ensure Prerequisites:**\r\n    *   Confirm the compiled C++ `.exe` is in `helpers/`.\r\n    *   Confirm `7z.exe`/`.dll` are in `helpers/bin/`.\r\n    *   Confirm `.json` files are in `helpers/json/`.\r\n    *   (Optional) Delete `helpers/skip_list.bf` and `helpers/log.txt` before building if you don't want to bundle potentially large or outdated state/log files.\r\n3.  **Run PyInstaller** from the main project root directory:\r\n\r\n    ```bash\r\n    # On Windows (use semicolon ; for path separators in --add-data)\r\n    pyinstaller ^\r\n      --name ArchivePasswordCracker ^\r\n      --onedir ^\r\n      --noconsole ^\r\n      --add-data \"helpers;helpers\" ^\r\n      archive_password_cracker.py\r\n\r\n    # On Linux/macOS (use colon : for path separators in --add-data)\r\n    # pyinstaller \\\r\n    #   --name ArchivePasswordCracker \\\r\n    #   --onedir \\\r\n    #   --noconsole \\\r\n    #   --add-data \"helpers:helpers\" \\\r\n    #   archive_password_cracker.py\r\n    ```\r\n\r\n    *   `--name ArchivePasswordCracker`: Sets the output folder and main executable name.\r\n    *   `--onedir`: Creates a folder bundle (recommended for easier resource handling).\r\n    *   `--noconsole`: Hides the console window when the GUI runs (use `--console` for debugging builds).\r\n    *   `--add-data \"helpers;helpers\"` (or `:helpers`): **Crucial!** Copies the *entire* `helpers` folder (including the C++ CLI, the `bin` subfolder with 7-Zip, the `json` subfolder, and any existing `skip_list.bf` or `log.txt`) into the root of the bundle, preserving the relative paths needed by the application at runtime.\r\n\r\n4.  **Verify Bundle Structure:** Check the generated `dist/ArchivePasswordCracker` folder. It should contain:\r\n    *   `ArchivePasswordCracker.exe` (or similar) - The main Python GUI launcher.\r\n    *   The `helpers/` folder, containing:\r\n        *   `ArchivePasswordCrackerCLI.exe` (C++ backend).\r\n        *   `bin/` folder with `7z.exe` and `7z.dll`.\r\n        *   `json/` folder with `.json` defaults.\r\n    *   Various Python DLLs, libraries (`_internal` folder), etc.\r\n\r\n5.  **Result \u0026 Distribution:** The `dist/ArchivePasswordCracker` folder contains everything needed. Zip and distribute this folder. The C++ backend inside the bundled `helpers/` will correctly find 7-Zip in its adjacent `bin/` folder.\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT License\r\n\r\n---\r\n\r\n## Acknowledgements\r\n\r\n*   **CustomTkinter:** For the modern Python GUI framework ([Tom Schimansky](https://github.com/TomSchimansky/CustomTkinter)).\r\n*   **7-Zip / Igor Pavlov:** For the essential 7-Zip command-line utility ([www.7-zip.org](https://www.7-zip.org/)).\r\n*   **windnd (Optional):** For Windows drag-and-drop support ([GitHub](https://github.com/cilame/windnd)).\r\n*   **Python Standard Library Contributors:** (`subprocess`, `threading`, `tkinter`, `pathlib`, `json`, etc.).\r\n*   **C++ Standard Library Contributors:** (`thread`, `atomic`, `random`, `vector`, `chrono`, `mutex`, `fstream`, `optional`, etc.).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglooring%2Farchive-password-cracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglooring%2Farchive-password-cracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglooring%2Farchive-password-cracker/lists"}