How to Contribute Wordlists to SecLists: The Complete Contributor Guide

Submit clean, deduplicated wordlists without leading slashes via Pull Request, include a properly formatted README entry, and follow Conventional Commits for attribution.

SecLists is the security community's go-to repository for wordlists used in penetration testing and security assessments. Contributing new wordlists helps the entire industry, but the project maintains strict quality standards to ensure lists remain useful and free of noise. According to the danielmiessler/SecLists source code, all contributions must follow the workflow defined in CONTRIBUTING.md to be accepted.

Preparing Your Wordlist Data

Before submitting, you must clean and standardize your wordlist file. The repository enforces several content rules to prevent false positives and maintain consistency.

Remove Leading Slashes

Every entry must start directly with the path or term, not a forward slash. The guidelines in CONTRIBUTING.md (lines 17-21) explicitly forbid leading / characters.

# Remove leading slashes from every line

sed 's|^/||' raw_wordlist.txt > cleaned_wordlist.txt

Convert entries like /path/to/something to path/to/something.

Deduplicate Entries

Duplicate lines bloat the repository and reduce scanning efficiency. For standard deduplication, use the sort -u command as specified in CONTRIBUTING.md (lines 28-30).

# Linux

sort -u your_wordlist.txt --output clean_file.txt

# Windows (PowerShell with Cygwin)

&"C:\\cygwin64\\bin\\sort.exe" -u your_wordlist.txt --output clean_file.txt

Preserve Probability Order When Needed

For password lists where frequency matters, use a stable deduplication method that preserves the original order. The CONTRIBUTING.md (lines 32-34) recommends gawk for this purpose.

# Linux: Remove duplicates while keeping first occurrence

gawk '!seen[$0]++' your_wordlist.txt > clean_file.txt

# Windows equivalent

&"C:\\cygwin64\\bin\\gawk.exe" '!seen[$0]++' your_wordlist.txt > clean_file.txt

Strip Ambiguous and Common Lines

Remove entries that generate excessive false-positives during security testing. The contribution guidelines (lines 36-39) specifically mention filtering out generic terms like index.html and .git.

Use Placeholders for Variable Data

Replace concrete values such as passwords or session IDs with placeholder syntax to ensure the list remains a template rather than specific exposure data. As documented in CONTRIBUTING.md (lines 41-48), use the format {PLACEHOLDER}.

# Replace sensitive query parameters with placeholders

sed -i 's/password=[^&]*/password={PASSWORD_PLACEHOLDER}/g' cleaned_wordlist.txt

Example transformation:

• Input: path/to/auth?password=secret123
• Output: path/to/auth?password={PASSWORD_PLACEHOLDER}

Organizing Files and Documentation

SecLists requires specific folder structures and documentation standards to help users discover and understand your contribution.

Follow Train-Case Folder Naming

Directory names must use Train-Case (each word capitalized, hyphen-separated, no spaces). The CONTRIBUTING.md (lines 52-53) specifies formats like File-System and Web-Content rather than file_system or webContent.

Include a README Entry

Every new wordlist must be documented in a README.md file inside its folder. If the target directory lacks a README, you must create one. Per CONTRIBUTING.md (lines 56-65), the documentation must include:

• The wordlist filename as the heading
• A "Use for:" line describing the purpose
• A "Source:" line linking to the origin
• An optional "Reference:" line for additional context

## example-credentials.txt

Use for: Credential stuffing attacks against web applications.

Source: https://example.com/security/wordlists/example-credentials.txt
Reference: https://example.com/blog/credential-stuffing-research

Submitting Your Contribution

Once your wordlist is cleaned and documented, submit it through the proper channels with appropriate attribution.

Choose Your Submission Method

The repository accepts contributions via Pull Request (preferred) or Issue with links to the list, as stated in CONTRIBUTING.md (lines 6-10). Pull requests allow for easier review and integration of the actual file content.

Use Conventional Commits

While optional, following the Conventional Commits specification helps maintain a clear project history. The guidelines (lines 70-88) recommend these patterns:

• New wordlists: feat(wordlist): Added "example" wordlist by AUTHOR
• Corrections: fix(wordlist): Fixed typo in "example.txt"
• Updates: update(wordlist): Updated "example.txt" with 100 new entries

git add Web-Content/example-paths.txt Web-Content/README.md
git commit -m "feat(wordlist): Added \"example-paths.txt\" wordlist by JaneDoe"

Provide Attribution

Always credit the original author or source when submitting wordlists gathered from research or third-party sources. The contribution rules (lines 11-12) explicitly require proper attribution to respect intellectual property and maintain transparency.

Leverage Helper Scripts

The repository includes utility scripts in the .bin/ directory (referenced in the root README.md, lines 95-102) that can assist with generating or mutating wordlists. While not mandatory, tools like mutate-wordlist.sh can streamline the creation of large or complex contributions.

Summary

• Strip leading slashes from every entry and deduplicate using sort -u (for sorted lists) or gawk '!seen[$0]++' (for probability-ordered lists).
• Remove ambiguous entries like index.html and replace variable data with {PLACEHOLDER} syntax.
• Use Train-Case for folder names (e.g., Web-Content) and document every wordlist in a folder-specific README.md with Source and Use-for lines.
• Submit via Pull Request with Conventional Commit messages (e.g., feat(wordlist): Added...) and include proper attribution to the original source.

Frequently Asked Questions

Can I submit a wordlist that contains duplicate entries if the duplicates represent frequency?

No. If you need to preserve probability order (where earlier entries appear more frequently), use the stable deduplication method gawk '!seen[$0]++' as specified in CONTRIBUTING.md (lines 32-34). This keeps the first occurrence of each entry while removing subsequent duplicates, maintaining the frequency distribution without bloating the file with identical lines.

What should I do if the target folder doesn't have a README.md file?

You must create one. According to the contribution guidelines (lines 56-65), every new wordlist requires documentation in a README.md within its folder. Create the file using Train-Case folder naming, then add an entry with the wordlist filename as the heading, followed by "Use for:", "Source:", and optional "Reference:" lines.

Are there specific file naming conventions for the wordlists themselves?

While the repository doesn't enforce strict filename patterns in the contribution guide, you must place files in properly named directories using Train-Case (e.g., Passwords/, Discovery/Web-Content/). The filename should clearly describe the content (e.g., common-admin-paths.txt) and must be referenced exactly in the folder's README.md heading.

Is it mandatory to use Conventional Commits for my contribution?

No, but it is strongly encouraged. The CONTRIBUTING.md (lines 70-88) states that following the Conventional Commits specification (using prefixes like feat(wordlist): or fix(wordlist):) helps maintain a clean project history and makes your contribution easier to review and categorize in the changelog.

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