# How CUPP Integrates with Alecto DB for Password Generation

> Learn how CUPP integrates with Alecto DB to generate passwords. Discover how to download leaked credentials and create wordlists for password cracking.

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

---

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

```bash
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`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/alectodb-usernames.txt) – Contains unique usernames from the breach data
- [`alectodb-passwords.txt`](https://github.com/Mebus/cupp/blob/main/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:

```bash
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`](https://github.com/Mebus/cupp/blob/main/test_cupp.py) at lines 80-90, the `test_alectodb_download()` function executes the download routine and asserts that both [`alectodb-usernames.txt`](https://github.com/Mebus/cupp/blob/main/alectodb-usernames.txt) and [`alectodb-passwords.txt`](https://github.com/Mebus/cupp/blob/main/alectodb-passwords.txt) are created successfully. This automated validation confirms that the URL in [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/cupp.py) (lines 71-78)
- **Configuration is stored** in [`cupp.cfg`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/alectodb-usernames.txt) and [`alectodb-passwords.txt`](https://github.com/Mebus/cupp/blob/main/alectodb-passwords.txt)
- **Test coverage** validates the pipeline in [`test_cupp.py`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/cupp.cfg).

### What files does CUPP generate from the Alecto database?

CUPP creates two separate wordlist files: [`alectodb-usernames.txt`](https://github.com/Mebus/cupp/blob/main/alectodb-usernames.txt) containing unique usernames from column 5 of the CSV, and [`alectodb-passwords.txt`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/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`](https://github.com/Mebus/cupp/blob/main/alectodb-usernames.txt) or [`alectodb-passwords.txt`](https://github.com/Mebus/cupp/blob/main/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.