# Mebus/cupp: building a targeted password wordlist from a person's details

> CUPP is a Python 3 profiler that turns what you know about a target into candidate passwords. It is a small interactive script with a wide wordlist downloader attached, and its output is only as good as your input.

**Mebus/cupp** — Common User Passwords Profiler (CUPP)

- Repository: https://github.com/Mebus/cupp
- Stars: 6,553 · Forks: 2,407
- Language: Python
- License: GPL-3.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/mebus-cupp

## The guessing problem CUPP was written for

The README frames the problem in authentication terms: a weak password can be one that is easily guessed by someone profiling the user, such as a birthday, nickname, address, name of a pet or relative, or a common word. That is a different failure from a password that is short or alphanumeric. A long password built from a pet's name and a birth year survives length checks and still falls to a handful of targeted guesses.

CUPP exists to produce exactly those targeted guesses. The README states it can be used in situations like legal penetration tests or forensic crime investigations. That scope matters. The tool takes personal details as input and writes candidate passwords as output; it does not crack hashes, does not talk to a login form, and does not test whether any candidate is correct. Whoever uses it supplies the target details and decides what to do with the list.

The intended user is therefore a penetration tester or investigator who already has authorised access to a target environment and some biographical information. It is not aimed at a developer who wants to score an application's password policy. Nothing in the README describes a strength-scoring mode, and the topics list on the repository points at wordlist generation rather than policy enforcement.

## How the profiler turns details into candidates

The mechanism is a questionnaire plus a set of combination rules. Running cupp.py with the -i flag starts interactive questions for user password profiling. The user answers them, and the script writes a wordlist file. The README's example section is a fast-forwarded GIF rather than text, so the exact questions and the exact combination logic are not documented in prose; the file test_cupp.py at the repository root is the place to look if you want to know what the code asserts about its own output.

The other modes reuse the same output format. The -w flag profiles an existing dictionary, or WyD.pl output, which means CUPP can expand a list you already have rather than only building one from a questionnaire. The -a flag parses default usernames and passwords directly from Alecto DB, described in the README as purified databases of Phenoelit and CIRT that were merged and enhanced. That is a fixed corpus, not a live feed: whatever Alecto DB contained when that mode was written is what you get.

The -l flag downloads huge wordlists from a repository. This is the part of CUPP that has nothing to do with the target at all; it is a convenience wrapper for pulling bulk lists. Treat it as a separate feature with separate disk requirements, because a downloaded list can be orders of magnitude larger than a profile built from one person's details.

## Installing CUPP and generating a first wordlist

There is no packaging step. The README's requirements section says you need Python 3 to run CUPP, and the quick start is a single command. Clone the repository, change into it, and run the help menu to confirm the script starts.

```bash
python3 cupp.py -h
```

You should see the usage block listing -h, -i, -w, -l, -a and -v. If Python 3 is missing, the interpreter error appears before any of that. There is no pip install line in the README and no setup.py in the top-level repository entries, so a virtual environment is optional rather than required.

For a first real run, use interactive mode. The script asks a series of questions about the target and then writes a wordlist.

```bash
python3 cupp.py -i
```

Answer the prompts and note the output filename the script reports at the end. Open that file and read the first few lines before you use it anywhere; the value of CUPP is in seeing which combinations it derived from your answers, and a list you have not inspected is a list you cannot defend in a report.

The -v flag prints the program version, which is worth capturing in an engagement record since the repository has no tagged releases. Configuration lives in cupp.cfg at the repository root; the README says it has instructions inside, so edit that file rather than patching cupp.py if you need to change defaults.

## What CUPP cannot tell you

The output is unverified. CUPP generates candidates; it never checks them against a hash, a directory service or a login endpoint. A wordlist of ten thousand entries and a wordlist of ten entries look the same in a report unless you actually test them, and the README documents no testing capability.

The quality of the list is bounded by the quality of the answers. If the questionnaire asks for a pet's name and you do not know it, the profile loses that branch entirely. There is no scoring, no ranking and no indication of which candidates are more likely than others. The README's own framing, that a weak password can be one that is easily guessed by someone profiling the user, cuts both ways: if the profile is thin, the output is generic.

