Skip to content

Building 70 Projects ranging from beginner to advanced so anyone can β€” learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company πŸ‘‡

feat: install.sh, Justfile, and README for zero-friction setup

CarterPerez-devefdfacdb55da
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 <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 <h> --wordlist <path>` | Dictionary attack against a hash |
+| `hashcracker --hash <h> --bruteforce --charset lower,digits` | Brute-force with character set |
+| `hashcracker --hash <h> --wordlist <path> --rules` | Dictionary + mutation rules |
+| `hashcracker --hash <h> --wordlist <path> --salt <s>` | 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 <hash> --wordlist <path>"
+echo " ./build/release/hashcracker --hash <hash> --bruteforce --charset lower,digits"
+echo " ./build/release/hashcracker --hash <hash> --wordlist <path> --rules"
+echo ""
+echo -e "${BOLD}Or use just:${RESET}"
+echo " just run -- --hash <hash> --wordlist <path>"
+echo ""