Metadata-Version: 2.4
Name: pinpulse
Version: 1.0.0
Summary: High-performance, asynchronous PIN brute-force tool with a real-time progress bar
Project-URL: Homepage, https://github.com/fr0stb1rd/PinPulse
Project-URL: Issues, https://github.com/fr0stb1rd/PinPulse/issues
Author: fr0stb1rd
License: MIT
License-File: LICENSE
Keywords: asyncio,brute-force,network-security,pentesting,pin-cracker,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.8
Requires-Dist: aiohttp
Requires-Dist: tqdm
Description-Content-Type: text/markdown

# ⚡ PinPulse
**PinPulse** is a high-performance, asynchronous PIN brute-force tool built with Python. Utilizing `asyncio` and `aiohttp`, it is designed to test the resilience of PIN-based authentication mechanisms through rapid, concurrent HTTP requests.

## ✨ Features
* 🚀 **Asynchronous Architecture:** Built on `aiohttp` for non-blocking network I/O, allowing hundreds of requests per second.
* 📊 **Real-time Progress:** Integrated with `tqdm` to provide a live progress bar, estimated time remaining, and request speed.
* 🛠️ **Fully Parameterized:** Easily adjust the target URL, concurrency limits, and PIN digit length directly from the terminal.
* 🛡️ **Smart Termination:** Automatically halts all active tasks as soon as the correct PIN is identified to save resources.

## 📦 Installation

Clone the repository to your local machine:
```bash
git clone https://github.com/fr0stb1rd/PinPulse.git
cd PinPulse
```

Install the required dependencies:
```bash
pip install -r requirements.txt
```
*(Note: Requires Python 3.7+)*

## 🚀 Usage

The most basic usage requires only a target URL:

```bash
python pinpulse.py -u "http://target-site.com/verify"
```

### Arguments

| Argument | Short | Description | Default |
| :--- | :--- | :--- | :--- |
| `--url` | `-u` | The target endpoint URL | (Required) |
| `--concurrent` | `-c` | Number of simultaneous requests | 50 |
| `--digits` | `-d` | Number of PIN digits to test | 4 |

### Examples

**Testing for a 6-digit PIN:**
```bash
python pinpulse.py -u "https://api.example.com/v1/auth" -d 6
```

**Aggressive testing with 100 concurrent workers:**
```bash
python pinpulse.py -u "https://api.example.com/v1/auth" -c 100
```

## 🛠️ How It Works
PinPulse uses an asynchronous `Semaphore` to manage request flow. This ensures that the tool respects your system's limits while maintaining maximum throughput. The script evaluates the HTTP response body for specific failure strings (e.g., "Incorrect pin code") to determine success or failure.

## ⚠️ Disclaimer
This tool is developed for educational purposes and authorized security testing (Pentesting) only. Running this against systems without explicit permission is illegal. The developer assumes no liability and is not responsible for any misuse or damage caused by this program.

