first commit

README.md

@@ -0,0 +1,119 @@
+# GODCWAK
+
+![GODCWAK screenshot](assets/screenshot.png)
+
+**GPU-accelerated account-recovery lab gear with proxy rotation, targeted wordlist building, and local Ollama CAPTCHA tooling.**
+
+GODCWAK is a high-energy Windows desktop application for authorized recovery work, local security testing, and lab validation on systems you own or are explicitly permitted to test. It brings a cyberpunk CustomTkinter interface to password-candidate generation, proxy health checks, live attempt logging, and local AI-assisted CAPTCHA experiments.
+
+This project is not a license to attack other people, harvest credentials, bypass access controls, or run unauthorized login attempts. Keep it legal, scoped, and documented.
+
+## What It Does Today
+
+- **Password Builder:** creates targeted password candidates from known fragments, custom words, number ranges, symbols, capitalization rules, leet variants, pattern templates, and length/character constraints.
+- **GPU-aware generation:** uses CuPy when a CUDA GPU is available, NumPy for accelerated CPU paths, and pure Python as the fallback.
+- **Proxy Manager:** fetches public proxies, imports/pastes proxy lists, tests proxy health, removes dead entries, and commits valid proxies to the runtime pool.
+- **Attack Terminal:** runs a configurable multi-worker login workflow against the selected target URL with proxy rotation, delay controls, timeout settings, live progress, pause/resume/stop controls, and attempt logging.
+- **Logs view:** shows runtime activity and records attempts to `data/attempt_log.csv`.
+- **Setup tab:** stores local Ollama settings, lists/tests models, and supports local model configuration for CAPTCHA-solving experiments.
+
+## Current Limits
+
+- CAPTCHA detection is present in the attack workflow, but full CAPTCHA solve-and-submit automation is still roadmap work.
+- Browser automation modules exist, but they are not yet connected into the attack flow.
+- Login success classification and generic site handling are still under active improvement.
+- Large generated wordlists and generated attempt logs can contain sensitive data; keep them local and out of commits.
+
+See [`NEEDS_TO_BE_DONE.md`](NEEDS_TO_BE_DONE.md) for the bug list, audit notes, and roadmap.
+
+## Install On Windows
+
+From PowerShell in the project directory:
+
+```powershell
+py -3 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+If PowerShell blocks activation scripts, run:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+```
+
+Then activate the virtual environment again.
+
+## Run
+
+Double-click:
+
+```text
+GODCWAK.bat
+```
+
+Or run from PowerShell:
+
+```powershell
+.\GODCWAK.bat
+```
+
+The launcher prefers `.venv\Scripts\python.exe`, then the Windows `py -3` launcher, then `python` from `PATH`.
+
+You can also launch directly:
+
+```powershell
+python main.py
+```
+
+## GPU Notes
+
+GODCWAK checks for CuPy at startup. With `cupy-cuda12x` installed and a working NVIDIA CUDA-capable GPU, password-combination index generation can use the GPU for larger workloads. Without CUDA, the app falls back to NumPy CPU acceleration or pure Python.
+
+If CuPy does not load, the app still runs. The startup log will report that GPU acceleration is disabled.
+
+## Ollama And CAPTCHA Notes
+
+Ollama settings live in `config_ollama.json`. The default host is:
+
+```text
+http://localhost:11434
+```
+
+Use the Setup tab to connect to a local Ollama server, list models, save a model choice, and run basic model tests. Vision-model CAPTCHA solving exists as a local solver module, but the full browser capture, solve, click/type, and retry loop is not yet wired into the attack workflow.
+
+## Project Structure
+
+```text
+.
+├── GODCWAK.bat              Windows launcher
+├── main.py                  Application entry point
+├── config.py                Paths, defaults, and runtime constants
+├── config_ollama.json       Local Ollama and browser settings
+├── requirements.txt         Python dependencies
+├── NEEDS_TO_BE_DONE.md      Audit notes and roadmap
+├── data/                    Local runtime data and logs
+└── src/
+    ├── attack/              Login client and multi-worker orchestrator
+    ├── captcha/             Ollama solver and browser/screenshot helpers
+    ├── engine/              Password generation and GPU acceleration
+    ├── gui/                 CustomTkinter application tabs and theme
+    ├── proxy/               Proxy fetch, validation, and pool management
+    └── utils/               File and attempt logging helpers
+```
+
+## Authorized Use Only
+
+Use GODCWAK only for:
+
+- Accounts and systems you own.
+- Recovery workflows you are authorized to perform.
+- Internal lab targets and controlled test environments.
+- Defensive validation with written permission and a clear scope.
+
+Do not use it for unauthorized credential attacks, account takeover, evasion, abuse, or activity that violates law, policy, or platform terms. The operator is responsible for scope, consent, logs, and consequences.
+
+## Roadmap
+
+The punch list lives in [`NEEDS_TO_BE_DONE.md`](NEEDS_TO_BE_DONE.md). Top priorities include wiring CAPTCHA automation into the attack flow, strengthening login classification, improving session/thread safety, refining proxy lifecycle handling, and adding automated tests.