Metadata-Version: 2.4
Name: PortMiner
Version: 0.2.1
Summary: A simple and Lite URL port scanner built with pure Python
Home-page: https://github.com/MobinSalehiP/
Author: Mobin Salehi
Author-email: salehimobin343@gmail.com
License: GPL-3.0-or-later
Project-URL: GitHub, https://github.com/MobinSalehiP/Port-Miner
Project-URL: PyPI, https://pypi.org/project/PortMiner/
Keywords: port scanner,network,security,latency,portminer,port,url,ports
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# Port Miner ⛏️

[![PyPI version](https://img.shields.io/pypi/v/portminer.svg)](https://pypi.org/project/PortMiner/)
[![Python Version](https://img.shields.io/pypi/pyversions/portminer.svg)](https://pypi.org/project/PortMiner/)
[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/portminer.svg)](https://pypi.org/project/PortMiner/)
[![Total Downloads](https://static.pepy.tech/personalized-badge/portminer?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/portminer)
[![Status](https://img.shields.io/badge/status-active-brightgreen.svg)](https://github.com/MobinSalehiP/Port-Miner)

**Port Miner** is a simple, lightweight, and easy-to-use port scanner built with pure Python.

It allows users to provide a URL or hostname, checks a predefined list of common network ports, and displays the ports that are open and reachable.

Port Miner focuses on simplicity, minimal dependencies, and an easy setup process. It is designed as a small networking utility and a learning project for developers interested in Python, sockets, and basic network scanning.

## ✨ Features

- ⚡ **Lightweight:** Designed to be simple and straightforward.
- 🐍 **Pure Python:** Uses Python's standard library without requiring third-party runtime packages.
- 🌐 **URL and hostname input:** Accepts a target for port scanning.
- 🔎 **Common port scanning:** Checks a predefined list of ports.
- 🎯 **Simple output:** Displays detected open ports.
- 🧵 **Concurrent scanning:** Uses `ThreadPoolExecutor` to check multiple ports concurrently.
- 🧩 **Minimal dependencies:** Uses modules such as `socket`, `urllib.parse`, and `concurrent.futures`.
- 💻 **Cross-platform:** Intended for Windows, Linux, and macOS.
- 📦 **PyPI distribution:** Installable through Python's package manager.

## 🛠 Requirements

- Python **3.7 or newer**
- An internet or network connection to reach the target
- Permission to scan the target system

Port Miner uses Python's standard library and does not require additional runtime dependencies.

## 📦 Installation

### Install from PyPI

Install the latest published release using pip:

```bash
pip install PortMiner
```

### Verify the installation

```bash
pip show PortMiner
```

## 🚀 How to Use

Import `scan_ports` from the package and call the function:

```python
from PortMiner import scan_ports

scan_ports()
```

The scanner will prompt you for the target and check its predefined list of ports.

### Example workflow

1. Install Port Miner.
2. Import the `scan_ports` function.
3. Run the scanner.
4. Enter the target when prompted.
5. Review the open ports reported by the program.

The exact output depends on the target, its network configuration, and which services are reachable.

## ⚙️ How It Works

Port Miner uses Python's networking capabilities to attempt connections to selected ports.

- **`socket`:** Provides the networking functionality used to test port connections.
- **`urllib.parse`:** Helps parse URL-related input.
- **`ThreadPoolExecutor`:** Enables concurrent execution of port checks.

A port is reported as open when the scanner's connection test indicates that it is accepting connections. Network restrictions, firewalls, timeouts, and filtering may affect the results.

## 🌍 Supported Platforms

Port Miner is intended to work on:

- Windows
- Linux
- macOS

The actual results may vary depending on the operating system, network configuration, and target accessibility.

## 🔐 Responsible Use

Port Miner is a networking utility intended for educational purposes and authorized testing.

**Only scan systems and networks that you own or have explicit permission to test.** Unauthorized scanning may violate organizational policies or applicable laws.

An open port does not necessarily indicate a vulnerability. Port Miner reports connection-related information and should not be treated as a complete security audit.

## 📄 License

Port Miner is distributed under the **GNU General Public License v3.0 or later (GPL-3.0-or-later)**.

You may use, study, modify, and redistribute the software under the terms of this license. When distributing covered copies or modified versions, you must comply with the applicable GPL requirements, including source-code availability and preservation of required notices.

See the [`LICENSE`](LICENSE) file for the complete license text.

Official license information: [GNU GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.html).

## 🔗 Links

- **PyPI:** https://pypi.org/project/PortMiner/
- **GitHub:** https://github.com/MobinSalehiP/Port-Miner
- **License:** [LICENSE](LICENSE)

## 👨‍💻 Author

**Mobin Salehi**

If you find a bug or have an idea for an improvement, you can open an issue in the GitHub repository or send email.
Email : salehimobin343@gmail.com

---

*Port Miner: simple tools for exploring urls ports with Python.*
