DEV Community

gamie
gamie

Posted on

I Built a Targeted Wordlist Generator in Go (and It's Actually Pretty Cool)

#go #security #opensource #pentest

So I've been doing some security work lately and kept running into the same problem: generic wordlists like rockyou.txt are massive but totally untargeted. If you're doing an authorized pentest or internal security awareness audit, you don't need millions of random passwords — you need a few thousand smart ones based on what you know about the target.

That's why I built Valence.

What is it?

Valence is a CLI tool that takes a personal profile (name, birthdate, pet's name, partner, city, etc.) and generates a deduplicated list of password candidates that mirror how real people actually create passwords.

The name comes from chemistry — the idea that atoms bond to form new structures. Here, personal data points are the atoms, and Valence bonds them together in every meaningful way.

valence -first John -last Smith -pet Max -birthdate 1990-05-15
Enter fullscreen mode Exit fullscreen mode

That one command generates candidates like john123, MaxSmith!, j0hn_1990, nhoj@smith, 5m1th1990 — you get the idea.

The fun stuff it does

Leet-speak substitutions — not just simple a→@ swaps. It applies 1-, 2-, and 3-rule combinations, so you get j0hn, j@ne, $m1th, and everything in between.

Per-character toggle case — generates all 2ⁿ combinations for each token. jOhN, JoHn, jOHn... yeah, it covers them all.

Birthdate expansion — a single 1990-05-15 expands into 1990, 90, 0515, 1505, 15051990, 05151990, and more.

Phone number derivation — plug in 555-123-4567 and it automatically extracts last-4 (4567), last-6 (234567), area code (555), and the full digits.

Common-word mixing — pairs profile tokens with real-world breach-corpus words. Think johnlove, dragonsmith, ilovejohn. These show up constantly in real password dumps.

Reversed tokens — nhoj, htims. Sounds weird but people actually do this.

Initials — derives JSmith and JohnS style tokens automatically.

And it all runs through a prefix → mutate → suffix → pair → word-mix → deduplicate pipeline that keeps output clean and sorted.

Two ways to use it

Interactive mode — just run valence with no flags and it walks you through everything:

Valence — interactive profile builder
Leave any field blank to skip it.

  First name:           John
  Last name:            Smith
  Pet's name:           Max
  Date of birth:        1990-05-15

  Output file [john_smith.txt]:
Enter fullscreen mode Exit fullscreen mode

Flag mode — great for scripting:

valence -first John -last Smith -nick Johnny \
        -partner Sarah -pet Max -child Emma \
        -phone "555-123-4567" -city Bangkok \
        -username j0hn -birthdate 1990-05-15 \
        -o john_smith.txt
Enter fullscreen mode Exit fullscreen mode

Pipe it anywhere

stdout is reserved for candidates only; metadata goes to stderr. So you can pipe directly into hashcat without any cleanup:

valence -first John -pet Max | hashcat -a 0 -m 1000 hashes.txt
Enter fullscreen mode Exit fullscreen mode

Or filter it:

valence -first John -birthdate 1990-05-15 | sort -u > candidates.txt
Enter fullscreen mode Exit fullscreen mode

Zero dependencies

The whole core engine (pkg/profiler) runs on Go's standard library — no third-party packages. That means it's auditable, embeddable, and you can import it into your own tools (web service, TUI, Burp extension, whatever).

The architecture splits the core from the CLI intentionally. pkg/profiler just does the work; main.go just handles I/O. Clean separation.

Installing it

Homebrew (macOS/Linux):

brew tap g4m3m4g/tap
brew install valence
Enter fullscreen mode Exit fullscreen mode

curl one-liner (no Go required):

curl -fsSL https://raw.githubusercontent.com/g4m3m4g/Valence/main/scripts/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

Go install:

go install github.com/g4m3m4g/valence@latest
Enter fullscreen mode Exit fullscreen mode

The obvious disclaimer

This is strictly for authorized security work. Pentests, internal audits, security awareness campaigns — that kind of thing. Using it against accounts or individuals without explicit written authorization is illegal in pretty much every jurisdiction, and that's not what this is for. The README has a full legal breakdown if you want the details.

If you're doing authorized security auditing and you're tired of blasting through 14 GB wordlists hoping for a hit, give Valence a try. It's a much more surgical approach.

GitHub: g4m3m4g/Valence

Feedback welcome — especially if you've built something similar and have thoughts on the mutation pipeline.

Top comments (0)