Golemorph

Coherent synthetic personas for authorized red-team spearphishing engagements.

Every identity is internally consistent - name, email, phone, age, city and role all follow the chosen origin, across 45 locales.

Features

• Coherent identities - name, email, phone, age, city and role all match the origin's language, dial code and conventions.
• 45 locales, grouped by region, every name romanized to Latin (accents kept) so emails stay readable.
• Credible by default - frequency-weighted sampling bounded to a percentile band that skips both "John Doe" names and odd, unplaceable ones.
• Realistic emails - several local-part layouts (first.last, jdupont, dupont.jean, ...) over region-appropriate domains.
• Ready-to-use exports - a rich color table for the terminal, plus csv, json, and a GoPhish group-import CSV.
• Reproducible - --seed makes any campaign repeatable.

Install

Requires Python 3.11+.

pipx install golemorph

From source

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# optional: tests + data regeneration
pip install -r requirements-dev.txt

Or run it straight from the repo root without installing (needs its runtime deps, PyYAML and rich - pip install -r requirements.txt):

python3 -m golemorph --help

Quick start

# 45 supported origins, grouped by region (filter: europe|americas|africa|asia)
golemorph --list-origins
golemorph --list-origins europe

# Five Russian personas, full JSON records
golemorph -o RUS -n 5 --format json

# 100 French personas, gophish CSV format saved in custom file
golemorph -o FRA -n 100 -f gophish --output targets.csv

# 50 personas, no repeated name, reproducible
golemorph -o DEU -n 50 --unique --seed 7

With no arguments, Golemorph prints a single American persona (the default origin is USA) as a table. The default name format renders a rich, color table - name, age, birth year, city, language, role, phone, email and the commonality score; use -f csv/json for machine-readable output.

Options

Output formats

• name (default): a rich, color table of the headline fields - name, age, birth year, city, language, role, phone, email and commonality. Color and box drawing are dropped automatically when the output is piped or redirected.
• csv: one row per persona with the full record - id, gender, first_name, last_name, origin_code, origin_label, nationality, language, name_order, birth_year, age, email, phone, city, role, first_name_percentile, last_name_percentile, commonality, full_name.
• json: one JSON array of full records, same fields as the CSV.
• gophish: the GoPhish group-import template - First Name, Last Name, Email, Position rows (Position carries the persona's role), ready to import directly into a GoPhish target group.

Origins

Golemorph ships 45 origins across Europe, the Americas, Africa, the Middle East and Asia-Pacific:

--list-origins prints them as color tables, one per region, and takes an optional group filter:

Full table with language, name order, dial code and nationality wording: docs/origins.md.

Data

Names are sampled (by default with replacement; see --unique) from per-origin CSVs generated from names-dataset 3.3.1 (Facebook, ~533M users) by scripts/generate_name_data.py:

• Frequency-weighted sampling, with long-tail counts decayed along a Zipf-like curve so mid-tier names are drawn far more often than raw counts alone would suggest. --unweighted switches to uniform.
• Credible band: by default the draw is bounded to a percentile band (--min-common / --max-common) that drops both the most common names, which read as "John Doe" placeholders, and the rarest, least placeable ones.
• Unique names: --unique rejects and redraws duplicates so a chosen part of the name never repeats across the run - full (whole name, the default), first (given names) or last (surnames). --unique full still lets a first name or surname recur in a different pairing; first/last keep that one field strictly distinct. Errors if the pool is too small.
• Gendered first names; Russian surnames carry romanized gendered forms (Ivanov/Ivanova), and a female persona never draws the male form.
• Latin-only spellings: every locale keeps its romanized names (accents allowed, e.g. José, Müller), so native-script entries (Arabic, Cyrillic, Greek, CJK, Hangul) are dropped in favour of their Latin forms and emails stay name-based.
• Surnames drop standalone name particles (El, Ben, Da, De, Von, Ait, ...) that the source stores as entries in their own right because it splits compound names on the space; genuine short surnames that collide with those tokens (Le, Do, Du, Ba, Das, Dal) are kept.
• Emails mix several realistic local-part layouts (first.last, firstlast, jdupont, j.dupont, jean.d, dupont.jean, with an optional numeric suffix) over a regional domain; phone numbers follow the origin's dial code and mobile prefix.

Regenerate the shipped data. The source dataset ships inside the names-dataset package (a dev dependency), so there is nothing to download by hand and it works on any OS:

pip install -r requirements-dev.txt   # installs names-dataset + PyYAML
python3 scripts/generate_name_data.py

Tests

python3 -m pytest tests/