The -w mode inherits the weaknesses of its input. Feeding it a poor dictionary produces a poor expanded dictionary. The -a mode is tied to a static corpus from Alecto DB, so it cannot reflect anything that happened after that database was assembled.

Finally, the project has no tagged releases. The last push to the default branch was on 2026-07-17, which is recent enough that the code is not abandoned, but there is no version number to pin in a reproducible environment. If your process requires a fixed artefact, CUPP does not give you one; you pin a commit hash or you accept drift.

## CUPP against hashcat rule-based mangling

The obvious alternative for building candidate passwords is hashcat's rule engine, which applies transformation rules to a base wordlist: append digits, capitalise, substitute characters, and so on. The difference in approach is where the knowledge sits. Hashcat rules are generic and reusable; you write or pick a rule file and apply it to any base list. CUPP's knowledge sits in the questionnaire, and the combination logic is built around the specific details you supply about one person.

That makes them complementary rather than competing in practice. A common workflow is to let CUPP produce the personal core and then run a mangling pass over it. What hashcat gives you that CUPP does not is a documented, versioned rule format you can store in a repository and diff between engagements. What CUPP gives you that a plain rule file does not is the interview step, which is the part that captures the pet name and the birth year in the first place.

If your need is bulk generation from an existing corpus with no personal detail involved, CUPP's -l and -a modes overlap with simply downloading a wordlist, and you may not need the script at all.

## Licence and the cost of staying current

CUPP is GPL-3.0. The README carries the standard GNU General Public License notice, version 3 or any later version, with the warranty disclaimer, and points to ./LICENSE for the full text. For an internal penetration test this changes little. If you modify cupp.py and distribute the result, the licence's copyleft terms apply to that distribution; that is a question for your legal team, not something this article can settle.

The upgrade cost is low in one sense and awkward in another. There is nothing to upgrade in a package manager, because there is no package. You pull the repository. The awkward part is that with no tagged releases there is no changelog-driven upgrade path; CHANGELOG.md exists at the root, so read it against the commit you are running. The .bumpversion.cfg and .travis.yml files at the root suggest the project once automated version bumps and CI, but the README's build badge points at travis-ci.org, and the absence of releases means none of that produces a version you can depend on.

## Conclusion

CUPP fits one job: producing a candidate wordlist for a legal penetration test or forensic investigation where you already hold details about a person. It is not a cracking tool and it does not verify anything it generates, so anyone expecting coverage guarantees should look at hashcat's rule engine instead. Before adopting it, check that cupp.cfg is present next to cupp.py, since the README points there for configuration, and read the GPL-3.0 terms if you plan to redistribute a modified cupp.py.

## FAQ

### How do I use Mebus CUPP?

Run python3 cupp.py -h to see the options, then python3 cupp.py -i to start the interactive questions for user password profiling. The script writes a wordlist from your answers. The README also documents -w for profiling an existing dictionary, -l for downloading wordlists, and -a for parsing default credentials from Alecto DB.

### What Python version does CUPP require?

The README's requirements section states that you need Python 3 to run CUPP. There is no pip install step documented and no setup.py among the top-level repository entries.

### Does CUPP crack passwords?

No. The README describes CUPP as producing candidate passwords from details about a user, for situations like legal penetration tests or forensic crime investigations. It generates a wordlist; it does not test candidates against a hash or a login service.

### Where is CUPP configured?

The README states that CUPP has a configuration file, cupp.cfg, with instructions. That file sits at the repository root alongside cupp.py.

### What does the -a option in CUPP do?

It parses default usernames and passwords directly from Alecto DB, which the README describes as purified databases of Phenoelit and CIRT that were merged and enhanced. It is a fixed corpus rather than a live source.

## Sources

- [Issues](https://github.com/Mebus/cupp/issues)
- [License: GPL-3.0](https://github.com/Mebus/cupp/blob/master/LICENSE)
- [Mebus/cupp on GitHub](https://github.com/Mebus/cupp)
- [README](https://github.com/Mebus/cupp/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mebus-cupp