{"id":13844338,"url":"https://github.com/RUB-SysSec/Password-Guessing-Framework","last_synced_at":"2025-07-11T22:31:43.771Z","repository":{"id":85013049,"uuid":"41431590","full_name":"RUB-SysSec/Password-Guessing-Framework","owner":"RUB-SysSec","description":"A Framework for Comparing Password Guessing Strategies","archived":false,"fork":false,"pushed_at":"2019-07-11T17:44:23.000Z","size":1031,"stargazers_count":121,"open_issues_count":0,"forks_count":21,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-08-05T17:41:29.421Z","etag":null,"topics":["password-cracker","password-cracking","password-generator","password-guessers"],"latest_commit_sha":null,"homepage":"https://www.password-guessing.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RUB-SysSec.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}},"created_at":"2015-08-26T14:51:05.000Z","updated_at":"2024-05-07T22:55:03.000Z","dependencies_parsed_at":"2023-03-03T16:30:22.160Z","dependency_job_id":null,"html_url":"https://github.com/RUB-SysSec/Password-Guessing-Framework","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RUB-SysSec%2FPassword-Guessing-Framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RUB-SysSec%2FPassword-Guessing-Framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RUB-SysSec%2FPassword-Guessing-Framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RUB-SysSec%2FPassword-Guessing-Framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RUB-SysSec","download_url":"https://codeload.github.com/RUB-SysSec/Password-Guessing-Framework/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225763339,"owners_count":17520439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["password-cracker","password-cracking","password-generator","password-guessers"],"created_at":"2024-08-04T17:02:40.666Z","updated_at":"2024-11-21T16:31:12.473Z","avatar_url":"https://github.com/RUB-SysSec.png","language":"Python","funding_links":[],"categories":["Python (1887)","Python"],"sub_categories":[],"readme":"Password Guessing Framework\n===========================\n\nThe [Password Guessing Framework](https://password-guessing.org) is an open source tool to provide an automated and reliable way to compare password guessers. It can help to identify individual strengths and weaknesses of a guesser, its modes of operation or even the underlying guessing strategies. Therefor, it gathers information about how many passwords from an input file (password leak) have been cracked in relation to the amount of generated guesses. Subsequent to the guessing process an analysis of the cracked passwords is performed.  \n\nBy default the framework supports the following password guessers:\n\n* [John the Ripper in Markov mode (JtR) - Narayanan et al. - 2005](https://github.com/magnumripper/JohnTheRipper)\n* [Probabilistic Context Free Grammar (PCFG) - Matt Weir et al. - 2009](https://sites.google.com/site/reusablesec/Home/password-cracking-tools/probablistic_cracker)\n* [Ordered Markov Enumerator (OMEN) - Markus Dürmuth et al. - 2013](https://github.com/RUB-SysSec/OMEN)\n* [Probability Infinite Chained Elements (PRINCE) - Jens Steube - 2014](https://github.com/jsteube/princeprocessor)\n\nIn general though, any guesser that prints the password candidates via ```STDOUT``` can be used with the framework.  \nPlease note: The aforementioned password guessing / password cracking software is not part nor shipped with the framework and need to be installed separately.\n\nChangelog\n---------\nRefer to [docs/CHANGELOG.md](docs/CHANGELOG.md) for more information.  \nThis software is under active development.  \nMore information on this topic can be found on the project [website](https://password-guessing.org) (www.password-guessing.org).\n\n\nDependencies\n------------\n\nThe framework is written in Python 2.7 and thus requires it installed on the host system.  \nIn addition, the following modules have to be installed:  \n\n* [psutils](https://pypi.python.org/pypi/psutil): We highly recommend to use [pip](https://pypi.python.org/pypi/pip) to install version 3 of the module. ```apt-get``` will only install version 1.\n* [subprocess](https://docs.python.org/2/library/subprocess.html): This module is a mandatory requirement.\n\nWe have tested the framework on Ubuntu 14.04 where all the requirements are met by default.  \n\n\nInstallation\n------------\n\nOn the project [website](https://password-guessing.org) (www.password-guessing.org) you can find a more extensive installation tutorial, a beginners' guide, use case descriptions, guesser installation tutorials, dataset descriptions, experiments, and measurement data, very soon!  \n\nWe have created the directory ```/opt/pgf``` in which we installed an instance of all guessers we run with the framework (e.g., ```/opt/pgf/prince```).  \nThis way, our individual configurations of the guessers wouldn't collide with other guessing instances installed on the system!  \nImportant to note is that John the Ripper is used for the hash evaluation in cases where hashed input is provided.  \nIf you consider to run John the Ripper Markov mode as password guesser, you will need two instllations on your hard disk.  \nTherefor, install it in ```/opt/pgf/john-hash``` and ```/opt/pgf/john-guess```, respectively.  \nThe ```/opt/pgf/john-hash``` version, which is utilized as hash evaluator by the framework requires some additional care.  \n\nIMPORTANT NOTE: You have to change two parameters in the ```john.conf``` file in your ```/opt/pgf/john-hash``` directory:  \n\n* Currently, it is required to use the latest bleeding edge release of [John the Ripper (Jumbo Version)](https://github.com/magnumripper/JohnTheRipper)  \n* Change the config parameter ```StatusShowCandidates``` to ```Y```  \n* In section ```[List.External:AutoStatus]``` verify that the ```interval``` is set to ```1000```  \n\n\nConfiguration / Execution\n-------------------------\n\nThe framework processes a queue of preconfigured \"jobs\" which are defined in the configuration file ```run.ini```. A job basically means the execution of a certain password guesser. The guessers are preconfigured in the shell scripts in the folder ```scripts```. The scripts execute the training command (if provided by the guesser) and the guessing command. To configure a job, you find detailed descriptions about the different parameters in the comments at the top of the ```run.ini```. Some parameters are required for all jobs, others are optional. The default values for the optional parameters can be found in the ```DEFAULT``` section of the file. Furthermore, there are a couple of special parameters which are used for features independent from any job. These parameters are also to be set in the ```DEFAULT``` section.  \n\nOnce set up, a job execution is split into 3 phases:\n\n* Preparation: Generates the required output files with a timestamp and unique IDs to identify. Also are the session files of the JtR instance, which is used for the hash evaluation, deleted in order to guarantee that all jobs are started without any previously cracked passwords in the \"cache\" of JtR.  \n* Execution: The execution phase starts the guesser and the analysis module and links the ```STDIN``` and ```STDOUT``` pipes of the started subprocesses.  \n* Analysis: The analysis module either receives the generated password candidates directly (for plaintext leaks) or parses the terminal output of John the Ripper (hash evaluator) to gather information about the current cracking status.  \n\nIn addition to the regular framework features, we provide a web frontend which uses live data to plot guess-number graphs and shows the progress of the current job and the overall progress of the PGF run.\n\nBefore you run the framework we suggest to test the single \"Guesser Wrapper Scripts\", e.g., via ```./scripts/PRINCE.sh /opt/pgf/leaks/myspace_training.txt 10```.  \nIf you can see the generated passwords, you should give it a try to execute the framework simply by running ```python main.py```.  \nIf you have trouble with the \"Guesser Wrapper Scripts\" make sure all directories are correctly setup and check whether the scripts are executable (```chmod +x /scripts/PRINCE.sh```).  \n\n\nExtension\n---------\n\nThe framework is designed to be easily extendable for specific needs and use cases.  \nMainly the following components can be extended:  \n\n* Input formats  \n* Analysis capabilities (plugins)  \n\nBy default, the Password Guessing Framework supports the input formats **pure plaintext** and **pure hash**, meaning input files with one password/hash value per line. Also the widely spread **withcount** leaks can be used as input files for the framework without any adaptations. Parsers for other input formats, e.g., shadow hash files, can easily be implemented.\n\nFor the extension of analysis capabilities, the analysis module provides a method to execute plugin-code which is run after all candidates have been processed.  \n\n![Alt text](/docs/screenshots/architecture.png?raw=true \"Architecture of the PGF\")\n\nOutput\n------\n\nThe framework creates a couple of output files for a run in the local ```results``` folder. Besides the ```log.txt``` which includes log and debug messages, a ```jobs.json``` is created which holds information about the configured jobs of the current run. It will be overwritten for each new PGF run but when backing up the output files after a successful run, the ```jobs.json``` receives a timestamp and an unique identifier to be able to connect it with the rest of the output files of that run.  \n\nThe progress and the cracking success is written into a **CSV-file** for each guesser, respectively. The files serve on the one hand as input for the live visualization module, on the other hand they open the ability to plot detailed Guess-number graphs with **GnuPlot** or similar software after the comparision is done. The actualization interval is set to 1000 by default, meaning every 1000 candidates the file is updated with the amount of processed candidates, the amount of cracked passwords and the percentage in regard of the total passwords in the input file (leak).  \n\n\nWeb Frontend\n------------\n\n![Web Frontend](/docs/screenshots/webfrontend.png?raw=true \"Web Frontend\")\n\nTo use the optional web visualization frontend, simply follow these steps:\n\n* Move to the working directory ```passwordguessingframework\\utils\\visualization\\dynamic``` in the terminal.\n* Make sure that the file ```webserver.py``` is executable. Use ```chmod +x webserver.py``` to make it executable if necessary.\n* Use ```./webserver.py``` to start the server.\n* Click the ```click_me.html``` in the directory mentioned above or navigate to \"http://localhost:31338/utils/visualization/dynamic/frontend/static/index.html\" in your browser directly (you can bookmark this url).\n* You can easily access the web frontend on a remote machine via an SSH tunnel. (```ssh somehost -L 31338:127.0.0.1:31338```)\n\nThe frontend shows the progress of the current PGF run along with information about the cracking success, the job queue etc.\n\nLicense\n-------\n\nThe **Password Guessing Framework** is licensed under the MIT license.  \nPlease note: The dynamic visualization module utilizes the Highcharts JS (by Torstein Honsi 2014) library which is only free of use in non-commercial software projects. Refer to [docs/LICENSE](docs/LICENSE) for more information.  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRUB-SysSec%2FPassword-Guessing-Framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRUB-SysSec%2FPassword-Guessing-Framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRUB-SysSec%2FPassword-Guessing-Framework/lists"}