From efdfacdb55dad29068dc3fc60ad8d2f00ee37c3e Mon Sep 17 00:00:00 2001 From: CarterPerez-dev Date: Sun, 22 Mar 2026 10:46:14 -0400 Subject: [PATCH] feat: install.sh, Justfile, and README for zero-friction setup install.sh detects package manager and installs all dependencies. Justfile provides build, test, run, and clean commands. README follows repo convention with ASCII banner and badges. --- PROJECTS/beginner/hash-cracker/Justfile | 29 ++++++++++ PROJECTS/beginner/hash-cracker/README.md | 65 +++++++++++++++++++++++ PROJECTS/beginner/hash-cracker/install.sh | 60 +++++++++++++++++++++ 3 files changed, 154 insertions(+) create mode 100644 PROJECTS/beginner/hash-cracker/Justfile create mode 100644 PROJECTS/beginner/hash-cracker/README.md create mode 100755 PROJECTS/beginner/hash-cracker/install.sh diff --git a/PROJECTS/beginner/hash-cracker/Justfile b/PROJECTS/beginner/hash-cracker/Justfile new file mode 100644 index 00000000..b6370e38 --- /dev/null +++ b/PROJECTS/beginner/hash-cracker/Justfile @@ -0,0 +1,29 @@ +# ©AngelaMos | 2026 +# Justfile + +set shell := ["bash", "-uc"] + +default: + @just --list --unsorted + +build: + cmake --preset debug + cmake --build build/debug + +release: + cmake --preset release + cmake --build build/release + +run *ARGS: + ./build/release/hashcracker {{ARGS}} + +run-debug *ARGS: + ./build/debug/hashcracker {{ARGS}} + +test: + cmake --preset debug + cmake --build build/debug + ctest --test-dir build/debug --output-on-failure + +clean: + rm -rf build/ diff --git a/PROJECTS/beginner/hash-cracker/README.md b/PROJECTS/beginner/hash-cracker/README.md new file mode 100644 index 00000000..db9cc1ae --- /dev/null +++ b/PROJECTS/beginner/hash-cracker/README.md @@ -0,0 +1,65 @@ +```ruby +██╗ ██╗ █████╗ ███████╗██╗ ██╗ ██████╗██████╗ █████╗ ██████╗██╗ ██╗███████╗██████╗ +██║ ██║██╔══██╗██╔════╝██║ ██║██╔════╝██╔══██╗██╔══██╗██╔════╝██║ ██╔╝██╔════╝██╔══██╗ +███████║███████║███████╗███████║██║ ██████╔╝███████║██║ █████╔╝ █████╗ ██████╔╝ +██╔══██║██╔══██║╚════██║██╔══██║██║ ██╔══██╗██╔══██║██║ ██╔═██╗ ██╔══╝ ██╔══██╗ +██║ ██║██║ ██║███████║██║ ██║╚██████╗██║ ██║██║ ██║╚██████╗██║ ██╗███████╗██║ ██║ +╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ +``` + +[![Cybersecurity Projects](https://img.shields.io/badge/Cybersecurity--Projects-Project%20%238-red?style=flat&logo=github)](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/beginner/hash-cracker) +[![C++](https://img.shields.io/badge/C%2B%2B23-00599C?style=flat&logo=cplusplus&logoColor=white)](https://isocpp.org) +[![License: AGPLv3](https://img.shields.io/badge/License-AGPL_v3-purple.svg)](https://www.gnu.org/licenses/agpl-3.0) + +> Multi-threaded hash cracking tool with dictionary, brute-force, and rule-based mutation attacks. + +*This is a quick overview — security theory, architecture, and full walkthroughs are in the [learn modules](#learn).* + +## What It Does + +- Crack MD5, SHA1, SHA256, and SHA512 hashes with auto-detection from hash length +- Dictionary attacks using memory-mapped wordlists for zero-copy large file handling +- Brute-force attacks with configurable character sets and keyspace partitioning +- Rule-based mutations (capitalize, leet speak, digit append, reverse, toggle case) +- Multi-threaded with zero-contention work partitioning across all CPU cores +- Salt support with prepend/append positioning +- Rich terminal progress display with speed, ETA, and progress bar + +## Quick Start + +```bash +./install.sh +hashcracker --hash --wordlist /path/to/rockyou.txt +``` + +> [!TIP] +> This project uses [`just`](https://github.com/casey/just) as a command runner. Type `just` to see all available commands. +> +> Install: `curl -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin` + +## Commands + +| Command | Description | +|---------|-------------| +| `hashcracker --hash --wordlist ` | Dictionary attack against a hash | +| `hashcracker --hash --bruteforce --charset lower,digits` | Brute-force with character set | +| `hashcracker --hash --wordlist --rules` | Dictionary + mutation rules | +| `hashcracker --hash --wordlist --salt ` | Crack salted hash | +| `hashcracker --help` | Show all options | + +## Learn + +This project includes step-by-step learning materials covering security theory, architecture, and implementation. + +| Module | Topic | +|--------|-------| +| [00 - Overview](learn/00-OVERVIEW.md) | Prerequisites and quick start | +| [01 - Concepts](learn/01-CONCEPTS.md) | Security theory and real-world breaches | +| [02 - Architecture](learn/02-ARCHITECTURE.md) | System design and data flow | +| [03 - Implementation](learn/03-IMPLEMENTATION.md) | Code walkthrough | +| [04 - Challenges](learn/04-CHALLENGES.md) | Extension ideas and exercises | + + +## License + +AGPL 3.0 diff --git a/PROJECTS/beginner/hash-cracker/install.sh b/PROJECTS/beginner/hash-cracker/install.sh new file mode 100755 index 00000000..3e833c6d --- /dev/null +++ b/PROJECTS/beginner/hash-cracker/install.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +# ©AngelaMos | 2026 +# install.sh + +set -euo pipefail + +GREEN='\033[32m' +CYAN='\033[36m' +RED='\033[31m' +BOLD='\033[1m' +RESET='\033[0m' + +info() { echo -e "${CYAN}[*]${RESET} $1"; } +success() { echo -e "${GREEN}[✔]${RESET} $1"; } +fail() { echo -e "${RED}[✖]${RESET} $1"; exit 1; } + +install_deps() { + if command -v apt-get &>/dev/null; then + info "Detected apt (Debian/Ubuntu)" + sudo apt-get update -qq + sudo apt-get install -y -qq g++ cmake ninja-build libssl-dev libboost-program-options-dev + elif command -v dnf &>/dev/null; then + info "Detected dnf (Fedora/RHEL)" + sudo dnf install -y gcc-c++ cmake ninja-build openssl-devel boost-program-options + elif command -v pacman &>/dev/null; then + info "Detected pacman (Arch)" + sudo pacman -S --needed --noconfirm gcc cmake ninja openssl boost + elif command -v brew &>/dev/null; then + info "Detected brew (macOS)" + brew install cmake ninja openssl boost + else + fail "Unsupported package manager. Install manually: g++, cmake, ninja, libssl-dev, libboost-program-options-dev" + fi +} + +build_project() { + info "Configuring release build..." + cmake --preset release + + info "Building..." + cmake --build build/release +} + +info "Installing dependencies..." +install_deps + +info "Building hashcracker..." +build_project + +echo "" +success "hashcracker built successfully!" +echo "" +echo -e "${BOLD}Usage:${RESET}" +echo " ./build/release/hashcracker --hash --wordlist " +echo " ./build/release/hashcracker --hash --bruteforce --charset lower,digits" +echo " ./build/release/hashcracker --hash --wordlist --rules" +echo "" +echo -e "${BOLD}Or use just:${RESET}" +echo " just run -- --hash --wordlist " +echo ""