How to Add Custom Special Characters for Password Generation in CUPP

Adding custom special characters to CUPP requires editing the chars= line in the [specialchars] section of cupp.cfg with comma-separated symbols, then running CUPP in interactive mode and confirming the special characters prompt.

CUPP (Common User Passwords Profiler) generates targeted wordlists by combining personal information with configurable special characters. The tool stores its symbol set in an external configuration file, allowing security researchers to customize password generation without modifying the Python source code.

Understanding CUPP's Special Character System

Configuration Loading

According to the Mebus/cupp source code, the read_config() function in cupp.py (lines 66-67) parses cupp.cfg at startup and stores the special characters list in CONFIG["global"]["chars"]. This dictionary drives all subsequent password generation operations.

Generation Logic

When you run CUPP in interactive mode (-i) or improve mode (-w), the script prompts "Do you want to add special chars at the end of words?" (lines 250-255). If you confirm, the code iterates through the configured character set up to three levels deep (lines 260-268), appending each combination to candidate passwords. This nested loop structure automatically incorporates any symbols you define in the configuration file.

Step-by-Step Guide to Adding Custom Characters

1. Locate the configuration file. Open cupp.cfg in the repository root directory. This file contains all runtime parameters for the wordlist generator.

2. Find the special characters section. Navigate to the [specialchars] stanza, typically found around lines 29-34 in cupp.cfg.

3. Modify the character list. Edit the chars= line to include your desired symbols as comma-separated values. For example:

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

4. Save the file. No changes to cupp.py are required because the configuration loads dynamically at runtime.

Running CUPP with Custom Characters

After updating the configuration, execute CUPP in interactive mode:

python3 cupp.py -i

When prompted "Do you want to add special chars at the end of words?", answer Y. The generator will now append your custom symbols to all password candidates. The output file (typically named after the target, such as john.txt) will contain entries like:

john!john1
john@123
john~2020
john!=2024

Extending Combination Depth (Optional)

By default, CUPP generates combinations up to three special characters deep via nested loops in cupp.py (lines 260-268). If your use case requires longer sequences (such as four or five trailing symbols), you must manually extend these loops in the source code. For most penetration testing scenarios, the default three-character depth provides sufficient coverage.

Summary

• Configuration location: Edit cupp.cfg in the repository root, specifically the [specialchars] section.
• No code changes required: cupp.py reads CONFIG["global"]["chars"] dynamically via read_config().
• Format: Use comma-separated values in the chars= line.
• Activation: Run with -i or -w flags and confirm the special characters prompt.
• Output: Generated wordlists automatically include passwords ending with your custom symbols.

Frequently Asked Questions

Where does CUPP store its special characters configuration?

CUPP stores special characters in the cupp.cfg file at the repository root, within the [specialchars] section. The read_config() function in cupp.py loads these values into CONFIG["global"]["chars"] during startup.

Can I add special characters without modifying Python code?

Yes. You only need to edit the cupp.cfg file. Add your symbols to the chars= line as comma-separated values, save the file, and run CUPP normally. The tool reads the configuration dynamically, so no changes to cupp.py are necessary.

Is there a limit to how many special characters I can add?

There is no hardcoded limit in the configuration parser. You can add as many comma-separated symbols as needed. However, remember that each additional character increases the wordlist size exponentially due to the three-level combination generation in lines 260-268 of cupp.py.

Does CUPP support multi-character strings as special characters?

The configuration parser splits the chars= value by commas, so individual entries can technically contain multiple characters (like abc or ?!). However, the generation logic treats each entry as a single unit to append, so test your specific use case to ensure the output matches your expectations.

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