Release 1.4.3

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

README.md

@@ -1,56 +1,200 @@
 # BruteSleuth
+
+[![GitHub Version](https://img.shields.io/github/v/release/rad10/BruteSleuth)](https://github.com/rad10/BruteSleuth/releases)
+[![PyPI](https://img.shields.io/pypi/v/BruteSleuth?style=flat)](https://pypi.org/project/BruteSleuth/)
+[![GPL3 License](https://img.shields.io/github/license/rad10/BruteSleuth?style=flat)](https://www.gnu.org/licenses/gpl-3.0.en.html)
+[![Package build status](https://img.shields.io/github/workflow/status/rad10/BruteSleuth/Python%20package?logo=GitHub)](https://github.com/rad10/BruteSleuth/actions/workflows/python-package.yml)
+
 This program uses string formatting to give a list of strings related to an original string based off regex
 
-## Description of Formatting
-This script works with official python formatting. For more information on proper python
-formatting, see the official documentation[1].
+## Table of Contents
+
+ * [How to install BruteSleuth](#how-to-install-brutesleuth)
+    * [Pip](#pip)
+    * [Debian](#debian)
+    * [RHEL](#rhel)
+    * [Arch](#arch)
+    * [Source](#source)
+ * [What is BruteSleuth](#what-is-brutesleuth)
+ * [Why use BruteSleuth](#why-use-brutesleuth)
+ * [Contributing](#contributing)
+ * [Links](#links)
+ * [Authoring](#authoring)
+
+
+## How to install BruteSleuth
+
+With the way that the project is set up, there are multiple ways to install
+BruteSleuth. The main way to install it is through pip, but it can be installed
+on Debian, Arch, and RHEL.
+
+### Pip
+
+to install the project from anywhere, the command is simply:
+
+```bash
+python -m pip install BruteSleuth
+```
+
+or
+
+```bash
+pip install BruteSleuth
+```
+
+If you are deciding to use the manual wheel from the releases page, you can
+always install it directly with pip as well
+
+```bash
+pip install ./BruteSleuth-1.4.0-py3-none-any.whl
+```
+
+### Debian
+
+In the releases, there should be a `.deb` file for debian users. It is not
+bound to any particular distro. The only special difference with it is that it
+requires the OS to recognize a version of Python 3, which most Distro's already
+have installed. You can install the deb file with either of these two commands.
+
+```bash
+sudo apt install ./python3-brutesleuth_1.4.0-1_all.deb
+```
+
+or with
+
+```bash
+sudo dpkg -i python3-brutesleuth_1.4.0-1_all.deb
+```
+
+### RHEL
+
+For you fedora/RHEL users, I also provided an RPM file that can be used with
+dnf. You can install it with:
+
+```bash
+sudo rpm -i BruteSleuth-1.4.0-1.noarch.rpm
+```
+or
+
+```bash
+sudo dnf localinstall BruteSleuth-1.4.0-1.noarch.rpm
+```
+
+or
+
+```bash
+sudo yum localinstall BruteSleuth-1.4.0-1.noarch.rpm
+```
+
+### Arch
+
+I include a `PKGBUILD` file in the root of the repo that can be used to install
+the package (written by me, so you know that the source is trustworthy.) To
+install the package, either clone the repo or just download the `PKGBUILD` file
+then run the usual commands that you would to install the package.
+
+```bash
+makepkg -si
+```
+
+Or if you don't want to build it yourself (which I get), I also include a
+`.pkg.tar.zst` file that you can use directly with pacman.
+
+```bash
+pacman -U python-brutesleuth-git-1.4.0.r0.?-1-any.pkg.tar.zst
+```
+
+### Source
+
+For those of you wanting to be a little bit adventurous out there or want to
+directly install a modified version of this library, you can easily directly
+install the package by going into the cloned folder and running:
+
+```bash
+python setup.py install
+```
 
-This program also works with custom formatting of its own design. This was implemented so
-that iteration using multiple unique character sets was possible.
+## What is BruteSleuth
 
-## Pythonic Formatting
-As stated, this program works with the majority of formatting that can be done in python.
-What this means is that you can input almost any string into the programs formatter that
-will work in a python f-string or string.format function. As such, "`{0:4d}`" will use the
-first generator to iterate through 4 base 10 digits in the chain. Currently only digit
-based filters work (though they are for the most part the only bits that will make sense)
-but this means that "`{2x}`" for 2 hex characters will work, as well as "`{0:08b}`" and "`{0:3o}`"
-and other formats that can be iterated may be added in the near future.
+BruteSleuth is a smart Bruteforce engine. What this means is that it can take
+a pattern string and output **every** combination that fits within that
+pattern into a wordlist. There are tools that can make every permutation of a
+character for a given length to be used in a wordlist, but what makes
+BruteSleuth smarter is that you as the user can decide what positions a
+character can be and what spots are constants. This means that the number of
+words that will be used for your wordlist go down the more information that
+you know, making it a smart Bruteforcer.
 
-## Custom Formatting
-An example of a unique character set would be "`{4a}`", which is a custom combo of an iterator
-of 4 characters long using lowercase letters. `{5aAd}` is a 5 character long iterator using
-lowercase, uppercase, and number characters for iteration. As of right now, the current custom
-formats available are:
+## Why use BruteSleuth
 
-> a: Lowercase Alphabet
+Story time:
+I first created this tool to be used in the National Cyber League
+([NCL](https://nationalcyberleague.org/)) to be used in one of their Capture
+The Flags (CTFs). I specifically made this tool for the hash cracking
+section. One of the sections is always to find the flag that the hash
+represents. The flag would always be SKY, 4 letters, then 4 digits as such:
+`SKY-KVjW-1830`, but then there was another section where all the hashes
+were a developers name, an animal, then 2 digits. I could make a wordlist by
+making a python script that generates each combination. The SKY flags would
+require at least 2 nested for loops to get every combo, and the developer
+hashes would require at least 3 nested for loops. Plus the script wasnt easily
+modifiable to go from one to the other. After doing to many hash cracking
+challenges where I have to make a new python script to make my wordlist, I
+started to get fed up with it and decided that I would make a python script to
+[rule them all](https://static0.gamerantimages.com/wordpress/wp-content/uploads/2021/08/Lord-of-the-Rings-Eye-of-Sauron-Mordor-1.jpg).
+Since then, I have been using this script to make all of my custom wordlists.
+[/story]
 
-> A: Uppercase Alphabet
+Why would you want to use BruteSleuth? Because making a custom python script
+every time that you have a unique wordlist is obnoxious. Why do that when you
+could use this tool to do all the forloops for you in the background. If you
+understand how f-strings work, then you can make any custom wordlist that your
+heart desires. You can even use full words in your combinations if you wanted.
 
-> d: Decimal Numbers
+For those of you who are looking at this and asking: How is this better than
+hash masks? For those who do not know, some BruteForce tools, such as
+[John the Ripper](https://www.openwall.com/john/doc/RULES.shtml) and
+[Hashcat](https://hashcat.net/wiki/doku.php?id=mask_attack) both provide a
+ruleset to make smart patterns for BruteForcing. The way that this tool is
+better than these options is that it isn't. Even if the pattern ruleset is far
+superior to hashcat or johns, nothing will beat the unison. When hashcat uses
+a mask, the mask gets directly turned into a hash and compared. With this tool,
+you would have to first output the wordlist to a file (which could go into the
+GB in size), then use that file as input for hashcat. For memory and storage
+sake, hashcat/john is 100% the way to go, but there is still a good reason to
+use this tool for bruteforcing. There are far more bruteforcing tools besides
+hashcat and john, and most do not support a masking feature. Bruteforcing tools
+such as Medusa, Ncrack, aircrack-ng, and hydra (kinda) do not have a way to
+make a passwordlist based off a pattern or a hash mask. Since there will always
+be tools like these that will only accept a file with password lines on each
+line, it is a solid option to be able to convert your mask consistently to a
+wordlist that can be used by **any** tool that is designed for some form of
+bruteforcing. In addition to this, BruteSleuth can even take a pattern string
+and convert it into a hash mask for you in case you dont know how to program
+one yourself (though it is 100% worth it to learn).
 
-> s: Special Characters (!,@,#,$)
+Another reason to use this tool for those masochistic enough to still want a
+python script for their wordlist generation is that all the major functions
+used in making any permutation wordlist can be used in your own scripts. I
+heavily document every function that I write (seriously, roughly 2/3 of every
+file is comments or doc strings). These include everything from the custom
+classes used to permutate combinations, to a proper iter_product function that
+properly products every iter without using all the memory (itertools, eat your
+heart out), to the functions that convert a pattern string into an iter class
+with every password available. All that and more by simply adding this to your
+project:
 
-> w: Custom Wordlist. This format is only available with the -w argument
+```python
+import brutesleuth
+```
 
-More are on the way, but the custom iterators allow any combonation of each other for more unique
-bruteforcing.
+## Contributing
 
-## ID Tags
-in official python formatting, these are the numbers before a colon that tell the format function
-which parameter to use per format tag. Examples such as `{0:04d}`, which to python says that the first
-argument will go into the format. Custom formats also work with ID Tags, but in a unique way to help
-the program differentiate the two. an example of a custom format with an id is `{0+4aA}`. This says
-that the first argument is expected to be an iterator of length 4 with uppercase and lowercase letters.
-The advantages of using ID's are two fold: if you have a bruteforce string that you know repeats in
-another portion of the password, then you can call the iterative number twice, meaning less false
-positives and less passwords to generate, which means it runs faster. The other advantage is you can
-prioritize portions of the unknown password. formats with smaller ID's will change value far less often
-than a format with a higher value. This can make life easier as the password list continues to grow in size.
+see [CONTRIBUTING.md](docs/CONTRIBUTING.md)
 
-## Links:
+## Links
 [1] https://docs.python.org/3.4/library/string.html#format-string-syntax
 
-## Authoring:
+## Authoring
 This program was built by Nicholas Cottrell (Rad10Logic)
 April 4th, 2020