Understanding the Configuration Sections in cupp.cfg: A Complete Guide

The cupp.cfg file contains six active configuration sections—[years], [leet], [specialchars], [nums], [alecto], and [downloader]—that control how CUPP generates password lists, from leet-speak substitutions to numeric ranges and external data sources.

The Common User Passwords Profiler (CUPP) relies on a single configuration file to define its default behavior and data sources. Understanding the configuration sections in cupp.cfg is essential for customizing how the tool generates targeted wordlists for security testing. This guide breaks down each section based on the source code in the Mebus/cupp repository.

Configuration Sections in cupp.cfg Explained

[years] – Appending Time-Based Suffixes

Located at lines 15–16 in cupp.cfg, this section stores a comma-separated list of years that CUPP appends to base words during generation.

The read_config() function parses this list into CONFIG["global"]["years"] when the program starts. Later, the komb() helper combines each word with every year in this list, creating variations like john1995 or admin2020.

[leet] – Leet-Speak Character Substitution

The [leet] section (lines 18–27) defines character mappings for leet-speak transformations, such as a=4 and i=1.

When read_config() executes, it builds a dictionary CONFIG["LEET"] containing each letter-to-symbol mapping. If the user enables leet mode via the -i prompt or --leetmode flag, the make_leet() function walks through strings and replaces characters according to this table.

[specialchars] – Special Character Appendices

Found at lines 32–34, this section contains a comma-separated list of special characters that may be appended to generated words.

The parser stores these values in CONFIG["global"]["chars"]. When users opt to add special characters, CUPP builds combinations of 1–3 characters from this list and appends them to base words within improve_dictionary() and generate_wordlist_from_profile().

[nums] – Numeric Range Configuration

The [nums] section at lines 45–48 defines the numeric range used for random number suffixes via two integer values: from and to (defaulting to 0–100).

These values populate CONFIG["global"]["numfrom"] and CONFIG["global"]["numto"]. The concats() generator then uses these boundaries to produce numeric suffixes when the "random numbers" option is selected.

[alecto] – External Database URL

Lines 66–67 contain the [alecto] section, which specifies a URL pointing to a compressed CSV containing username/password pairs from the Alecto database.

This URL is stored as CONFIG["global"]["alectourl"]. The alectodb_download() routine fetches this file, extracts the columns, and writes separate username and password lists for further processing.

[downloader] – Wordlist Repository Base

The [downloader] section (lines 69–70) configures the base URL for the dictionary repository from which CUPP downloads large wordlists.

Saved as CONFIG["global"]["dicturl"], this value enables the download_wordlist_http() function to construct full download URLs by concatenating this base with sub-directory paths and filenames.

Note: Commented headings like [# Random years] appear in the file but serve only as explanatory text and do not affect the configuration parser.

How CUPP Loads Configuration Settings

The read_config() function in cupp.py handles all configuration parsing at startup. It maps the INI-style sections to a global CONFIG dictionary that subsequent functions reference throughout execution.

# Load the configuration (called at program start)

read_config(os.path.join(os.path.dirname(__file__), "cupp.cfg"))

# Example: Access the list of years

years = CONFIG["global"]["years"]          # ['1990', '1991', …, '2020']

# Example: Apply leet-speak when the user enables it

if leetmode == "y":
    word = make_leet(word)                 # replaces a→4, i→1, etc.

# Example: Append a random number from the configured range

if randnum == "y":
    word_with_num = f"{word}{random.randint(CONFIG['global']['numfrom'], CONFIG['global']['numto'])}"

These snippets demonstrate the direct link between cupp.cfg entries and runtime behavior in the Mebus/cupp codebase.

Summary

• The [years] section (lines 15–16) provides date suffixes that komb() appends to base words.
• The [leet] section (lines 18–27) defines character substitutions used by make_leet() when transforming words into leet-speak.
• The [specialchars] section (lines 32–34) supplies characters that get appended to words via improve_dictionary().
• The [nums] section (lines 45–48) sets the numeric range (0–100 by default) that concats() uses for random number suffixes.
• The [alecto] section (lines 66–67) stores the URL for external credential databases accessed by alectodb_download().
• The [downloader] section (lines 69–70) configures the base URL for wordlist downloads handled by download_wordlist_http().

Frequently Asked Questions

What is the purpose of the [leet] section in cupp.cfg?

The [leet] section defines letter-to-symbol mappings for leet-speak transformations, such as converting a to 4 and i to 1. When enabled via command-line flags, the make_leet() function uses these mappings to mutate words into common alternative spellings used in passwords.

How does the [years] section affect password generation?

The [years] section contains a comma-separated list of years that CUPP appends to base words during the combination phase. The komb() function pairs each word with every year listed here, creating variations like username1995 or company2020.

What configuration section controls numeric suffixes in CUPP?

The [nums] section controls numeric suffixes by defining from and to integer values (default 0–100). These values populate CONFIG["global"]["numfrom"] and CONFIG["global"]["numto"], which the concats() generator uses to append random numbers within this range to generated words.

Where does CUPP download external wordlists from?

CUPP downloads external wordlists from the base URL specified in the [downloader] section (lines 69–70), stored as CONFIG["global"]["dicturl"]. The download_wordlist_http() function constructs full URLs by appending specific file paths to this base address.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}