How to Configure Leet Mode Character Mappings in cupp.cfg

You configure leet mode character mappings by editing the [leet] section in cupp.cfg, where each line maps a plain character to its leet replacement (e.g., a=4), and CUPP automatically loads these mappings via the read_config() function.

CUPP (Common User Passwords Profiler) generates personalized password lists using target information. The leet mode (1337-speak) feature substitutes standard characters with numeric or symbolic equivalents to create variants like "p4ssw0rd", and you can configure leet mode character mappings in cupp.cfg to customize these substitutions for your specific use case.

Understanding the Default Leet Mode Mapping

The leet mode mapping is defined in cupp.cfg under the [leet] section (lines 19‑26). By default, CUPP uses the following character replacements:

Plain	Leet
a	4
i	1
e	3
t	7
o	0
s	5
g	9
z	2

These entries are stored as key-value pairs in the configuration file. When CUPP runs with leet mode enabled, it uses this mapping to transform password candidates by replacing every occurrence of the plain character with its defined substitute.

How CUPP Loads the Configuration

According to the CUPP source code in cupp.py, the read_config() function (lines 76‑84) reads the [leet] section and populates the global CONFIG["LEET"] dictionary. This happens automatically when the tool starts, requiring no manual intervention beyond ensuring the configuration file exists in the repository root.

You can verify the loaded mapping at runtime:

from cupp import read_config, CONFIG

read_config("cupp.cfg")
print(CONFIG["LEET"])

# Output: {'a': '4', 'i': '1', 'e': '3', 't': '7', 'o': '0', 's': '5', 'g': '9', 'z': '2'}

Customizing Character Mappings in cupp.cfg

To configure custom leet mode character mappings, follow these steps:

1. Open cupp.cfg in the repository root directory.

2. Locate the [leet] section and modify existing entries or add new ones using the format character=replacement.

3. Save the file—CUPP does not require recompilation or source code changes because read_config() dynamically reads every entry under [leet].

For example, to change the mapping for a to @ instead of 4, and to add b mapping to 8:

[leet]
a=@
i=1
e=3
t=7
o=0
s=5
g=9
z=2
b=8

Applying the Custom Mappings

When leet mode is enabled (via the -i interactive prompt or -w improvement step when prompted "Leet mode? (i.e. leet = 1337) Y/[N]"), CUPP passes each word through the make_leet() function (lines 95‑99 in cupp.py). This function iterates over CONFIG["LEET"] and substitutes every occurrence of each key with its corresponding value.

To test your custom mappings programmatically:

from cupp import read_config, make_leet, CONFIG

# Load your customized configuration

read_config("cupp.cfg")

# Test with default mapping

word = "password"
print(make_leet(word))  # Returns: p455w0rd

# Test with custom mapping (if you added b=8)

word2 = "bob"
print(make_leet(word2))  # Returns: 808

Summary

• Leet mode mappings are stored in the [leet] section of cupp.cfg (lines 19‑26).
• The read_config() function in cupp.py (lines 76‑84) automatically loads these into CONFIG["LEET"].
• You can add, modify, or remove mappings by editing the INI-style key-value pairs without changing source code.
• The make_leet() function (lines 95‑99) applies these mappings when generating password candidates.
• Changes take effect immediately the next time you run CUPP with leet mode enabled.

Frequently Asked Questions

Where is the cupp.cfg file located?

The configuration file resides in the repository root directory alongside cupp.py. CUPP expects to find it in the current working directory when you execute the script.

Do I need to restart CUPP after editing cupp.cfg?

Yes, you must restart CUPP for configuration changes to take effect. The read_config() function only executes during initialization, so edits made while the program is running are not picked up dynamically.

Can I add custom characters beyond the default set?

Yes. The read_config() function reads every entry under the [leet] section automatically, so you can add mappings for any character (e.g., b=8, l=1) without modifying the Python source code.

How does the make_leet() function apply these mappings?

The make_leet() function iterates over the CONFIG["LEET"] dictionary and uses string replacement to substitute every occurrence of each plain character with its configured leet equivalent. This transformation occurs after the base word generation when leet mode is enabled.

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