Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jeremywildsmith/shadowhash-distributed

Elixir distributed Shadow File password cracker with GPU accelerated cracking for md5crypt hashing algorithm.
https://github.com/jeremywildsmith/shadowhash-distributed

cracking-hash cracking-hashes cracking-password cuda distributed-systems elixir erlang hashing nx security

Last synced: 24 days ago
JSON representation

Elixir distributed Shadow File password cracker with GPU accelerated cracking for md5crypt hashing algorithm.

Awesome Lists containing this project

README 

          
# ShadowHash



## Introduction



ShadowHash 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.



The 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.



## Usage



ShadowHash can operate on a single node, or work distributively on multiple nodes / machines.



### Installation and Configuration



1. 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)

2. Install and configure your environment for CUDA if you plan to use GPU Accelerated password hashers included in ShadowHash. 

    - 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/

3. Clone this repository onto your local machine

4. That shadow_client project should be explicitly compiled to ensure it is properly configured to use GPU accelerated password cracking:

   ```

   > cd ./apps/shadow_client/

   > export XLA_TARGET=cuda12

   > mix deps.get

   > mix deps.compile

   ```

   (depending on your environment, you may need to manually build XLA for GPU accelerated hashing.)



5. Run the test-cases to ensure all is working as expected

   ```

   > mix test --trace

   ```



6. 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:

    ```

    > sudo apt install mkpasswd

    > mkpasswod --version

    mkpasswd 5.5.22

    ``` 



7. 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.

    ```

    > sudo apt-get install gnuplot

    > gnuplot --version

      gnuplot 6.0 patchlevel 0



### Single / Multi Node



Using 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.



#### Help (Shadow CLI)

```

>  mix shadow_cli --help

Shadow hash CLI command interface.

Usage is one of following forms:

 mix shadow_cli submit []

 mix shadow_cli status

 mix shadow_cli truncate-clients 



Switches valid for all verbs:

 --data-node    : Name of the data node where the scheduler, job and result bank are available

 --cookie       : Security cookie to use when connecting to the data-node.

 --interface    : IP Address to advertise to register with as a node (IP Datanode can address you by)

 --verbose      : Print verbose logging



submit verb - submit a bruteforce job to job bank

  : Optional path to the linux shadow file containing hashed user passwords.

 --password    : Specify a password in a valid form inline to process with/without specifying a shadow file

 --dictionary   : Supply a dictionary of passwords that are attempted initially

 --user  : Supply a username, the passwords for which will be cracked.

                  Otherwise, attempts to crack all passwords in the shadow file.

 --all-chars   : Will also bruteforce with non-printable characters

 --get-results : Wait for the results and print them out once ready



status verb - Interrogate status of jobs / results

 --show-all     : Show all jobs (even suspended or inactive jobs.)



truncate-clients verb - Remove clients registered on the system

   : Maximum number of clients to keep connected to the system.

```



#### Help (Shadow Client)



```

>  mix shadow_client --help

Shadow file password cracker client (job processing module.)

Usage is: mix shadow_client

 --data-node     : Name of the data node where the scheduler, job and result bank are available

 --cookie        : Security cookie to use when connecting to the data-node.

 --interface     : IP Address to advertise to register with as a node (IP Datanode can address you by)

 --verbose       : Print verbose logging

 --gpu           : Supported for md5crypt, will execute the hash algorithm

                   on the GPU. There is initial overhead to JIT compile to CUDA

                   but after JIT compiling, significantly faster.

 --gpu-warmup    : Warm-up GPU bruteforce algorithm. Useful when capturing

                   timing metrics and you don't want to include start-up overhead

 --workers  : Number of workers to process bruteforce requests. Defaults

                   to number of available CPU cores. Be mindful of the memory constraint

```



#### Example Running Password Cracking Cluster

**ShadowHash is implemented as a MIX task.**



1. Start the shadow_hash server

   ```

   > cd ./apps/shadow_server

   > iex --name shadow_data@ --cookie  -S mix

   ```



2. Spawn one or more local or remote workers:

    ```

    > cd ./apps/shadow_client

    > mix shadow_client --data-node shadow_data@ --interface  --cookie  --workers 8

    ```



3. Submit a job using the submit command with shadow_cli

   ```

   > cd ./apps/shadow_cli

   > mix shadow_cli submit ../../../data/sample_shadow --user user_yescrypt --data-node shadow_data@ --interface  --get-results --cookie mysecret

   ```



4. Interrogate the status of the hashing cluster

   ```

   > cd ./apps/shadow_cli

   > mix shadow_cli status --data-node shadow_data@ --interface  --cookie mysecret

   ```



### Multi-Node

In 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.



## Benchmarking



For generating benchmark metrics, please refer to the `benchmark.sh` shell script.



Below 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

![benchmark stats for 2 character password](/docs/nodes.png)



Below is a sample benchmark file produced by `benchmark.sh` which benchmarks the hashing performance accross all supported algorithms for different thread counts.

![benchmark stats for 2 character password](/docs/threading.png)



## Design



ShadowHash 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.



### Submitting a Job

The following sequence diagrams shows the interaction between agents when a job has been submitted and begins getting processed by a worker.

![sequence diagram for submitting a job](/docs/sequence-submit_process-job.png)



### Job Completion

The following sequence diagrams shows the interaction between agents when a job has been submitted successfully processed (password has been cracked.)

![sequence diagram for submitting a job](/docs/sequence-complete.png)