How CUPP Integrates with Alecto DB for Password Generation

CUPP integrates with the Alecto database by downloading a compressed CSV of leaked credentials via the -a flag, extracting usernames and passwords into two sorted, deduplicated wordlists ready for password profiling or cracking.

CUPP (Common User Password Profiler) is a powerful open-source tool for generating customized wordlists based on target profiling. When security researchers need real-world leaked credentials to enhance dictionary attacks, the CUPP Alecto DB integration provides immediate access to millions of previously exposed usernames and passwords. This functionality pulls data directly from the Alecto project's curated database of breached credentials, as implemented in the Mebus/cupp repository.

Activating Alecto Integration via Command Line

The Alecto DB integration is triggered through a dedicated command-line argument. In cupp.py at lines 71-78, the CLI parser defines the -a (or --alecto) flag that initiates the Alecto import routine.

When you execute CUPP with this flag, the main() function immediately calls alectodb_download() to begin the retrieval process:

python3 cupp.py -a

This single command launches the complete pipeline: downloading the compressed database, extracting credential pairs, and generating the final wordlist files.

Configuring the Data Source

Before any download occurs, CUPP reads the remote database location from its configuration file. In cupp.cfg at lines 65-68, the [alecto] section contains the alectourl parameter, which stores the HTTP endpoint for the compressed CSV dump.

This configurable approach allows you to update the source URL without modifying the core Python code. The configuration entry specifies the location of alectodb.csv.gz, ensuring CUPP always pulls from the correct Alecto repository mirror.

The Download and Extraction Pipeline

The alectodb_download() function in cupp.py (lines 715-753) orchestrates the entire data processing workflow. This function handles four critical operations:

HTTP Retrieval and Caching

First, the function checks for the existence of alectodb.csv.gz in the local directory. If the file is missing, it invokes download_http() to fetch the archive from the URL specified in cupp.cfg. This prevents unnecessary re-downloads during repeated executions.

CSV Parsing and Column Extraction

Once the compressed file is available, the function opens the gzip archive and iterates through each CSV row. It specifically extracts column 5 (username) and column 6 (password) from the database schema, ignoring other metadata fields.

Deduplication and Sorting

To ensure optimal wordlist quality, the function de-duplicates the extracted credentials and sorts them alphabetically. This eliminates redundant entries that would slow down password cracking attempts while maintaining a predictable file structure.

File Output Generation

Finally, the processed data writes to two distinct plain-text files:

• alectodb-usernames.txt – Contains unique usernames from the breach data
• alectodb-passwords.txt – Contains unique passwords from the breach data

These files appear in your working directory and are immediately ready for use.

Consuming Alecto Wordlists in CUPP

The generated wordlists integrate seamlessly with CUPP's existing functionality. You can feed either file into the wordlist improvement feature using the -w flag:

python3 cupp.py -w alectodb-usernames.txt

This merges the Alecto credentials with your existing dictionary, creating an enhanced wordlist that combines real-world breach data with target-specific profiling. Alternatively, you can use these files directly with external password cracking tools like Hashcat or John the Ripper.

Automated Verification

The project includes unit tests to ensure the Alecto integration remains functional. In test_cupp.py at lines 80-90, the test_alectodb_download() function executes the download routine and asserts that both alectodb-usernames.txt and alectodb-passwords.txt are created successfully. This automated validation confirms that the URL in cupp.cfg remains accessible and the extraction logic functions correctly across different environments.

Summary

• Use the -a flag to trigger Alecto DB downloads via the CLI parser in cupp.py (lines 71-78)
• Configuration is stored in cupp.cfg under the [alecto] section with the alectourl parameter (lines 65-68)
• The alectodb_download() function handles HTTP retrieval, gzip extraction, and CSV parsing at lines 715-753
• Two output files are generated: alectodb-usernames.txt and alectodb-passwords.txt
• Test coverage validates the pipeline in test_cupp.py (lines 80-90) ensuring both files are created

Frequently Asked Questions

How do I enable Alecto DB integration in CUPP?

Add the -a or --alecto flag when running CUPP from the command line. This triggers the alectodb_download() function in cupp.py to fetch and process the latest Alecto database dump. The flag requires no additional arguments, as the source URL is read automatically from cupp.cfg.

What files does CUPP generate from the Alecto database?

CUPP creates two separate wordlist files: alectodb-usernames.txt containing unique usernames from column 5 of the CSV, and alectodb-passwords.txt containing unique passwords from column 6. Both files are deduplicated, sorted, and stored as plain text in your working directory.

Where does CUPP store the Alecto database URL?

The download URL is stored in the cupp.cfg configuration file within the [alecto] section as the alectourl parameter (lines 65-68). This externalized configuration allows you to update the data source without modifying the Python source code in cupp.py.

Can I use the Alecto wordlists with CUPP's wordlist improvement feature?

Yes. After generating the Alecto files, pass either alectodb-usernames.txt or alectodb-passwords.txt to the -w flag to merge them with your existing dictionaries. This combines real-world breach data with CUPP's profiling capabilities for more effective password attacks.

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