# trustedsec/hate_crack architecture

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

- Interactive diagram: https://gitdiagram.com/trustedsec/hate_crack
- Repository: https://github.com/trustedsec/hate_crack

## Overview

##### Project type and purpose
- This is a command-line orchestration tool (“hate_crack”) built around the hashcat password-cracking engine.
- It provides multiple “attack modes” (Quick Crack, Pure_Hate methodology, Brute Force, Mask, Combinator, PRINCE, etc.), wraps calls to external binaries (hashcat, PACK utilities, hashcat-utils, princeprocessor), and manages wordlists, masks, and rules.

##### File structure
- Top-level scripts:
– hate_crack.py            ← main CLI entry point
– wordlist_optimizer.py   ← helper to preprocess wordlists
– maskgen.py, policygen.py, statsgen.py (in PACK/)
– Additional scripts: hate_crack.py spawns PACK tools, hashcat-utils bins, princeprocessor binaries, pipal analysis, etc.
- Data directories:
– masks/                   ← .hcmask files for mask attacks
– rules/                   ← .rule files for hashcat rule-based attacks
– hashcat-utils/           ← precompiled utilities invoked by certain modes
– princeprocessor/         ← PRINCE attack engine and rule sets
– config.json.example      ← defines paths for hashcat, wordlists, optimized wordlists
- Third-party integrations:
– External executable: hashcat binary (built via git clone & make)
– pipal (optional hash analysis tool)

##### README for additional insights
- The README outlines each attack mode, the sequence of sub-attacks or rule applications, and data flows (which wordlists/masks/rules get applied).
- It references PACK (statsgen, maskgen) for Top Mask Attack.
- It references hashcat-utils for stats generation.
- It references princeprocessor for PRINCE Attack.

##### Main components and interactions
a. Core Components
1. CLI Controller (hate_crack.py)
2. Configuration Loader (reads config.json)
3. Attack Modules (one per mode):
- Quick Crack
- Pure_Hate methodology
- Brute Force
- Top Mask (invokes PACK: statsgen.py → maskgen.py)
- Fingerprint (invokes hashcat-utils hcstatgen)
- Combinator/Hybrid/PRINCE (invokes hashcat-utils/combinator, princeprocessor)
- pipal Analysis
4. Wordlist Optimizer (wordlist_optimizer.py)
5. Data Stores:
- Wordlists directory
- Optimized wordlists (output of wordlist_optimizer.py)
- masks/ directory
- rules/ directory
- princeprocessor/rules/
- hashcat binary
- PACK utilities (maskgen, statsgen)
- hashcat-utils binaries
- princeprocessor binaries
- pipal analysis script/tool
c. Data Flow
– User invokes hate_crack.py → loads config.json → presents menu → user selects mode.
– Controller calls Attack Module → Attack Module invokes external binary(ies) with parameters (wordlist file path, rule file path, mask file).
– External tool processes hashes → outputs cracked/password data → Attack Module collects & optionally pipelines through pipal or exports to Excel.
– Results are stored/logged and displayed.

##### Architectural patterns and design principles
- Modular design: each attack mode encapsulated as a distinct function/class.
- External process orchestration: the core Python code spawns subprocesses for hashcat, PACK, hashcat-utils, and princeprocessor.
- Configuration-driven: all paths and parameters are abstracted via config.json.
- Extensibility: new attack modes can be added by dropping in new scripts or binaries and wiring them into the menu.
- Data separation: static resources (masks, rules, wordlists) live in dedicated folders.

