# Pawpy
**最强大的字典生成器**
## ⚠️ 仅限合法使用
Pawpy **专门**为授权的安全测试、密码审计和教育目的而设计。未经授权对你不拥有或没有明确测试许可的系统或账户进行使用是**违法且不道德的**。使用此工具即表示你确认已获得适当的授权。
## 目录
- [概述](#overview)
- [功能](#features)
- [安装说明](#installation)
- [快速开始](#quick-start)
- [CLI 参考](#cli-reference)
- [Profile 格式](#profile-format)
- [变异引擎](#mutation-engine)
- [评分与过滤](#scoring--filtering)
- [API 与 Dashboard](#api--dashboard)
- [OSINT 插件](#osint-plugins)
- [项目结构](#project-structure)
- [开发指南](#development)
- [许可证](#license)
## 概述
Pawpy 是一款开源的、基于终端的字典生成器，具备强大的变异引擎、Markov 链混合、hashcat 规则文件支持、混合掩码攻击以及内置的 Web Dashboard。它将目标 profile 信息转换为全面、符合策略的密码候选列表，适用于授权的渗透测试和安全研究。
该工具采用模块化的 pipeline 架构：profile 数据依次流经多个变异阶段（leet-speak、mangle 规则、日期排列、键盘步进、Markov 混合、自定义模板、hashcat 规则、混合掩码），随后通过可选的评分和策略过滤，最终生成去重且排序好的字典。
## 功能
### 核心
| 功能 | 描述 |
|---------|-------------|
| **交互式 Profiling** | 用于收集目标信息的问卷 |
| **JSON 导入** | 从 JSON 文件加载单个或多个目标的 profile |
| **多目标交叉引用** | 合并多个 profile 以进行交叉引用的密码生成 |
| **OSINT 插件系统** | 从 `profile/plugins/` 自动发现并执行 OSINT 插件 |
| **内置 Top 10K 密码** | 附带常见密码；可从 SecLists 自动更新 |
### 变异引擎
| 变异 | 描述 |
|----------|-------------|
| **Leet Speak** | 3 个替换级别（基础、扩展、激进）及组合扩展 |
| **日期排列** | 每个日期有 20 多种变体：DDMM, MMDD, YYYY, YY 及分隔符组合 |
| **常见 Mangle 规则** | 首字母大写、全大写、全小写、反转、大小写互换、追加/前置数字与符号 |
| **Hashcat 规则引擎** | 支持 hashcat/John 风格 `.rule` 文件的完整解析器 (l, u, c, r, $X, ^X, sXY, iNX, oNX, d, p, z, [N, ]N) |
| **静态键盘步进** | 25 多种内置经典模式 (qwerty, asdf, zxcvbn, 1qaz2wsx, ...) |
| **动态键盘步进** | 在 QWERTY 邻接图上进行 BFS 生成的、长度可配置的步进 |
| **双词组合** | 所有基础词汇的两两组合，包含 8 种分隔符变体及大小写组合 |
| **年份-词汇混合** | 向所有基础词汇追加/前置年份（1990-当前）及两位数年份 |
| **Markov 混合** | 基于语料库和 profile 词汇训练的字符级 Markov 链（1-4 阶） |
| **自定义模板** | 模式引擎：带有 token 解析和组合扩展的 `[FirstName][Year][!]` |
| **混合掩码攻击** | 模拟 hashcat 的 `-a 6`（单词 + 右侧掩码）和 `-a 7`（左侧掩码 + 单词） |
### 评分与过滤
| 功能 | 描述 |
|---------|-------------|
| **zxcvbn 评分** | 可选的基于强度的修剪（分数 0-4），用于移除极其脆弱的候选项 |
| **策略过滤** | 强制要求最小长度、大写字母、小写字母、数字和特殊字符 |
### API 与 Dashboard
| 功能 | 描述 |
|---------|-------------|
| **REST API** | FastAPI endpoint (`POST /generate`)，接收 profile JSON，返回下载 URL |
| **Web Dashboard** | 基于浏览器的 UI，带有实时的 WebSocket 进度日志 |
### 性能
| 功能 | 描述 |
|---------|-------------|
| **多进程** | 通过 `-t` / `--threads` 配置 worker 数量 |
| **GPU 加速** | 可选的基于 CuPy 的 GPU 规则应用（优雅地回退到 CPU） |
| **外部归并排序** | 针对超大规模字典，使用 k 路堆归并进行十亿级别的排序 |
### 模式
| 模式 | 标志 | 行为 |
|------|------|----------|
| **Normal** | *(默认)* | 所有标准变异 |
| **Lite** | `--lite` | 跳过双词组合、Markov、大型混合掩码和动态键盘步进 |
| **Extreme** | `--extreme` | 启用年份混合、Markov、动态键盘步进及所有繁重的变异 |
## 安装说明
### 从 PyPI 安装（推荐）
```
pip install pawpy
```
### 从源码安装
```
git clone https://github.com/Danyalkhattak/pawpy.git
cd pawpy
pip install -r requirements.txt
pip install -e .
```
### 可选依赖
```
# API 与 Dashboard
pip install fastapi uvicorn websockets
# GPU 加速 (需要 CUDA)
pip install cupy-cuda11x # or cupy-cuda12x depending on your CUDA version
# 密码强度评分
pip install zxcvbn
# 全部可选
pip install -e ".[all]"
```
## 快速开始
### 交互模式
```
pawpy
```
这将启动问卷。回答提示（留空也可以），Pawpy 会生成一个字典并保存到 `pawpy_wordlist.txt`。
### 从 JSON Profile 生成
```
pawpy -j profile.json -o wordlist.txt
```
### 多目标模式
```
pawpy --multi targets.json --extreme
```
### 使用 Hashcat 规则
```
pawpy -j profile.json --rules best64.rule
```
### 混合掩码攻击
```
pawpy -j profile.json --hybrid-right ?d?d?d
```
### 使用评分与策略过滤
```
pawpy -j profile.json --min-strength 2 --min-length 8 --require-upper --require-digit
```
### 更新常见密码
```
pawpy update-passwords
```
### 启动 API 服务器
```
pawpy api
# 服务器运行在 http://127.0.0.1:8000
```
### 启动 Dashboard
```
pawpy dashboard
# Dashboard 运行在 http://127.0.0.1:8080
```
## CLI 参考
```
usage: pawpy [-h] [-o FILE] [-j FILE] [--multi FILE] [--rules FILE]
[--template TMPL] [--hybrid-left MASK] [--hybrid-right MASK]
[--markov] [--markov-order N] [--markov-count N]
[--min-strength N] [--min-length N]
[--require-upper] [--require-lower] [--require-digit]
[--require-special] [--lite] [--extreme]
[--gpu] [-t N] [-v] [--verbose]
Options:
-o, --output FILE Output file (default: pawpy_wordlist.txt)
-j, --import-json FILE Import single profile from JSON
--multi FILE Import multiple profiles from JSON array
--rules FILE Load hashcat rule file
--template TEMPLATE Custom pattern template (repeatable)
--hybrid-left MASK Left mask for hybrid attack (?l?d)
--hybrid-right MASK Right mask for hybrid attack (?d?d?d)
--markov Enable Markov chain blending
--markov-order N Markov chain order (default: 2)
--markov-count N Number of Markov words (default: 5000)
--min-strength N Minimum zxcvbn score (0-4)
--min-length N Minimum password length
--require-upper Require uppercase letter
--require-lower Require lowercase letter
--require-digit Require digit
--require-special Require special character
--lite Fast mode (skip heavy combos)
--extreme Enable all heavy mutations
--gpu Use GPU acceleration if available
-t, --threads N Worker process count (default: CPU count)
-v, --version Show version
--verbose Enable debug logging
Sub-commands:
update-passwords Download latest common passwords from SecLists
api Start REST API server
dashboard Launch web dashboard
```
## Profile 格式
### 单个 Profile (JSON)
```
{
"firstname": "John",
"lastname": "Doe",
"nickname": "Johnny",
"birthdate": "01011990",
"partner": "Jane",
"partner_nick": "Janey",
"partner_bdate": "02021992",
"pet": "Rex",
"company": "Acme",
"hometown": "Metropolis",
"favourite_color": "blue",
"children": ["Alice", "Bob"],
"keywords": ["guitar", "hiking"]
}
```
### 多目标 Profile (JSON 数组)
```
[
{ "firstname": "John", "lastname": "Doe", "pet": "Rex" },
{ "firstname": "Jane", "lastname": "Doe", "pet": "Buddy" }
]
```
使用 `--multi` 时，Pawpy 会将所有 profile 合并为一个统一的交叉引用 profile。这意味着所有目标的基础词汇会被组合在一起，使变异引擎能够生成跨目标的组合（例如，将 John 的名字与 Jane 的宠物名配对）。
## 变异引擎
变异 pipeline 会按顺序通过多个阶段处理基础词汇：
```
Base Words
│
├── Leet Speak (3 levels)
├── Common Mangle Rules (capitalize, reverse, append/prepend)
├── Date Permutations (20+ variants per date)
├── Hashcat Rules (if --rules provided)
├── Custom Templates (if --template provided)
├── Keyboard Walks (static + optional dynamic)
├── Markov Blending (if --markov)
├── Year-Word Blends (if not --lite)
├── Two-Word Combinations (if not --lite)
├── Hybrid Masks (if --hybrid-left/right)
└── Top 10K Common Passwords
│
▼
Scoring & Policy Filtering
│
▼
Deduplication & Sort → Final Wordlist
```
### Leet Speak 级别
| 级别 | 替换 |
|-------|---------------|
| 1 (基础) | a→@, e→3, i→1, o→0, s→$, t→7 |
| 2 (扩展) | + i→!, s→5 |
| 3 (激进) | + a→4, l→1, b→8, g→9, h→# |
### Hashcat 规则支持
支持的规则命令：
| 规则 | 描述 | 示例 |
|------|-------------|--------|
| `l` | 全部小写 | `hello` → `hello` |
| `u` | 全部大写 | `hello` → `HELLO` |
| `c` | 首字母大写 | `hello` → `Hello` |
| `s` | 大小写互换 | `Hello` → `hELLO` |
| `r` | 反转 | `hello` → `olleh` |
| `d` | 复制整个单词 | `hi` → `hihi` |
| `p` | 复制首个字符 | `hi` → `hhi` |
| `z` | 复制末尾字符 | `hi` → `hii` |
| `$X` | 追加字符 X | `$!` → `pass!` |
| `^X` | 前置字符 X | `^1` → `1pass` |
| `[N` | 保留前 N 个字符 | `[3` → `pas` |
| `]N` | 保留后 N 个字符 | `]3` → `ssw` |
| `iNX` | 在位置 N 插入字符 X | `i2X` → `paXssword` |
| `oNX` | 用 X 覆盖位置 N 的字符 | `o0X` → `Xassword` |
| `'XY` | 将所有 X 替换为 Y | `'a@` → `p@ssword` |
### 模板 Token
| Token | 解析为 |
|-------|-------------|
| `[FirstName]` | 名字（原始、首字母大写、全大写、全小写） |
| `[LastName]` | 姓氏 |
| `[Nickname]` | 昵称 |
| `[Pet]` | 宠物名 |
| `[Company]` | 公司名 |
| `[Color]` / `[Favourite_Color]` | 最喜欢的颜色 |
| `[Partner]` | 伴侣的名字 |
| `[Child]` / `[Children]` | 孩子的名字 |
| `[Keyword]` / `[Keywords]` | 关键词 / 兴趣 |
| `[Year]` | 1986-当前年份 |
| `[Year2]` | 两位数年份 |
| `[Date]` | profile 中的生日 |
| `[Digit]` | 0–9 |
| `[Special]` | !@#$%^&*?._- |
| `[Upper]` | A–Z |
| `[Lower]` | a–z |
| `[Sep]` | 分隔符：_ - . @ # (空) |
| `[123]` | 123, 1234, 12345, !@#, 1q2w3e |
示例：对于 profile `firstname=John`，`[FirstName][Sep][Year]` 将生成：
`john_2024`, `john-2024`, `john.2024`, `John_2024`, `john@2024` 等。
## 评分与过滤
### zxcvbn 强度评分
当提供 `--min-strength N` 时（需要 `zxcvbn` 包），每个候选项都会在 0-4 的范围内进行评分：
| 分数 | 强度 | 描述 |
|-------|----------|-------------|
| 0 | 非常弱 | 极易被猜出（例如，`123456`） |
| 1 | 弱 | 很容易被猜出（例如，`password1`） |
| 2 | 一般 | 中等容易被猜出 |
| 3 | 强 | 不常见，但无法抵御针对性攻击 |
| 4 | 非常强 | 极强的抗破解能力 |
低于阈值的候选项将被修剪。这通过移除极其微弱的条目来减少字典的大小，同时保留真正强大的候选词。
### 策略过滤
组合策略标志以强制执行密码复杂性要求：
```
# 至少 8 个字符，一个大写字母，一个数字
pawpy -j profile.json --min-length 8 --require-upper --require-digit
# 复杂：10+ 个字符，大小写混合，数字，特殊字符
pawpy -j profile.json --min-length 10 --require-upper --require-lower \
--require-digit --require-special
```
## API 与 Dashboard
### REST API
启动 API 服务器：
```
pawpy api
```
Endpoints：
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| GET | `/` | 健康检查 |
| POST | `/generate` | 生成字典（multipart：profile JSON 文件 + 选项） |
| GET | `/download/{job_id}` | 下载生成的字典 |
| GET | `/jobs` | 列出所有生成任务 |
使用 `curl` 的示例：
```
curl -X POST http://127.0.0.1:8000/generate \
-F "profile=@target.json" \
-F "output=my_wordlist.txt" \
-F "extreme=true"
```
### Web Dashboard
```
pawpy dashboard
# 在浏览器中打开 http://127.0.0.1:8080
```
Dashboard 提供了一个深色主题的 Web 界面，你可以在其中：
- 上传 profile JSON 文件
- 选择生成模式（Normal / Lite / Extreme）
- 切换 Markov 混合和 zxcvbn 评分
- 通过 WebSocket 监控实时生成进度
- 下载生成的字典
## OSINT 插件
Pawpy 包含一个插件系统，可自动发现 `pawpy/profile/plugins/` 中的 Python 模块。每个插件必须定义一个 `collect(profile: dict) -> dict` 函数，用于使用 OSINT 派生的数据丰富 profile 字典。
### 创建插件
在 `pawpy/profile/plugins/` 中创建一个新的 `.py` 文件：
```
# pawpy/profile/plugins/my_plugin.py
from typing import Any, Dict
def collect(profile: Dict[str, Any]) -> Dict[str, Any]:
"""Enrich profile with OSINT data."""
# Your OSINT logic here
# e.g., look up public social media profiles,
# check for breached credentials (with consent), etc.
if profile.get("firstname"):
keywords = profile.get("keywords", [])
if isinstance(keywords, str):
keywords = [keywords]
# Add OSINT-discovered keywords
keywords.append("discovered_keyword")
profile["keywords"] = keywords
return profile
```
### 插件开发者的重要规则
- **遵守速率限制**以及任何外部 API 或网站的服务条款。
- **仅将 OSINT 数据用于授权的安全测试。**
- **遵循负责任的披露**实践。
- 优雅地处理异常，以免插件故障导致 pipeline 崩溃。
## 项目结构
```
pawpy/
├── pawpy/
│ ├── __init__.py # Package version and metadata
│ ├── __main__.py # python -m pawpy entry point
│ ├── cli.py # Full CLI with argparse
│ ├── config.py # PawpyConfig dataclass
│ ├── utils.py # Banner, logging, dedup, progress
│ ├── profile/
│ │ ├── __init__.py
│ │ ├── base.py # ProfileCollector (interactive + JSON)
│ │ ├── multi.py # Multi-target cross-referencing
│ │ └── plugins/
│ │ ├── __init__.py # Plugin discovery and loader
│ │ └── example.py # Example no-op plugin template
│ ├── mutations/
│ │ ├── __init__.py
│ │ ├── leet.py # Leet-speak (3 levels, combinatorial)
│ │ ├── dates.py # Date permutations (20+ variants)
│ │ ├── mangle.py # Common rules + hashcat rule engine
│ │ ├── markov.py # Markov chain training & generation
│ │ ├── keyboard.py # Static + dynamic keyboard walks
│ │ └── templates.py # Custom pattern template engine
│ ├── generator/
│ │ ├── __init__.py
│ │ ├── core.py # Main 15-stage pipeline orchestrator
│ │ ├── hybrid.py # Hybrid mask attacks (hashcat -a 6/7)
│ │ ├── sorter.py # Billion-scale external merge sort
│ │ └── gpu.py # Optional CuPy GPU acceleration
│ ├── scoring/
│ │ ├── __init__.py
│ │ └── scorer.py # zxcvbn-based strength pruning
│ ├── filters/
│ │ ├── __init__.py
│ │ └── policy.py # Password complexity policy filter
│ ├── api/
│ │ ├── __init__.py
│ │ ├── rest.py # FastAPI REST endpoints
│ │ └── dashboard.py # WebSocket web dashboard
│ └── data/
│ ├── __init__.py
│ ├── common_passwords.py # Embedded top 100 + SecLists loader
│ └── updater.py # Auto-update from SecLists
├── tests/
│ ├── __init__.py
│ ├── test_leet.py
│ ├── test_dates.py
│ ├── test_mangle.py
│ ├── test_markov.py
│ ├── test_keyboard.py
│ ├── test_templates.py
│ ├── test_profile.py
│ ├── test_hybrid.py
│ └── test_policy.py
├── .github/
│ └── workflows/
│ └── lint.yml # CI: flake8 + black + isort
├── requirements.txt
├── setup.py
└── README.md
```
## 开发指南
### 环境配置
```
git clone https://github.com/Danyalkhattak/pawpy.git
cd pawpy
pip install -e ".[all]"
pip install pytest
```
### 运行测试
```
pytest tests/ -v
```
### 代码质量
```
# Lint
flake8 pawpy/
# Format
black pawpy/
isort pawpy/
# 所有检查 (CI 也会运行)
flake8 pawpy/ && black --check pawpy/ && isort --check-only pawpy/
```
###添加新的变异
在 `pawpy/mutations/` 中创建一个新的 `.py` 文件，其中包含一个接收单词列表并返回变异候选项列表的函数：
```
# pawpy/mutations/my_mutation.py
def my_mutation(word: str) -> list[str]:
"""Apply custom mutation to a word."""
return [word + "_custom", word.upper() + "123"]
```
然后在 `pawpy/generator/core.py` 中的 `PipelineOrchestrator.run()` 方法内导入并调用它。
## 架构与数据流
```
User Input (CLI / JSON / API)
│
▼
┌─────────────────────┐
│ Profile Collection │ Interactive / JSON / OSINT Plugins
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Base Word Extract │ All text fields → lowercase, deduplicated
│ + Date Extraction │
└──────────┬──────────┘
│
▼
┌──────────────────────────────────────────┐
│ Mutation Pipeline │
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Leet │ │ Mangle │ │ Dates │ │
│ └──────────┘ └──────────┘ └───────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Keyboard │ │ Markov │ │ Templates │ │
│ └──────────┘ └──────────┘ └───────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Hybrid │ │ Rules │ │ Combos │ │
│ └──────────┘ └──────────┘ └───────────┘ │
└────────────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Scoring & Filtering │
│ zxcvbn strength │ Policy compliance │
└────────────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Sort + Deduplicate │
│ (in-memory or external merge sort) │
└────────────────────┬─────────────────────┘
│
▼
Final Wordlist File
```
## 性能说明
- **吞吐量**：在 8 核 CPU 上，系统目标为基础变异达到 ≥1000 万个密码/分钟。
- **内存**：默认保持在 2 GB RAM 以下。对于非常大的生成任务，外部归并排序器负责处理基于磁盘的处理。
- **输出**：顺序写入以实现最佳 I/O。排序好的块会进行高效的归并排序。
- **GPU**：用于规则应用的可选 CuPy 加速。如果未安装 CuPy，会优雅地回退到 CPU。
## 许可证
MIT 许可证。详情请参阅 [LICENSE](LICENSE)。
## 致谢
- [CUPP](https://github.com/Mebus/cupp) – 交互式 Profiling 的最初灵感
- [Hashcat](https://hashcat.net/wiki/doku.php?id=rule_based_attack) – 规则引擎格式
- [SecLists](https://github.com/danielmiessler/SecLists) – 常见密码数据源
- [zxcvbn](https://github.com/dropbox/zxcvbn) – 密码强度估算
- [Rich](https://github.com/Textualize/rich) – 精美的终端输出