{"id":21372675,"url":"https://github.com/jeremywildsmith/shadowhash-distributed","last_synced_at":"2026-05-11T02:49:04.855Z","repository":{"id":262957395,"uuid":"888357227","full_name":"JeremyWildsmith/shadowhash-distributed","owner":"JeremyWildsmith","description":"Elixir distributed Shadow File password cracker with GPU accelerated cracking for md5crypt hashing algorithm.","archived":false,"fork":false,"pushed_at":"2024-11-25T06:32:45.000Z","size":21218,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-16T08:44:48.963Z","etag":null,"topics":["cracking-hash","cracking-hashes","cracking-password","cuda","distributed-systems","elixir","erlang","hashing","nx","security"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JeremyWildsmith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-14T09:04:01.000Z","updated_at":"2024-11-25T06:35:15.000Z","dependencies_parsed_at":"2024-11-15T09:32:26.519Z","dependency_job_id":null,"html_url":"https://github.com/JeremyWildsmith/shadowhash-distributed","commit_stats":null,"previous_names":["jeremywildsmith/shadowhash-distributed"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JeremyWildsmith/shadowhash-distributed","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyWildsmith%2Fshadowhash-distributed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyWildsmith%2Fshadowhash-distributed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyWildsmith%2Fshadowhash-distributed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyWildsmith%2Fshadowhash-distributed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JeremyWildsmith","download_url":"https://codeload.github.com/JeremyWildsmith/shadowhash-distributed/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeremyWildsmith%2Fshadowhash-distributed/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32879551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cracking-hash","cracking-hashes","cracking-password","cuda","distributed-systems","elixir","erlang","hashing","nx","security"],"created_at":"2024-11-22T08:22:10.063Z","updated_at":"2026-05-11T02:49:04.830Z","avatar_url":"https://github.com/JeremyWildsmith.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ShadowHash\n\n## Introduction\n\nShadowHash is an Elixir application which implements distributed hash cracking against a linux [shadow file](https://man7.org/linux/man-pages/man5/shadow.5.html), as well as GPU Accelerated password cracking for select algorithms.\n\nThe project is largely an exercise in distributed programming in Elixir and programming using CUDA and NX, and less about creating a robust or competative password cracker.\n\n## Usage\n\nShadowHash can operate on a single node, or work distributively on multiple nodes / machines.\n\n### Installation and Configuration\n\n1. Ensure you have Erlang OTP installed and Elixir installed (version Elixir 1.17.3 on Erlang 27) Follow the official installation instrucitons [here](https://elixir-lang.org/install.html)\n2. Install and configure your environment for CUDA if you plan to use GPU Accelerated password hashers included in ShadowHash. \n    - These steps vary depending on your hardware configuration. For Nvidia you can follow the guide here: https://docs.nvidia.com/cuda/cuda-installation-guide-linux/\n3. Clone this repository onto your local machine\n4. That shadow_client project should be explicitly compiled to ensure it is properly configured to use GPU accelerated password cracking:\n   ```\n   \u003e cd ./apps/shadow_client/\n   \u003e export XLA_TARGET=cuda12\n   \u003e mix deps.get\n   \u003e mix deps.compile\n   ```\n   (depending on your environment, you may need to manually build XLA for GPU accelerated hashing.)\n\n5. Run the test-cases to ensure all is working as expected\n   ```\n   \u003e mix test --trace\n   ```\n\n6. For GPU-based hashing generation, ShadowHash relies on it's own Nx based hashing algorithm. For CPU-based hashing, ShadowHash relies on mkpasswd. It can be installed via your package manager:\n    ```\n    \u003e sudo apt install mkpasswd\n    \u003e mkpasswod --version\n    mkpasswd 5.5.22\n    ``` \n\n7. Optional, for generating benchmark plots (generated by using benchmark.sh script), you will need to have gnuplot installed, which can also be acquire via your package manager.\n    ```\n    \u003e sudo apt-get install gnuplot\n    \u003e gnuplot --version\n      gnuplot 6.0 patchlevel 0\n\n### Single / Multi Node\n\nUsing ShadowHash on a single node is straight-forward. Use the `--help` switch on the `shadow_cli` or `shadow_client` task to learn about the available options and usage instructions.\n\n#### Help (Shadow CLI)\n```\n\u003e  mix shadow_cli --help\nShadow hash CLI command interface.\nUsage is one of following forms:\n mix shadow_cli submit [\u003cshadow_path\u003e]\n mix shadow_cli status\n mix shadow_cli truncate-clients \u003cnum_clients\u003e\n\nSwitches valid for all verbs:\n --data-node    : Name of the data node where the scheduler, job and result bank are available\n --cookie       : Security cookie to use when connecting to the data-node.\n --interface    : IP Address to advertise to register with as a node (IP Datanode can address you by)\n --verbose      : Print verbose logging\n\nsubmit verb - submit a bruteforce job to job bank\n \u003cshadow_path\u003e : Optional path to the linux shadow file containing hashed user passwords.\n --password    : Specify a password in a valid form inline to process with/without specifying a shadow file\n --dictionary \u003cdictionary\u003e  : Supply a dictionary of passwords that are attempted initially\n --user \u003cuser\u003e : Supply a username, the passwords for which will be cracked.\n                  Otherwise, attempts to crack all passwords in the shadow file.\n --all-chars   : Will also bruteforce with non-printable characters\n --get-results : Wait for the results and print them out once ready\n\nstatus verb - Interrogate status of jobs / results\n --show-all     : Show all jobs (even suspended or inactive jobs.)\n\ntruncate-clients verb - Remove clients registered on the system\n \u003cnum_clients\u003e  : Maximum number of clients to keep connected to the system.\n```\n\n\n#### Help (Shadow Client)\n\n```\n\u003e  mix shadow_client --help\nShadow file password cracker client (job processing module.)\nUsage is: mix shadow_client\n --data-node     : Name of the data node where the scheduler, job and result bank are available\n --cookie        : Security cookie to use when connecting to the data-node.\n --interface     : IP Address to advertise to register with as a node (IP Datanode can address you by)\n --verbose       : Print verbose logging\n --gpu           : Supported for md5crypt, will execute the hash algorithm\n                   on the GPU. There is initial overhead to JIT compile to CUDA\n                   but after JIT compiling, significantly faster.\n --gpu-warmup    : Warm-up GPU bruteforce algorithm. Useful when capturing\n                   timing metrics and you don't want to include start-up overhead\n --workers \u003cnum\u003e : Number of workers to process bruteforce requests. Defaults\n                   to number of available CPU cores. Be mindful of the memory constraint\n```\n\n#### Example Running Password Cracking Cluster\n**ShadowHash is implemented as a MIX task.**\n\n1. Start the shadow_hash server\n   ```\n   \u003e cd ./apps/shadow_server\n   \u003e iex --name shadow_data@\u003chost address\u003e --cookie \u003csecret\u003e -S mix\n   ```\n\n2. Spawn one or more local or remote workers:\n    ```\n    \u003e cd ./apps/shadow_client\n    \u003e mix shadow_client --data-node shadow_data@\u003cserver address\u003e --interface \u003cmy address\u003e --cookie \u003csecret\u003e --workers 8\n    ```\n\n3. Submit a job using the submit command with shadow_cli\n   ```\n   \u003e cd ./apps/shadow_cli\n   \u003e mix shadow_cli submit ../../../data/sample_shadow --user user_yescrypt --data-node shadow_data@\u003cserver address\u003e --interface \u003cmy addres\u003e --get-results --cookie mysecret\n   ```\n\n4. Interrogate the status of the hashing cluster\n   ```\n   \u003e cd ./apps/shadow_cli\n   \u003e mix shadow_cli status --data-node shadow_data@\u003cserver address\u003e --interface \u003cmy addres\u003e --cookie mysecret\n   ```\n\n### Multi-Node\nIn a multi-node configuration, `shadow_hash` will distribute the password cracking work horizontally accross multiple machines and optionally multiple GPUs. Currently this feature is pending implementation.\n\n## Benchmarking\n\nFor generating benchmark metrics, please refer to the `benchmark.sh` shell script.\n\n\nBelow is a sample benchmark file produced by `benchmark.sh` which benchmarks the hashing performance 10, 4, 3, 2 and 1 distributed nodes each executing 12 password cracking threads\n![benchmark stats for 2 character password](/docs/nodes.png)\n\nBelow is a sample benchmark file produced by `benchmark.sh` which benchmarks the hashing performance accross all supported algorithms for different thread counts.\n![benchmark stats for 2 character password](/docs/threading.png)\n\n## Design\n\nShadowHash is implemented using agents to maximize scalability and stability. The below sequence diagrams show the general interaction between these agens to achieve the goal of performing a distributed password cracking.\n\n### Submitting a Job\nThe following sequence diagrams shows the interaction between agents when a job has been submitted and begins getting processed by a worker.\n![sequence diagram for submitting a job](/docs/sequence-submit_process-job.png)\n\n\n### Job Completion\nThe following sequence diagrams shows the interaction between agents when a job has been submitted successfully processed (password has been cracked.)\n![sequence diagram for submitting a job](/docs/sequence-complete.png)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremywildsmith%2Fshadowhash-distributed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeremywildsmith%2Fshadowhash-distributed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremywildsmith%2Fshadowhash-distributed/lists"}