How to Contribute to SecLists: A Complete Guide to Submitting Security Wordlists

Contributing to SecLists requires forking the repository, placing cleaned wordlists in the appropriate Train-Case directory (e.g., Passwords/), updating the folder's README.md with attribution, and submitting a pull request using Conventional Commit syntax.

SecLists is the security community's premier curated collection of wordlists for penetration testing and vulnerability research. If you have discovered or curated valuable usernames, passwords, or fuzzing payloads, learning how to contribute to SecLists ensures your data reaches thousands of security professionals worldwide. The process is governed by the guidelines in the project's CONTRIBUTING.md and emphasizes clean data, proper attribution, and consistent documentation.

Prerequisites and Repository Structure

Before submitting wordlists, familiarize yourself with the repository layout and key files. SecLists follows an MIT License and organizes content into Train-Case directories such as Passwords/, Usernames/, and Fuzzing/.

The following files provide essential context for contributors:

• CONTRIBUTING.md: Contains detailed contribution rules, data-cleaning steps, commit style requirements, and a flowchart for commit types.
• README.md: Provides high-level project description, installation instructions, and links to other documentation.
• CONTRIBUTORS.md: Lists all recognized contributors and their credits.
• .bin/: Houses helper scripts including wordlist mutators and update tools useful for generating or cleaning lists.
• Folder-specific README.md: Each category directory (e.g., Passwords/README.md, Usernames/README.md) provides context and catalogs existing lists.

Step-by-Step Contribution Workflow

1. Fork and Clone the Repository

Create your own copy of the repository and clone it locally. Use --depth 1 to minimize download time if you do not need full git history.

git clone --depth 1 https://github.com/danielmiessler/SecLists.git
cd SecLists
git checkout -b add-my-wordlist

2. Prepare Your Wordlist Data

Clean your data according to the standards defined in CONTRIBUTING.md. Raw wordlists often contain noise that must be removed before submission.

Execute the following cleaning steps:

• Remove leading slashes: Convert /path/to/file to path/to/file.
• Remove duplicate lines: Use sort -u to ensure uniqueness.
• Strip ambiguous entries: Remove common noise such as index.html or generic placeholders.
• Sanitize sensitive parameters: Replace actual credentials with placeholders like {PASSWORD_PLACEHOLDER} when documenting examples.

# Remove duplicate lines (Linux/macOS)

sort -u your_wordlist.txt -o your_wordlist.txt

# Verify no leading slashes remain

sed -i 's/^\///' your_wordlist.txt

3. Place Files in the Correct Directory

Move your cleaned wordlist into the appropriate Train-Case folder. Do not create new top-level directories without justification. Valid locations include Passwords/, Discovery/Web-Content/, or Usernames/.

cp your_wordlist.txt Passwords/

4. Update Folder Documentation

Every wordlist must be documented in its folder's README.md. Add an entry containing the filename, optional "Use for:" description, source link, and reference link.

cat <<EOF >> Passwords/README.md

## your_wordlist.txt

Use for: Common weak passwords discovered in recent breaches.  
Source: https://example.com/wordlist-source  
Reference: https://example.com/blog/post-about-wordlist
EOF

5. Commit Using Conventional Commits

SecLists requires Conventional Commit syntax to maintain a readable history. Refer to the flowchart in CONTRIBUTING.md for guidance on selecting the appropriate type.

Format your commit message as follows:

feat(wordlist): Added "raft" wordlist by Google

Stage your changes and commit:

git add Passwords/your_wordlist.txt Passwords/README.md
git commit -m "feat(wordlist): Added your_wordlist.txt by YourName"
git push origin add-my-wordlist

6. Submit Your Pull Request

Open a pull request against the master branch from your fork. Include a brief description of the list, its source, and any preprocessing you performed. Maintainers will review for formatting, attribution accuracy, and security concerns before merging.

Data Cleaning Requirements

The CONTRIBUTING.md file mandates specific preprocessing to ensure wordlist quality. Contributions failing these standards will be rejected.

• Deduplication: Use sort -u to eliminate redundant entries. Duplicate lines bloat the repository and reduce scanning efficiency.
• Normalization: Ensure no absolute paths (entries starting with /) remain in the list, as these represent filesystem noise rather than target strings.
• Contextual filtering: Remove entries like index.html that appear in virtually every web directory and provide no discriminatory value during security testing.
• Attribution placeholders: When including example payloads with sensitive parameters, use bracketed placeholders such as {PASSWORD_PLACEHOLDER} rather than real credentials.

Helper Scripts and Tools

The .bin/ directory contains utility scripts for list generation and maintenance. These tools can automate mutations, format conversions, and validation checks. Review the scripts in this directory before manually processing large wordlists, as they may significantly reduce preparation time.

Summary

• Fork the danielmiessler/SecLists repository and create a feature branch.
• Clean your wordlist by removing duplicates with sort -u, stripping leading slashes, and filtering ambiguous entries.
• Place files in the appropriate Train-Case directory (e.g., Fuzzing/, Discovery/).
• Document your contribution in the folder's README.md with source attribution.
• Commit using Conventional Commits format: feat(wordlist): description.
• Submit a pull request to the master branch with detailed description.

Frequently Asked Questions

What file format should wordlists use?

SecLists accepts plain text files (.txt) with one entry per line. Ensure files use Unix line endings (LF) rather than Windows (CRLF) format. Binary formats or compressed archives are not accepted unless specifically requested for specialized payloads.

How do I clean and deduplicate a wordlist before submitting?

Use the sort -u command to remove duplicate lines while sorting alphabetically. Additionally, strip leading slashes using sed and remove common noise entries like index.html or robots.txt that lack discriminatory value. The CONTRIBUTING.md file provides specific patterns to filter.

Where should I place new wordlists in the repository structure?

Place wordlists in the appropriate Train-Case directory such as Passwords/, Usernames/, or Discovery/Web-Content/. Do not create new top-level directories. If uncertain, examine the existing folder structure in the repository root and follow the naming conventions established in README.md files.

What commit message format does SecLists require?

SecLists requires Conventional Commits syntax. Use feat(wordlist): as the prefix for new wordlists, followed by a concise description. For example: feat(wordlist): Added "raft" wordlist by Google. Refer to the flowchart in CONTRIBUTING.md to select the correct commit type for updates, fixes, or documentation changes.

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