# phenotypic/wificrack architecture

> Architecture diagram of the GitHub repository phenotypic/wificrack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phenotypic/wificrack
- Repository: https://github.com/phenotypic/wificrack

## Overview

##### Project type and purpose
- WiFiCrack is an open-source, Bash-based CLI tool for demonstrating WPA/WPA2 handshake capture and password cracking.
- It glues together system utilities and external tools (mergecap, cap2hccapx, hashcat) to automate the end-to-end attack process for educational purposes.

##### File structure
- Top level contains only three entries:
- LICENSE – project license
- README.md – documentation and usage instructions
- WiFiCrack.sh – the single Bash script
- No frontend/backend split, no libraries or modules beyond the script itself
- All architecture lives inside the script’s workflow and its interaction with external dependencies

##### README for additional insights
- Describes the high-level flow:
a) Detect and configure Wi-Fi interface in monitor mode
b) Scan for and list available networks
c) (Optional) Deauthentication attack to provoke a handshake
d) WPA/WPA2 handshake packets
e) Convert capture to hashcat-readable format (cap2hccapx)
f) Invoke hashcat with a wordlist to crack the passphrase
- Lists external prerequisites: Xcode (macOS), hashcat, mergecap, cap2hccapx, plus a wordlist

a. Main components
- User / CLI – initiates the script and provides flags (–h, –w, –i, etc.)
- WiFiCrack.sh – central orchestration script
- OS & Shell Environment – Bash/Zsh on macOS
- Wi-Fi Adapter – switched to monitor mode by the script
- Wireless Network (Target AP + client device) – source of WPA handshake
- mergecap – packet file merger/converter (part of Wireshark)
- cap2hccapx.bin – hashcat-utils converter
- hashcat – GPU-accelerated password cracker
- Wordlist – dictionary for hashcat attacks
- Output (handshake files, cracked password)

b. Relationships and data flow
1. User invokes WiFiCrack.sh (CLI → Script).
2. Script configures Wi-Fi Adapter into monitor mode (Script → OS/Adapter).
3. Adapter captures beacon and handshake packets from Target AP/Client (Adapter ↔ Network).
4. Optionally, Script triggers deauth frames to force a handshake (Script → Network).
5. Packet capture file(s) passed to mergecap if needed (Script → mergecap → Script).
6. Script runs cap2hccapx to produce a .hccapx file (Script → cap2hccapx).
7. Script calls hashcat, supplying .hccapx file and Wordlist (Script → hashcat).
8. hashcat produces cracked password or retains .hccapx for later (hashcat → Script).
9. Script reports result to User (Script → CLI).

c. Architectural patterns and design principles
- Orchestration pattern: WiFiCrack.sh acts as a coordinator, invoking external tools in sequence.
- Modularity by externalization: heavy lifting is delegated to battle-tested utilities rather than reinvented.
- Clear separation of concerns: capture, conversion, cracking, and I/O are distinct steps.

d. Key technologies and libraries
- Bash scripting in macOS environment
- mergecap (Wireshark) for pcap manipulation
- cap2hccapx (hashcat-utils) for format conversion
- hashcat for GPU-based attack
- Standard Unix tools (awk/grep/sudo) for parsing and control flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Components
    User["User / CLI"]:::io
    Script["WiFiCrack.sh"]:::script
    OS["OS & Shell Environment"]:::hw
    Adapter["Wi-Fi Adapter"]:::hw
    Network["Wireless Network (AP & Client)"]:::hw
    merge["mergecap"]:::tool
    cap2["cap2hccapx"]:::tool
    hashcat["hashcat"]:::tool
    wordlist["Wordlist"]:::tool
    Output["Output (handshake files & cracked password)"]:::io
    Readme["README.md"]:::io
    License["LICENSE"]:::io

    %% Flow
    User -->|"1.invokes"| Script
    Script -->|"2.configure monitor mode"| OS
    OS -->|"2.executes"| Adapter
    Adapter -->|"3.captures packets from"| Network
    Adapter -->|"3.delivers capture"| Script
    Script -.->|"4.deauth attack (optional)"| Network
    Script -->|"5.pcap merge"| merge
    merge -->|"5.return merged pcap"| Script
    Script -->|"6.convert to .hccapx"| cap2
    cap2 -->|"6.return .hccapx"| Script
    Script -->|"7.crack with hashcat"| hashcat
    wordlist -->|"7.provides dictionary"| hashcat
    hashcat -->|"8.return results"| Script
    Script -->|"9.reports result"| User
    Script -->|"produces"| Output

    %% Click Events
    click Script "https://github.com/phenotypic/wificrack/blob/master/./WiFiCrack.sh"
    click Readme "https://github.com/phenotypic/wificrack/blob/master/./README.md"
    click License "https://github.com/phenotypic/wificrack/tree/master/./LICENSE"

    %% Styles
    classDef script fill:#add8e6,stroke:#000,stroke-width:1px
    classDef tool fill:#90ee90,stroke:#000,stroke-width:1px
    classDef hw fill:#ffa500,stroke:#000,stroke-width:1px
    classDef io fill:#d3d3d3,stroke:#000,stroke-width:1px
```
