first commit~

2026-03-29 19:13:48 -07:00
commit 6b60fc43a7
1 changed files with 132 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,132 @@
+<div align="center">
+
+```text
+ ███████╗██╗███╗   ██╗ █████╗ ██╗     ██╗   ██╗     ~ finally ~
+ ██╔════╝██║████╗  ██║██╔══██╗██║     ╚██╗ ██╔╝   dual-radio lab
+ █████╗  ██║██╔██╗ ██║███████║██║      ╚████╔╝    aircrack-ng tmux
+ ██╔══╝  ██║██║╚██╗██║██╔══██║██║       ╚██╔╝      hc22000 · no hashcat
+ ██║     ██║██║ ╚████║██║  ██║███████╗   ██║
+ ╚═╝     ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝   ╚═╝
+```
+
+**`// capture · deauth · convert · print hashcat cmd`**  
+<sub>LAB / AUTHORIZED ENVIRONMENTS ONLY · MT7612U + RTL8812AU</sub>
+
+</div>
+
+<div align="center">
+
+![Bash](https://img.shields.io/badge/shell-bash-121212?style=for-the-badge&logo=gnu-bash&logoColor=00ff41)
+![aircrack-ng](https://img.shields.io/badge/stack-aircrack--ng-121212?style=for-the-badge&logo=wireshark&logoColor=39ff14)
+![hc22000](https://img.shields.io/badge/hashcat_-m_22000-121212?style=for-the-badge&logoColor=7dff00)
+![tmux](https://img.shields.io/badge/UI-tmux_2--pane-121212?style=for-the-badge&logo=tmux&logoColor=00ff88)
+
+</div>
+
+---
+
+## `$ whoami`
+
+**`finally`** is a single entrypoint: **`./start.sh`**. It flips two interfaces into monitor mode, opens a **tmux** lab console (live **airodump-ng** + automated **aireplay-ng** cycle), dumps raw **`.cap`** under `out/<timestamp>/`, then runs **`hcxpcapngtool`** to produce **one** merged **`handshakes.hc22000`** and prints the exact **`hashcat -m 22000`** line — it does **not** invoke hashcat.
+
+<details>
+<summary><strong>📡 threat model (what this is / isn’t)</strong></summary>
+
+| In scope | Out of scope |
+|----------|--------------|
+| Campus pen-test labs with written scope | Anything outside explicit authorization |
+| Pair of dedicated USB adapters | Running hashcat for you |
+| Clean teardown → managed mode | Teaching OPSEC or evasion |
+
+</details>
+
+---
+
+## `$ ./quickstart`
+
+```bash
+# from repo root — will sudo itself
+chmod +x start.sh
+./start.sh
+```
+
+**Inside tmux**, quit cleanly:
+
+```text
+Ctrl+b    # prefix
+&         # kill-window (confirm y)
+```
+
+**Detached** instead of killed? Session keeps running on the radios. See [HOW_IT_WORKS.md](./HOW_IT_WORKS.md) for recovery / manual `airmon-ng stop`.
+
+---
+
+## `$ ls -la stack`
+
+| Layer | Tooling |
+|-------|---------|
+| **Capture** | `airodump-ng` · channel hop · `CAPTURE_IFACE` → monitor |
+| **Attack** | `aireplay-ng` · scan CSV · targeted / broadcast deauth |
+| **Convert** | `hcxpcapngtool` → `*.hc22000` + ESSID hint wordlist |
+| **Shell** | `bash` · `tmux` · `airmon-ng` · `iw` |
+
+**Target hardware (defaults)**
+
+| Radio | Default iface | Typical dongle |
+|-------|---------------|----------------|
+| Record / hop | `wlan0` | MediaTek **MT7612U** |
+| Scan / deauth | `wlan1` | Realtek **RTL8812AU** |
+
+---
+
+## `$ export THINGS`
+
+| Variable | Default | Role |
+|----------|---------|------|
+| `CAPTURE_IFACE` | `wlan0` | Physical name before monitor |
+| `ATTACK_IFACE` | `wlan1` | Physical name before monitor |
+| `IGNORE_SSID` | `thetempleofdoom` | Skip AP rows containing substring |
+| `CAPTURE_BAND` | `abg` | `a` / `bg` / `abg` for airodump |
+| `SCAN_SECONDS` | `6` | Per-scan dwell |
+| `DEAUTH_COUNT` | `18` | Frames per burst |
+| `ATTACK_DELAY` | `0.15` | Pace between bursts (seconds) |
+| `SESSION_DIR` | `out/<timestamp>` | Artifacts |
+| `TMUX_SESSION` | `finally` | Session name |
+
+---
+
+## `$ tree out`
+
+```text
+out/20260329_143022/
+├── chamber-01.cap          # raw capture (rolling)
+├── handshakes.hc22000      # hashcat -m 22000
+├── essids_from_capture.txt # ESSID hints from conversion
+├── .cap.sh                  # tmux top pane launcher
+└── .atk.sh                  # tmux bottom pane launcher
+```
+
+---
+
+## `$ man thoroughly`
+
+Full sequence diagrams and cleanup rules → **[HOW_IT_WORKS.md](./HOW_IT_WORKS.md)**
+
+---
+
+## `$ legal`
+
+> **Authorized access only.** Running deauthentication or passive capture against networks you do not own or have **explicit written permission** to test is illegal in many jurisdictions. This repository is for **education** and **licensed security assessments** (e.g. school lab with scope). The authors assume no liability for misuse.
+
+```text
+  Monitor mode + airmon-ng check kill can nuke local Wi-Fi (NetworkManager).
+  Prefer SSH over Ethernet or a dedicated attack box so you don’t lock yourself out.
+```
+
+---
+
+<p align="center">
+  <sub>
+    <code>~</code> red team hygiene: scope · logging · teardown · hashcat on your own box <code>~</code>
+  </sub>
+</p>