##### Essential details to capture
- Which directories/files back each module (e.g., “masks/*.hcmask”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components (Blue)
    subgraph "Core Components"
        direction TB
        CLI["hate_crack.py\n(CLI Controller)"]:::core
        Config["config.json.example\n(Configuration Loader)"]:::config
        WordOpt["wordlist_optimizer.py\n(Wordlist Optimizer)"]:::core
    end

    %% Attack Modules
    subgraph "Attack Modules" 
        direction TB
        QC["Quick Crack Module"]:::core
        PH["Pure_Hate Module"]:::core
        BF["Brute Force Module"]:::core
        TM["Top Mask Attack Module"]:::core
        FP["Fingerprint Module"]:::core
        CH["Combinator/Hybrid/PRINCE Module"]:::core
        PP["Pipal Analysis Module"]:::core
    end

    %% Data Stores (Orange)
    subgraph "Data Stores"
        direction TB
        WL["Wordlists\n(directory)"]:::data
        OWL["Optimized Wordlists\n(directory)"]:::data
        Masks["masks/\n(.hcmask files)"]:::data
        Rules["rules/\n(.rule files)"]:::data
        PRules["princeprocessor/rules\n(prince_*.rule)"]:::data
    end

    %% External Tools (Green)
    subgraph "External Tools"
        direction TB
        HC["hashcat binary"]:::tool
        subgraph "PACK Utilities"
            Stats["statsgen.py"]:::tool
            MaskGen["maskgen.py"]:::tool
            Policy["policygen.py"]:::tool
        end
        subgraph "hashcat-utils"
            HCStat["hcstatgen.bin"]:::tool
            Comb["combinator.bin"]:::tool
        end
        PPBin["pp64.bin\n(princeprocessor)"]:::tool
        Pipal["pipal tool"]:::tool
    end

    %% Core to Config and WordOpt
    CLI --> Config
    CLI --> WordOpt

    %% Core to Attack Modules
    CLI --> QC
    CLI --> PH
    CLI --> BF
    CLI --> TM
    CLI --> FP
    CLI --> CH
    CLI --> PP

    %% Attack Modules to Data Stores
    QC --> WL
    PH --> WL
    BF --> WL
    TM --> Masks
    FP --> Rules
    CH --> WL
    CH --> Rules
    CH --> PRules
    PP --> WL

    %% Attack Modules to External Tools
    TM --> Stats
    TM --> MaskGen
    TM --> Policy
    FP --> HCStat
    QC --> HC
    PH --> HC
    BF --> HC
    TM --> HC
    FP --> HC
    CH --> HC
    CH --> Comb
    CH --> PPBin
    PP --> Pipal

    %% Tool Data Flow
    Stats --> MaskGen
    MaskGen --> HC
    HCStat --> HC
    Comb --> HC
    PPBin --> HC

    %% Wordlist Optimizer data flow
    WordOpt --> WL
    WordOpt --> OWL

    %% Styles
    classDef core fill:#D0E6FF,stroke:#005A9C,stroke-width:1px;
    classDef config fill:#E0E0E0,stroke:#6E6E6E,stroke-width:1px;
    classDef data fill:#FFE4B3,stroke:#CC8400,stroke-width:1px;
    classDef tool fill:#D5F5D5,stroke:#1F8A2E,stroke-width:1px;

    %% Click Events
    click CLI "https://github.com/trustedsec/hate_crack/blob/main/hate_crack.py"
    click Config "https://github.com/trustedsec/hate_crack/blob/main/config.json.example"
    click WordOpt "https://github.com/trustedsec/hate_crack/blob/main/wordlist_optimizer.py"
    click Stats "https://github.com/trustedsec/hate_crack/blob/main/PACK/statsgen.py"
    click MaskGen "https://github.com/trustedsec/hate_crack/blob/main/PACK/maskgen.py"
    click Policy "https://github.com/trustedsec/hate_crack/blob/main/PACK/policygen.py"
    click Masks "https://github.com/trustedsec/hate_crack/tree/main/masks/"
    click Rules "https://github.com/trustedsec/hate_crack/tree/main/rules/"
    click HCStat "https://github.com/trustedsec/hate_crack/blob/main/hashcat-utils/bin/hcstatgen.bin"
    click Comb "https://github.com/trustedsec/hate_crack/blob/main/hashcat-utils/bin/combinator.bin"
    click PPBin "https://github.com/trustedsec/hate_crack/blob/main/princeprocessor/pp64.bin"
    click PRules "https://github.com/trustedsec/hate_crack/blob/main/princeprocessor/rules/prince_generated.rule"
```
