# mebus/cupp architecture

> Architecture diagram of the GitHub repository mebus/cupp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mebus/cupp
- Repository: https://github.com/mebus/cupp

## Overview

CUPP is a command-line password-dictionary generator intended for authorized profiling and investigations. The main workflow collects user-provided profile details, derives and transforms candidate passwords, filters them, and writes a dictionary. Separate options improve an existing wordlist, download categorized dictionaries, or obtain and parse the Alecto database. The excerpts show configuration loading and parts of these operations, but omit some dispatch and output details; uncertain wiring is not shown.

Main entry points: [`cupp.py`](https://github.com/mebus/cupp/blob/master/cupp.py) (CLI entry point), [`cupp.cfg`](https://github.com/mebus/cupp/blob/master/cupp.cfg) (Runtime settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and configuration"]
  node_main["CLI entry point<br/>[cupp.py]"]
  node_parser["Option parser<br/>[cupp.py]"]
  node_config_loader["Config loader<br/>[cupp.py]"]
  node_config["Runtime settings<br/>[cupp.cfg]"]
end

subgraph group_generation["Dictionary generation"]
  node_interactive["Profile prompts<br/>[cupp.py]"]
  node_candidate_gen["Candidate generation<br/>[cupp.py]"]
  node_leet["Leet conversion<br/>[cupp.py]"]
  node_candidate_filter["Length filtering<br/>[cupp.py]"]
  node_output["Dictionary output<br/>[cupp.py]"]
  node_wordlist_improver["Wordlist improver<br/>[cupp.py]"]
end

subgraph group_sources["Dictionary sources"]
  node_list_downloader["Wordlist downloader<br/>[cupp.py]"]
  node_catalog["Wordlist catalog<br/>[cupp.py]"]
  node_alecto_importer["Alecto parser<br/>[cupp.py]"]
end

node_user(("Operator"))
node_remote_sources(("Remote wordlist sources"))
node_alecto_db(("Alecto database"))

node_user -->|"runs"| node_main
node_main -->|"loads settings"| node_config_loader
node_config_loader -->|"reads"| node_config
node_main -->|"parses options"| node_parser
node_user -->|"provides profile"| node_interactive
node_interactive -->|"generates candidates"| node_candidate_gen
node_candidate_gen -->|"converts variants"| node_leet
node_leet -->|"filters length"| node_candidate_filter
node_candidate_filter -->|"writes words"| node_output
node_user -->|"provides wordlist"| node_wordlist_improver
node_wordlist_improver -->|"writes words"| node_output
node_list_downloader -->|"uses categories"| node_catalog
node_list_downloader -->|"downloads files"| node_remote_sources
node_alecto_importer -->|"downloads database"| node_remote_sources
node_remote_sources -.->|"includes"| node_alecto_db

click node_main "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_parser "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_config_loader "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_config "https://github.com/mebus/cupp/blob/master/cupp.cfg"
click node_interactive "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_candidate_gen "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_leet "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_candidate_filter "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_output "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_wordlist_improver "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_list_downloader "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_catalog "https://github.com/mebus/cupp/blob/master/cupp.py"
click node_alecto_importer "https://github.com/mebus/cupp/blob/master/cupp.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_parser,node_config_loader,node_config toneBlue
class node_interactive,node_candidate_gen,node_leet,node_candidate_filter,node_output,node_wordlist_improver,node_alecto_db toneAmber
class node_list_downloader,node_catalog,node_alecto_importer toneMint
class node_user,node_remote_sources toneIndigo
```

## Components

### CLI and configuration

- [CLI entry point](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Option parser](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Config loader](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Runtime settings](https://github.com/mebus/cupp/blob/master/cupp.cfg): `cupp.cfg`

### Dictionary generation

- [Profile prompts](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Candidate generation](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Leet conversion](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Length filtering](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Dictionary output](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Wordlist improver](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`

### Dictionary sources

- [Wordlist downloader](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Wordlist catalog](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`
- [Alecto parser](https://github.com/mebus/cupp/blob/master/cupp.py): `cupp.py`

### Other components

- **Operator**
- **Remote wordlist sources**
- **Alecto database**

## Connections

- Operator → CLI entry point: runs
- CLI entry point → Config loader: loads settings
- Config loader → Runtime settings: reads
- CLI entry point → Option parser: parses options
- Operator → Profile prompts: provides profile
- Profile prompts → Candidate generation: generates candidates
- Candidate generation → Leet conversion: converts variants
- Leet conversion → Length filtering: filters length
- Length filtering → Dictionary output: writes words
- Operator → Wordlist improver: provides wordlist
- Wordlist improver → Dictionary output: writes words
- Wordlist downloader → Wordlist catalog: uses categories
- Wordlist downloader → Remote wordlist sources: downloads files
- Alecto parser → Remote wordlist sources: downloads database
- Remote wordlist sources → Alecto database: includes