# Phashcat
**Phashcat** is a tiny, immutable, monoid-style, fluent builder around the
[`hashcat`](https://hashcat.net/hashcat/) CLI. It lets you compose robust
commands in Python without remembering every flag, while keeping everything
type-checked and chainable.
- **Install**: `pip install Phashcat`
- **Repo**: https://github.com/avitwil/Phashcat
- **Author**: Avi Twil
> **Import once, from one place**
>
> ```python
> from Phashcat import hashcat, flags
> ```
---
## Who is it for?
- **Security engineers / pentesters** who automate cracking workflows, want
clean scripts, repeatability, and fewer copy–paste mistakes.
- **DevOps / SRE** building pipelines that run `hashcat` on CI/CD, with
predictable argument construction and clear diffs.
- **Researchers / educators** who demonstrate attack modes and need readable,
reproducible code snippets for classes, workshops, or papers.
- **Anyone** who dislikes hand-crafting long shell strings and prefers a
Pythonic, immutable, and composable API.
---
## When should you use Phashcat?
Use Phashcat when you:
- Want to **assemble `hashcat` commands programmatically** with validation.
- Need **immutable, composable configs** (e.g., presets you can merge).
- Prefer **Python lists** for `subprocess.run()` over a single shell string.
- Need a **single point of import** (`from Phashcat import ...`) for clarity
and maintainability across your project.
You probably **don’t** need Phashcat if you:
- Run `hashcat` only once by hand, or
- Prefer writing plain shell scripts without Python.
---
## Key Features
- **Monoid-style builder**: `.empty()`, `.mappend(other)` for composition.
- **Immutability**: every call returns a new builder — easier to reason about.
- **Fluent API**: `.hash_type(0).attack_mode(3).outfile("...").status(True)`.
- **Light validation**: sanity checks via `flags.VALUE_KIND`.
- **Single import surface**: `from Phashcat import hashcat, flags`.
---
## Quick Start
```python
from Phashcat import hashcat
cmd = (
hashcat("example0.hash", "?d?d?d?d?d?d")
.hash_type(0) # -m 0 (MD5)
.attack_mode(3) # -a 3 (brute-force / mask)
.outfile("cracked.txt")
.status(True).status_timer(2)
.workload_profile(3)
.value()
)
# import subprocess; subprocess.run(cmd, check=True)
````
---
## Common Use Cases
### 1) Straight wordlist (`-a 0`)
```python
from Phashcat import hashcat
cmd = (
hashcat("example0.hash", "example.dict")
.hash_type(0)
.attack_mode(0)
.outfile("out.txt")
.status(True)
.value()
)
```
### 2) Wordlist + rules
```python
cmd = (
hashcat("example0.hash", "example.dict")
.hash_type(0).attack_mode(0)
.rules_file("rules/best64.rule")
.outfile("out_rules.txt")
.value()
)
```
### 3) Brute-force mask (`-a 3`) with increment
```python
cmd = (
hashcat("example0.hash", "?1?1?1?1?1?1")
.hash_type(0).attack_mode(3)
.cs1("?l?d") # define ?1
.increment(True).increment_min(4).increment_max(6)
.outfile("out_inc.txt")
.value()
)
```
### 4) Hybrid wordlist + mask (`-a 6`)
```python
cmd = (
hashcat("example0.hash", "example.dict", "?d?d")
.hash_type(0).attack_mode(6)
.outfile("out_hybrid6.txt")
.value()
)
```
### 5) Show / Left (potfile reconciliation)
```python
show_cmd = hashcat("hashes.txt").show(True).value() # --show
left_cmd = hashcat("hashes.txt").left(True).value() # --left
```
---
## Presets & Composition (Monoid)
Create reusable presets and merge with `.mappend(...)`:
```python
preset_md5 = hashcat().hash_type(0)
preset_mask = hashcat().attack_mode(3).workload_profile(3)
cmd = (
preset_md5
.mappend(preset_mask)
.outfile("out.txt")
.arg("example0.hash", "?a?a?a?a?a?a")
.status(True)
.value()
)
```
---
## Reference Tables (via `flags`)
```python
from Phashcat import flags
print(flags.ATTACK_MODES) # {0: 'Straight', 1: 'Combination', ...}
print(flags.WORKLOAD_PROFILES) # {1: {...}, 2: {...}, ...}
print(flags.OUTFILE_FORMATS) # {1: 'hash[:salt]', ...}
```
---
## Ethics & Legality
Use `hashcat` **only** on hashes you are authorized to test. Comply with
local laws, organizational policies, and responsible disclosure guidelines.
---
## Contributing
PRs welcome! Please:
1. Keep imports top-level (`from Phashcat import ...`).
2. Add tests or runnable examples where possible.
3. Update `MANUAL.md` for public API changes.
---
## License
MIT — see `LICENSE`.
**Author: Avi Twil**
Raw data
{
"_id": null,
"home_page": null,
"name": "Phashcat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "hashcat, cli, wrapper, security, pentest, builder, monoid",
"author": "Avi Twil",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/55/d5/dc9229b7827002bdad72e932ea45443aa618638df2327d266ba013187b58/phashcat-0.1.1.tar.gz",
"platform": null,
"description": "\r\n# Phashcat\r\n\r\n**Phashcat** is a tiny, immutable, monoid-style, fluent builder around the\r\n[`hashcat`](https://hashcat.net/hashcat/) CLI. It lets you compose robust\r\ncommands in Python without remembering every flag, while keeping everything\r\ntype-checked and chainable.\r\n\r\n- **Install**: `pip install Phashcat`\r\n- **Repo**: https://github.com/avitwil/Phashcat\r\n- **Author**: Avi Twil\r\n\r\n> **Import once, from one place**\r\n>\r\n> ```python\r\n> from Phashcat import hashcat, flags\r\n> ```\r\n\r\n---\r\n\r\n## Who is it for?\r\n\r\n- **Security engineers / pentesters** who automate cracking workflows, want\r\n clean scripts, repeatability, and fewer copy\u2013paste mistakes.\r\n- **DevOps / SRE** building pipelines that run `hashcat` on CI/CD, with\r\n predictable argument construction and clear diffs.\r\n- **Researchers / educators** who demonstrate attack modes and need readable,\r\n reproducible code snippets for classes, workshops, or papers.\r\n- **Anyone** who dislikes hand-crafting long shell strings and prefers a\r\n Pythonic, immutable, and composable API.\r\n\r\n---\r\n\r\n## When should you use Phashcat?\r\n\r\nUse Phashcat when you:\r\n\r\n- Want to **assemble `hashcat` commands programmatically** with validation.\r\n- Need **immutable, composable configs** (e.g., presets you can merge).\r\n- Prefer **Python lists** for `subprocess.run()` over a single shell string.\r\n- Need a **single point of import** (`from Phashcat import ...`) for clarity\r\n and maintainability across your project.\r\n\r\nYou probably **don\u2019t** need Phashcat if you:\r\n- Run `hashcat` only once by hand, or\r\n- Prefer writing plain shell scripts without Python.\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n- **Monoid-style builder**: `.empty()`, `.mappend(other)` for composition.\r\n- **Immutability**: every call returns a new builder \u2014 easier to reason about.\r\n- **Fluent API**: `.hash_type(0).attack_mode(3).outfile(\"...\").status(True)`.\r\n- **Light validation**: sanity checks via `flags.VALUE_KIND`.\r\n- **Single import surface**: `from Phashcat import hashcat, flags`.\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```python\r\nfrom Phashcat import hashcat\r\n\r\ncmd = (\r\n hashcat(\"example0.hash\", \"?d?d?d?d?d?d\")\r\n .hash_type(0) # -m 0 (MD5)\r\n .attack_mode(3) # -a 3 (brute-force / mask)\r\n .outfile(\"cracked.txt\")\r\n .status(True).status_timer(2)\r\n .workload_profile(3)\r\n .value()\r\n)\r\n\r\n# import subprocess; subprocess.run(cmd, check=True)\r\n````\r\n\r\n---\r\n\r\n## Common Use Cases\r\n\r\n### 1) Straight wordlist (`-a 0`)\r\n\r\n```python\r\nfrom Phashcat import hashcat\r\n\r\ncmd = (\r\n hashcat(\"example0.hash\", \"example.dict\")\r\n .hash_type(0)\r\n .attack_mode(0)\r\n .outfile(\"out.txt\")\r\n .status(True)\r\n .value()\r\n)\r\n```\r\n\r\n### 2) Wordlist + rules\r\n\r\n```python\r\ncmd = (\r\n hashcat(\"example0.hash\", \"example.dict\")\r\n .hash_type(0).attack_mode(0)\r\n .rules_file(\"rules/best64.rule\")\r\n .outfile(\"out_rules.txt\")\r\n .value()\r\n)\r\n```\r\n\r\n### 3) Brute-force mask (`-a 3`) with increment\r\n\r\n```python\r\ncmd = (\r\n hashcat(\"example0.hash\", \"?1?1?1?1?1?1\")\r\n .hash_type(0).attack_mode(3)\r\n .cs1(\"?l?d\") # define ?1\r\n .increment(True).increment_min(4).increment_max(6)\r\n .outfile(\"out_inc.txt\")\r\n .value()\r\n)\r\n```\r\n\r\n### 4) Hybrid wordlist + mask (`-a 6`)\r\n\r\n```python\r\ncmd = (\r\n hashcat(\"example0.hash\", \"example.dict\", \"?d?d\")\r\n .hash_type(0).attack_mode(6)\r\n .outfile(\"out_hybrid6.txt\")\r\n .value()\r\n)\r\n```\r\n\r\n### 5) Show / Left (potfile reconciliation)\r\n\r\n```python\r\nshow_cmd = hashcat(\"hashes.txt\").show(True).value() # --show\r\nleft_cmd = hashcat(\"hashes.txt\").left(True).value() # --left\r\n```\r\n\r\n---\r\n\r\n## Presets & Composition (Monoid)\r\n\r\nCreate reusable presets and merge with `.mappend(...)`:\r\n\r\n```python\r\npreset_md5 = hashcat().hash_type(0)\r\npreset_mask = hashcat().attack_mode(3).workload_profile(3)\r\n\r\ncmd = (\r\n preset_md5\r\n .mappend(preset_mask)\r\n .outfile(\"out.txt\")\r\n .arg(\"example0.hash\", \"?a?a?a?a?a?a\")\r\n .status(True)\r\n .value()\r\n)\r\n```\r\n\r\n---\r\n\r\n## Reference Tables (via `flags`)\r\n\r\n```python\r\nfrom Phashcat import flags\r\n\r\nprint(flags.ATTACK_MODES) # {0: 'Straight', 1: 'Combination', ...}\r\nprint(flags.WORKLOAD_PROFILES) # {1: {...}, 2: {...}, ...}\r\nprint(flags.OUTFILE_FORMATS) # {1: 'hash[:salt]', ...}\r\n```\r\n\r\n---\r\n\r\n## Ethics & Legality\r\n\r\nUse `hashcat` **only** on hashes you are authorized to test. Comply with\r\nlocal laws, organizational policies, and responsible disclosure guidelines.\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nPRs welcome! Please:\r\n\r\n1. Keep imports top-level (`from Phashcat import ...`).\r\n2. Add tests or runnable examples where possible.\r\n3. Update `MANUAL.md` for public API changes.\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT \u2014 see `LICENSE`.\r\n\r\n**Author: Avi Twil**\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pythonic monoid-style builder around hashcat CLI with bundled binary.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/avitwil/Phashcat",
"Issues": "https://github.com/avitwil/Phashcat/issues"
},
"split_keywords": [
"hashcat",
" cli",
" wrapper",
" security",
" pentest",
" builder",
" monoid"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2524252f7afe7d8fb3997b44a925814abb194d8adc4dfb860ea4ce2ed9bb9fd5",
"md5": "0deff1d85533367acf9e6d9d3c47565a",
"sha256": "bca8ba89a2f5f5c5d7930f857d982c3f1e9fec650af2dd58b1fd016b0a983ea6"
},
"downloads": -1,
"filename": "phashcat-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0deff1d85533367acf9e6d9d3c47565a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 789030,
"upload_time": "2025-09-05T02:44:10",
"upload_time_iso_8601": "2025-09-05T02:44:10.616271Z",
"url": "https://files.pythonhosted.org/packages/25/24/252f7afe7d8fb3997b44a925814abb194d8adc4dfb860ea4ce2ed9bb9fd5/phashcat-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "55d5dc9229b7827002bdad72e932ea45443aa618638df2327d266ba013187b58",
"md5": "af21abde54014de4dc90f2f4a28bd85e",
"sha256": "7634604e4bd10299ea74adad40e55a121cfdbb189a5a6e402c499ae415bc88a9"
},
"downloads": -1,
"filename": "phashcat-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "af21abde54014de4dc90f2f4a28bd85e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 793758,
"upload_time": "2025-09-05T02:44:12",
"upload_time_iso_8601": "2025-09-05T02:44:12.113297Z",
"url": "https://files.pythonhosted.org/packages/55/d5/dc9229b7827002bdad72e932ea45443aa618638df2327d266ba013187b58/phashcat-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 02:44:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avitwil",
"github_project": "Phashcat",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "phashcat"
}
JSON
