From b850ad0b49652e627d8774437acab5d804ac9657 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 29 Jun 2026 14:15:58 +0100 Subject: [PATCH] revert(readme): restore canonical README.adoc; remove runaway .md conversion The estate-wide 'convert README.adoc -> Markdown' pass over-applied the narrow boj-server/hyperpolymath .md rule to every repo. AsciiDoc is canonical here; restore README.adoc and remove README.md (clean revert). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md => README.adoc | 368 ++++++++++++++++++--------------------- 1 file changed, 168 insertions(+), 200 deletions(-) rename README.md => README.adoc (52%) diff --git a/README.md b/README.adoc similarity index 52% rename from README.md rename to README.adoc index 606a4bb..4a76d9c 100644 --- a/README.md +++ b/README.adoc @@ -1,110 +1,79 @@ - +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell += πŸ” dicti0nary-attack +image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/dicti0nary-attack"] -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0--1.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) -\> A comprehensive security research utility for testing non-dictionary -passwords +image:https://img.shields.io/badge/License-MPL_2.0--1.0-blue.svg[License: MPL-2.0,link="https://github.com/hyperpolymath/palimpsest-license"] -Everyone knows that it’s easy to crack a password if it appears in a -dictionary. *dicti0nary-attack* is a humorous inversion of that -concept - it’s a powerful tool for generating and testing passwords that -are NOT in traditional dictionaries, focusing on the creative variations -users think make their passwords "secure." +> A comprehensive security research utility for testing non-dictionary passwords -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0--1.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) -link:[\![Chapel](https://img.shields.io/badge/Chapel-2.3+-purple.svg)\]() -[\![Rust](https://img.shields.io/badge/Rust-2021-orange.svg)\]() -link:[\![ReScript](https://img.shields.io/badge/ReScript-11+-red.svg)\]() -[\![RSR -Compliance](https://img.shields.io/badge/RSR-Bronze%20(86%25)-yellow.svg)\](RSR_COMPLIANCE.md) -[\![Offline-First](https://img.shields.io/badge/offline--first-100%25-green.svg)\](RSR_COMPLIANCE.md#5-offline-first—​compliant) +Everyone knows that it's easy to crack a password if it appears in a dictionary. _dicti0nary-attack_ is a humorous inversion of that concept - it's a powerful tool for generating and testing passwords that are NOT in traditional dictionaries, focusing on the creative variations users think make their passwords "secure." -# ⚠️ Legal Notice +image:https://img.shields.io/badge/License-MPL_2.0--1.0-blue.svg[License: MPL-2.0,link="https://github.com/hyperpolymath/palimpsest-license"] +link:https://img.shields.io/badge/Chapel-2.3+-purple.svg[![Chapel]](https://chapel-lang.org/) +link:https://img.shields.io/badge/Rust-2021-orange.svg[![Rust]](https://www.rust-lang.org/) +link:https://img.shields.io/badge/ReScript-11+-red.svg[![ReScript]](https://rescript-lang.org/) +link:https://img.shields.io/badge/RSR-Bronze%20(86%25[![RSR Compliance]-yellow.svg)](RSR_COMPLIANCE.md) +link:https://img.shields.io/badge/offline--first-100%25-green.svg[![Offline-First]](RSR_COMPLIANCE.md#5-offline-first--compliant) -*This tool is for authorized security testing only.* +== ⚠️ Legal Notice -Authorized use includes: - βœ… Penetration testing with explicit written -permission - βœ… Security audits of systems you own - βœ… CTF (Capture The -Flag) competitions - βœ… Academic research and education - βœ… Password -strength analysis on your own data +_This tool is for authorized security testing only._ -Unauthorized access to computer systems is *illegal* and may result in -criminal prosecution under computer fraud and abuse laws. +Authorized use includes: +- βœ… Penetration testing with explicit written permission +- βœ… Security audits of systems you own +- βœ… CTF (Capture The Flag) competitions +- βœ… Academic research and education +- βœ… Password strength analysis on your own data -# ✨ Features +Unauthorized access to computer systems is _illegal_ and may result in criminal prosecution under computer fraud and abuse laws. -## Password Generators +== ✨ Features -- *Leetspeak Generator*: Transforms words using character substitutions - (aβ†’4, eβ†’3, oβ†’0, etc.) +=== Password Generators -- *Phonetic Generator*: Uses phonetic substitutions (forβ†’4, toβ†’2, youβ†’u) +- _Leetspeak Generator_: Transforms words using character substitutions (aβ†’4, eβ†’3, oβ†’0, etc.) +- _Phonetic Generator_: Uses phonetic substitutions (forβ†’4, toβ†’2, youβ†’u) +- _Pattern Generator_: Creates pattern-based passwords (keyboard walks, sequences, date patterns) +- _Random Generator_: Generates truly random non-dictionary passwords +- _Markov Chain Generator_: Statistical password generation based on training data -- *Pattern Generator*: Creates pattern-based passwords (keyboard walks, - sequences, date patterns) +=== Hash Cracking -- *Random Generator*: Generates truly random non-dictionary passwords +- _Multi-Algorithm Support_: MD5, SHA1, SHA224, SHA256, SHA384, SHA512, BLAKE2b, BLAKE2s +- _Parallel Processing_: Multi-core support for faster cracking +- _Batch Operations_: Crack multiple hashes simultaneously +- _Progress Tracking_: Real-time statistics and progress monitoring -- *Markov Chain Generator*: Statistical password generation based on - training data +=== Additional Features -## Hash Cracking +- 🎨 _Rich CLI Interface_: Beautiful terminal UI with progress bars and tables +- 🌐 _Web Interface_: Browser-based GUI for easy password generation and cracking +- πŸ“Š _Comprehensive Statistics_: Detailed performance metrics and reporting +- πŸ”§ _Flexible Configuration_: YAML/JSON configuration files +- πŸ“ _Multiple Output Formats_: Text, JSON, CSV, HTML reports +- 🐳 _Docker Support_: Containerized deployment +- πŸ§ͺ _Extensive Test Suite_: High code coverage with pytest +- ⚑ _Performance Benchmarks_: Built-in benchmarking tools +- πŸ† _RSR Framework Compliant_: Bronze level (86% compliance) +- πŸ“΄ _Offline-First_: Core functionality works without internet +- πŸ”’ _Security-First_: RFC 9116 compliant, comprehensive security policy -- *Multi-Algorithm Support*: MD5, SHA1, SHA224, SHA256, SHA384, SHA512, - BLAKE2b, BLAKE2s +== πŸ“¦ Installation -- *Parallel Processing*: Multi-core support for faster cracking +=== Prerequisites -- *Batch Operations*: Crack multiple hashes simultaneously +* **Chapel** 2.3+ - https://chapel-lang.org/download.html[Download Chapel] +* **Rust** 2021 edition - https://rustup.rs/[Install via rustup] +* **Deno** (for web dev) - https://deno.land/[Install Deno] +* **just** task runner - https://just.systems/[Install just] -- *Progress Tracking*: Real-time statistics and progress monitoring +=== From Source -## Additional Features - -- 🎨 *Rich CLI Interface*: Beautiful terminal UI with progress bars and - tables - -- 🌐 *Web Interface*: Browser-based GUI for easy password generation and - cracking - -- πŸ“Š *Comprehensive Statistics*: Detailed performance metrics and - reporting - -- πŸ”§ *Flexible Configuration*: YAML/JSON configuration files - -- πŸ“ *Multiple Output Formats*: Text, JSON, CSV, HTML reports - -- 🐳 *Docker Support*: Containerized deployment - -- πŸ§ͺ *Extensive Test Suite*: High code coverage with pytest - -- ⚑ *Performance Benchmarks*: Built-in benchmarking tools - -- πŸ† *RSR Framework Compliant*: Bronze level (86% compliance) - -- πŸ“΄ *Offline-First*: Core functionality works without internet - -- πŸ”’ *Security-First*: RFC 9116 compliant, comprehensive security policy - -# πŸ“¦ Installation - -## Prerequisites - -- **Chapel** 2.3+ - [Download - Chapel](https://chapel-lang.org/download.html) - -- **Rust** 2021 edition - [Install via rustup](https://rustup.rs/) - -- **Deno** (for web dev) - [Install Deno](https://deno.land/) - -- **just** task runner - [Install just](https://just.systems/) - -## From Source - -```bash +[source,bash] +---- git clone https://github.com/Hyperpolymath/dicti0nary-attack.git cd dicti0nary-attack @@ -116,11 +85,12 @@ just build # Build WASM for web interface just build-wasm -``` +---- -## Using Podman/Docker +=== Using Podman/Docker -```bash +[source,bash] +---- # Build with Podman (preferred) podman build -t dicti0nary-attack -f Containerfile . podman run --rm dicti0nary-attack just info @@ -128,23 +98,25 @@ podman run --rm dicti0nary-attack just info # Or with Docker docker build -t dicti0nary-attack . docker run --rm dicti0nary-attack just info -``` +---- -## Using Podman Compose +=== Using Podman Compose -```bash +[source,bash] +---- # Run CLI podman-compose run dicti0nary-cli just info # Run web interface (static server) podman-compose up dicti0nary-static -``` +---- -# πŸš€ Quick Start +== πŸš€ Quick Start -## Generate Passwords +=== Generate Passwords -```bash +[source,bash] +---- # Generate 1000 leetspeak passwords dicti0nary generate -g leetspeak -n 1000 @@ -153,11 +125,12 @@ dicti0nary generate -g pattern -n 5000 -o passwords.txt # Custom length constraints dicti0nary generate -g random -n 100 --min-length 12 --max-length 20 -``` +---- -## Crack Password Hashes +=== Crack Password Hashes -```bash +[source,bash] +---- # Crack a SHA256 hash using pattern generator dicti0nary crack 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8 -a sha256 -g pattern @@ -166,88 +139,89 @@ dicti0nary crack -a sha256 -g leetspeak -p --workers 8 # Use custom wordlist dicti0nary crack -a md5 -w wordlists/custom.txt -``` +---- -## Create Wordlists +=== Create Wordlists -```bash +[source,bash] +---- # Create leetspeak wordlist dicti0nary create-wordlist wordlists/leetspeak.txt -g leetspeak -n 50000 # Create phonetic wordlist dicti0nary create-wordlist wordlists/phonetic.txt -g phonetic -n 10000 -``` +---- -## Hash Passwords +=== Hash Passwords -```bash +[source,bash] +---- # Hash with SHA256 dicti0nary hash-password "mypassword" # Hash with MD5 dicti0nary hash-password "mypassword" -a md5 -``` +---- -## Run Web Interface +=== Run Web Interface -```bash +[source,bash] +---- # Serve static web interface just serve-static # Or with Deno deno task serve -``` - -Visit in your browser. - -# πŸ“š Documentation - -- [Usage Guide](docs/USAGE.md) - Comprehensive usage instructions - -- [API Documentation](docs/API.md) - Python API reference +---- -- [Plugin Guide](docs/PLUGINS.md) - Plugin development guide +Visit http://localhost:8080 in your browser. -- [Configuration Guide](config/README.md) - Configuration options +== πŸ“š Documentation -- [RSR Compliance](RSR_COMPLIANCE.md) - Standards compliance report +- link:docs/USAGE.md[Usage Guide] - Comprehensive usage instructions +- link:docs/API.md[API Documentation] - Python API reference +- link:docs/PLUGINS.md[Plugin Guide] - Plugin development guide +- link:config/README.md[Configuration Guide] - Configuration options +- link:RSR_COMPLIANCE.md[RSR Compliance] - Standards compliance report +- link:SECURITY.md[Security Policy] - Vulnerability reporting +- link:CONTRIBUTING.md[Contributing] - Contribution guidelines -- [Security Policy](SECURITY.md) - Vulnerability reporting +== 🎯 Use Cases -- [Contributing](CONTRIBUTING.md) - Contribution guidelines - -# 🎯 Use Cases - -## Security Audit +=== Security Audit Test if users are using common non-dictionary password patterns: -```bash +[source,bash] +---- dicti0nary create-wordlist audit.txt -g leetspeak -n 100000 dicti0nary crack -w audit.txt -a sha256 -``` +---- -## CTF Competition +=== CTF Competition Quickly test common patterns: -```bash +[source,bash] +---- dicti0nary crack -a md5 -g pattern -p -``` +---- -## Password Research +=== Password Research Generate datasets for password strength analysis: -```bash +[source,bash] +---- dicti0nary create-wordlist data/leetspeak.txt -g leetspeak -n 50000 dicti0nary create-wordlist data/phonetic.txt -g phonetic -n 50000 dicti0nary create-wordlist data/patterns.txt -g pattern -n 50000 -``` +---- -# πŸ—οΈ Architecture +== πŸ—οΈ Architecture -```text +[source,text] +---- dicti0nary-attack/ β”œβ”€β”€ src/ # Main source code β”‚ β”œβ”€β”€ main.rs # Rust CLI entry point @@ -286,13 +260,14 @@ dicti0nary-attack/ β”œβ”€β”€ Chapel.toml # Chapel config β”œβ”€β”€ rescript.json # ReScript config └── deno.json # Deno config -``` +---- -# πŸ”§ Configuration +== πŸ”§ Configuration Create a configuration file (`config.yaml`): -```yaml +[source,yaml] +---- generators: leetspeak: max_substitutions: 3 @@ -312,19 +287,21 @@ output: format: json directory: output save_stats: true -``` +---- Use with commands: -```bash +[source,bash] +---- dicti0nary --config config.yaml generate -g leetspeak -n 1000 -``` +---- -# πŸ§ͺ Testing +== πŸ§ͺ Testing Run the test suite: -```bash +[source,bash] +---- # Run Chapel tests just test @@ -336,51 +313,56 @@ cargo test # Watch mode (requires entr) just test-watch -``` +---- -# πŸ“Š Benchmarks +== πŸ“Š Benchmarks Run performance benchmarks: -```bash +[source,bash] +---- # Run Chapel benchmarks just bench # Run Rust benchmarks cargo bench -``` +---- -# 🐳 Container Usage +== 🐳 Container Usage -## Build Image (Podman preferred) +=== Build Image (Podman preferred) -```bash +[source,bash] +---- # Podman (preferred) podman build -t dicti0nary-attack -f Containerfile . # Docker docker build -t dicti0nary-attack . -``` +---- -## Run CLI +=== Run CLI -```bash +[source,bash] +---- podman run --rm dicti0nary-attack just info -``` +---- -## Run Web Interface +=== Run Web Interface -```bash +[source,bash] +---- podman-compose up dicti0nary-static -``` +---- -Access at +Access at http://localhost:8080 -# πŸ› οΈ Development +== πŸ› οΈ Development -## Setup Development Environment +=== Setup Development Environment -```bash +[source,bash] +---- # Clone repository git clone https://github.com/Hyperpolymath/dicti0nary-attack.git cd dicti0nary-attack @@ -396,11 +378,12 @@ deno task build:rescript # Watch mode for development deno task watch:rescript -``` +---- -## Available just Commands +=== Available just Commands -```bash +[source,bash] +---- just # List all commands just build # Compile Chapel sources just build-wasm # Compile to WASM @@ -417,60 +400,45 @@ just podman-build # Build container just validate-rsr # Check RSR compliance just nickel-eval # Evaluate Nickel config just stats # Show project statistics -``` +---- -# 🀝 Contributing +== 🀝 Contributing Contributions are welcome! Please ensure: -1. All tests pass: `just` `test` and `cargo` `test` - -2. Code is formatted: `just` `format` and `cargo` `fmt` - -3. No linting errors: `just` `lint` and `cargo` `clippy` +1. All tests pass: `just test` and `cargo test` +2. Code is formatted: `just format` and `cargo fmt` +3. No linting errors: `just lint` and `cargo clippy` +4. ReScript compiles: `deno task build:rescript` +5. Documentation is updated -4. ReScript compiles: `deno` `task` `build:rescript` +== πŸ“„ License -5. Documentation is updated +This project is licensed under the GNU General Public License v3.0 - see the link:LICENSE[LICENSE] file for details. -# πŸ“„ License - -This project is licensed under the GNU General Public License v3.0 - see -the [LICENSE](LICENSE) file for details. - -# πŸ™ Acknowledgments +== πŸ™ Acknowledgments - Inspired by the need for better password security testing tools - - Built with Chapel, Rust, ReScript, and Nickel - - Powered by WASM for offline-first browser execution - - Thanks to the security research community -# πŸ“ž Contact & Support +== πŸ“ž Contact & Support -- *Issues*: [GitHub - Issues](https://github.com/Hyperpolymath/dicti0nary-attack/issues) +- _Issues_: link:https://github.com/Hyperpolymath/dicti0nary-attack/issues[GitHub Issues] +- _Documentation_: link:docs/[docs/] +- _License_: GPL-3.0 -- *Documentation*: [docs/](docs/) +== πŸ”’ Security Notice -- *License*: GPL-3.0 - -# πŸ”’ Security Notice - -This tool is designed to help security professionals identify weak -passwords. It should never be used: +This tool is designed to help security professionals identify weak passwords. It should never be used: - To gain unauthorized access to any system - -- To crack passwords you don’t have permission to test - +- To crack passwords you don't have permission to test - For any illegal or unethical purposes -Always obtain explicit written permission before testing any system you -do not own. +Always obtain explicit written permission before testing any system you do not own. ------------------------------------------------------------------------- +--- -*Made with ❀️ for the security research community* +_Made with ❀️ for the security research community_