How to Add Custom Special Characters for Password Suffixes in CUPP

You can add custom special characters for password suffixes in CUPP by editing the chars= line in the [specialchars] section of cupp.cfg, then running the tool in interactive or wordlist mode.

CUPP (Common User Passwords Profiler) generates targeted wordlists by combining personal data with configurable special characters appended to the end of words. According to the Mebus/cupp source code, modifying the configuration file is the only step required to customize which symbols appear in your generated passwords—no changes to the Python code are necessary.

Understanding the Special Characters Configuration

The cupp.cfg file controls all runtime behavior, including which symbols CUPP appends to candidate passwords. In cupp.py, the read_config() function parses this file at startup and stores the special character list in CONFIG["global"]["chars"] (lines 66-67).

The configuration uses a dedicated [specialchars] stanza located around lines 29-34 of cupp.cfg. This section contains a single key:

[specialchars]
chars=!,@,#,$,%,^,&,*,?,~

The parser splits this comma-separated string, allowing you to define any ASCII or Unicode symbols you need for your target password policy.

Step-by-Step Guide to Adding Custom Special Characters

Follow these steps to customize the suffix characters:

1. Locate the configuration file in the repository root directory: cupp.cfg.

2. Open the file in any text editor and find the [specialchars] section.

3. Edit the chars= line, adding your desired symbols separated by commas. For example, to add brackets and currency symbols:

   [specialchars]
   chars=!,@,#,$,%,^,&,*,?,~,[,],{,},(,),€,£,¥

4. Save the file. CUPP reads this configuration fresh on every execution, so changes take effect immediately.

5. Run CUPP with the -i flag for interactive mode or -w for wordlist improvement, and answer Y when prompted to add special characters.

How CUPP Applies Special Characters to Passwords

When you run CUPP interactively, the script prompts: "Do you want to add special chars at the end of words?" (lines 250-255). If you confirm, the generation logic enters a nested loop structure (lines 260-268) that appends characters from your configured list to each base word.

The default implementation generates combinations up to three levels deep:

• Single character suffixes (e.g., password!)
• Double character combinations (e.g., password!!, password!@)
• Triple character combinations (e.g., password!@#)

This approach ensures comprehensive coverage while keeping file sizes manageable.

Running CUPP with Custom Special Characters

After editing cupp.cfg, execute the interactive mode:

python3 cupp.py -i

When prompted, confirm the special character addition:

> Do you want to add special chars at the end of words? Y/[N]: y

The output file (typically named after the target, e.g., john.txt) will now contain entries using your custom symbols:

john!
john@
john[2020
john€

Extending Character Combination Depth (Optional)

The default three-character depth suits most penetration testing scenarios. However, if your target environment requires longer special character suffixes, you can modify the nested loops in cupp.py around lines 260-268. Add additional for loops to generate four, five, or more character combinations, though be aware this exponentially increases the output file size.

Summary

• Configuration location: Edit cupp.cfg in the repository root, specifically the [specialchars] section.
• Syntax: Use comma-separated values in the chars= line without spaces between characters.
• Application: Run python3 cupp.py -i and answer Y to the special character prompt.
• Implementation: The read_config() function loads your symbols into CONFIG["global"]["chars"], and the generation logic appends them up to three characters deep.
• No code changes required: The Python script automatically reads the updated configuration on startup.

Frequently Asked Questions

Where is the cupp.cfg file located?

The cupp.cfg file resides in the root directory of the Mebus/cupp repository. If you cloned the repository, it sits alongside cupp.py and test_cupp.py. The application expects this file in the working directory or the same folder as the executable script.

Do I need to restart CUPP after editing the configuration?

No, CUPP reads cupp.cfg fresh every time you execute the script. Simply save your changes to the configuration file before running python3 cupp.py, and the new special characters will be loaded immediately via the read_config() function.

Can I use spaces or commas in my special characters?

Commas serve as delimiters in the configuration file, so you cannot include literal commas in the chars= list without modifying the parser. However, you can include any other symbols including spaces, brackets, and Unicode characters. If you need a literal comma, you would need to modify the parsing logic in cupp.py lines 66-67.

How many special characters can I add?

There is no hardcoded limit in the source code. You can add as many symbols as your target password policy requires. Keep in mind that each additional character increases the total wordlist size exponentially, as CUPP generates combinations up to three characters deep for every base word.

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