Crowd-sourced credential stuffing engine built for security professionals.
NOTE: a full overhaul is in the works to turn this into a comprehensive credential theft framework for red-teams.
brute is a Python-based library framework and engine that enables security professionals to rapidly construct bruteforce / credential stuffing attacks. It features both a
multi-purpose command-line application (
brute), and a software library that can be used in tandem to quickly generate standalone module scripts for attack.
brute is built for Python 3.7+, and should work with any operating system, preferably macOS/Linux.
brute, you can either install through
$ pip install brute-engine --user
or build locally:
git clone https://github.com/ex0dus-0x/brute cd brute/ python3 setup.py install
usage: brute [-h] [--list_modules] [--add_module ADD_MODULE] [--new_module NEW_MODULE] [-m MODULE] [-u USERNAME] [-w WORDLIST] [-a ADDRESS] [-p PORT] [-d DELAY] crowd-sourced credential stuffing engine optional arguments: -h, --help show this help message and exit Module Management: --list_modules List out the currently available modules in the local registry. --add_module ADD_MODULE Add a new module to the local registry. --new_module NEW_MODULE Given a specifier (type/name), initialize a new module plugin. Launching an Attack: -m MODULE, --module MODULE Provide a valid module to be executed. -c COMBO_LIST, --combo_list COMBO_LIST Path or valid URL to combination list (--username and --wordlist will be ignored). -u USERNAME, --username USERNAME Provide a valid username/identifier for module being executed. Can either be a single username, comma-seperated list of users, or a file. -w WORDLIST, --wordlist WORDLIST Provide a file path, directory of files, or a HTTP URL to a wordlist. -a ADDRESS, --address ADDRESS Provide host address for specified service. Required for certain protocols. -p PORT, --port PORT Provide port for host address for specified service, otherwise default will be used. -d DELAY, --delay DELAY Provide the number of seconds the program delays as each password is tried. -t TIMEOUT, --timeout TIMEOUT Number of seconds to stop bruteforce execution on currently executing user.
To interact with the modules in your local registry, you can do the following:
show all modules in registry brute --list_modules create a new plugin script brute --new_module web/mysite .. edit it with functionality vim mysite.py now you can run it normally ... python3 mysite.py --username test --wordlist wordlist.txt .. or add it to the registry and use it with the cli brute --add_module mysite.py brute -m mysite --username test --wordlist wordlist.txt
You can specify different credential inputs in different formats.
First, you can use multiple usernames, either in a comma-seperated list or a file path. Be
sure to set a timeout with
-t/--timeout in order to stop an execution on a user after
a finite amount of time. You can also choose to use a URL with a wordlist as well.
# with multiple usernames and a URL wordlist, timeout per user of 5 seconds $ brute -m mysite --username myname,othername,anothername, --wordlist https://example.com/leak.txt -t 5 # with username file and wordlist file, timeout per user of 3 seconds $ brute -m mysite --username user.txt --wordlist pass.txt -t 3
To better automate credential stuffing campaigns, you can use
--wordlist flags, with either a filepath or URL. Be sure that the file
contains a colon-seperated combo per line as so:
# with a file $ brute -m mysite --combo_list test.txt # .. or a URL $ brute -m mysite --combo_list http://example.com/leak.txt
As seen previously, brute enables security engineers to develop their own attacks using the Python API exposed to them. Here is a how a generated template script for a
$ brute --new_module protocol/mymod $ vim mymod.py
#!/usr/bin/env python3 """ mymod.py Module Name: mymod Author: YOU <firstname.lastname@example.org> Description: DESCRIPTION """ import dataclasses # include any other networking imports needed! from brute.core.protocol import ProtocolBruteforce class Mymod(ProtocolBruteforce): name = "mymod" # replace! you can delete address if you choose to specify through a CLI. address = "0.0.0.0" port = 00 def success(self) -> int: return 0 def init(self): """ Performs the necessary initialzation in order to interact with the service. This means creating any client objects, setting up the environment, etc. """ pass # def sanity(self): def brute(self, username, pwd_guess) -> int: """ `brute()` should be implemented to represent how a single response against the service would be done. The engine will then use this as a callback during the bruteforce execution. """ pass if __name__ == "__main__": args = Mymod.parse_args() Mymod( address=args.address, username=args.username, wordlist=args.wordlist, delay=args.delay, port=args.port, ).run()
Once the attack developer implements the necessary parameters and functionality needed to make their attack work, they can now run it as a standalone script, or bake it into brute's module system for later reuse. This plugin-based architecture makes it deal for attack developers to rapidly build up a script using a simple cookie-cutter template for their use.
If you have any proposed changes, please make a pull request or issue!
brute was designed as a pragmatic approach towards credential stuffing and reuse. In no way does it endorse malicious hacking. Please do not support the use of this code as a method of advancing black-hat activites.