How carolqian31/fepguesser works
Project Type and Purpose
• FEPGuesser is a single codebase for a machine-learning-driven password guessing system. It is composed of three tightly related components:
• PSVG: a password segmentation and wordlist generation module
• PassExBert: a BERT-based masked language model pretraining module that incorporates custom mixed vocabularies
• PassExBertVAE: a variational autoencoder module built on top of the pre-trained BERT embeddings to generate candidate passwords and perform attack experiments
• The system’s primary goal is to take raw password corpora, segment them, build a richer vocabulary, train a language model, refine it with a VAE, and then sample guess candidates.
File-Structure Analysis
• Top-level directories:
• PSVG: scripts and submodule for segmentation, rules for detecting tokens, and utilities to produce segmented output
• passExBert: building mixed vocab from segments, ExBERT model code (tokenization, modeling, optimization), a pretraining driver, plus configuration and vocabulary storage
• passExBertVAE: VAE wrapper modules (encoder, decoder, sampler), training and sampling scripts, parameter utilities, and experiment code
• Configuration files and vocab reside under config_and_vocab and bert_config_and_vocab, respectively
• requirements.txt lists external dependencies (PyTorch, Huggingface transformers, etc.)
• The workflow is driven by CLI scripts that chain data files, config JSONs, pretrained BERT weights, and output storage folders.
Key Components and Relationships
a. Data Input
• Raw password datasets (plain text files)
• Pretrained BERT weights from Huggingface
b. PSVG Module
• segmntr.py: segments passwords into subword tokens
• get_wordlist_from_segment.py: filters segments by frequency threshold
• detection_rules: custom rules for segment detection
→ Output: a wordlist.txt
c. Vocabulary Builder
• build_pass_vocab_from_word_list.py: merges custom wordlist with original BERT vocab
→ Output: mixed_vocab.txt
d. PassExBert Pretraining
• pretraining_pass.py: fine-tunes BERT on password data with masks
• exBERT subpackage: tokenization, modeling, optimization routines
• Output: trained PassExBert checkpoint and dict file
e. PassExBertVAE Training
• train_chunk.py: loads PassExBert embeddings, encodes sequences into latent space, decodes them, applies VAE losses
• selfModules & model subpackages: encoder, decoder, VAE wrapper
• Output: VAE checkpoints
f. Sampling and Attack
• PassExBert_sample.py: samples from VAE latent space using beam search or Gaussian noise, generates password guesses
• guess.py: utilities for scoring or testing guesses
g. Storage and Outputs
• Storage folders (./storage and data/...) for model checkpoints, logs, and generated samples
• Logger utilities under utils/
Architectural Patterns and Design Principles
• Modular ML pipeline: each stage (segmentation, vocab, pretraining, VAE) is a standalone CLI that takes inputs and produces outputs for the next stage
• Use of configuration files (JSON) to parameterize each stage, enabling reproducibility
• Separation of concerns: PSVG handles data preprocessing, PassExBert handles language modeling, PassExBertVAE handles generative modeling
• Extensibility: detection_rules, selfModules, and config_and_vocab directories show plug-and-play pattern