# How to Configure Leet Mode Character Mappings in cupp.cfg

> Learn to configure leet mode character mappings in cupp.cfg by editing the [leet] section. Map plain characters to their leet replacements for enhanced password cracking.

- Repository: [Mebus/cupp](https://github.com/Mebus/cupp)
- Tags: how-to-guide
- Published: 2026-07-03

---

**You configure leet mode character mappings by editing the `[leet]` section in [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/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:

```python
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`](https://github.com/Mebus/cupp/blob/main/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`:

```ini
[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`](https://github.com/Mebus/cupp/blob/main/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:

```python
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`](https://github.com/Mebus/cupp/blob/main/cupp.cfg) (lines 19‑26).
- The **`read_config()`** function in [`cupp.py`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/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.