Metadata-Version: 2.4
Name: portpulse
Version: 0.1.1
Summary: High-Performance Asynchronous TCP Socket & Service Health Auditor
Home-page: https://github.com/dhruvrathod68/PortPulse-CLI
Author: Dhruv Rathod
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama>=0.4.6
Requires-Dist: python-dotenv>=1.0.1
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PortPulse-CLI (portpulse)

[![PyPI Version](https://img.shields.io/pypi/v/portpulse.svg)](https://pypi.org/project/portpulse/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Layer 4 Concurrency](https://img.shields.io/badge/concurrency-asyncio-brightgreen.svg)](https://docs.python.org/3/library/asyncio.html)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey.svg)](https://github.com/dhruvrathod68/PortPulse-CLI)

**PortPulse-CLI** is a high-throughput, non-blocking network auditor engineered to assess TCP socket reachability, categorize service endpoints, perform active and passive banner grabbing, and export structured telemetry reports without thread-pool overhead.

---

## 🎯 Primary Use Cases

* **Layer 4 Active Reconnaissance:** Rapidly discover open TCP sockets across single hosts or subnet ranges without requiring root or administrator privileges.
* **Service & Version Auditing:** Capture daemon signatures (SSH, FTP, SMTP, HTTP server tags) to identify outdated or exposed legacy protocols.
* **Attack Surface Management:** Detect rogue open ports, misconfigured perimeter firewalls, or unexpected listening services on internal infrastructure.
* **CI/CD & DevSecOps Health Checks:** Execute lightweight non-blocking socket health audits inside hardened containers and serverless pipelines.

---

## 🏛️ Architectural Overview

Traditional network discovery tools frequently rely on synchronous `socket.connect()` calls across heavy OS threads (e.g., `ThreadPoolExecutor`) or sequential blocking loops. While functional at small scales, thread-per-connection models introduce significant memory overhead, context-switching penalties, and resource contention under high socket loads.

```text
[CLI Entrypoint: portpulse <target>]
               │
               ▼
   [Dynamic Port Range Parser]  <── (Embedded Defaults or Custom JSON)
               │
               ▼
  [Async Event Loop Initiated]
               │
 ┌─────────────┼─────────────┐
 ▼             ▼             ▼
[Worker Task] [Worker Task] [Worker Task]  <── Managed concurrently via asyncio streams
 │             │             │
 └─────────────┼─────────────┘
               ▼
 [Banner Extraction & Probe Engine]
         │           │
         ▼           ▼
 [Colorama ANSI UI] [RFC JSON Report]
```

### Key Technical Advantages

* **Single-Threaded Cooperative Concurrency:** Leverages Python's `asyncio` engine coupled with underlying OS I/O multiplexers (`epoll` on Linux, `IOCP` on Windows, and `kqueue` on macOS) to monitor hundreds of concurrent sockets simultaneously.
* **Deterministic State Classification:** Accurately classifies TCP resets (`CLOSED`), firewall drops/timeouts (`FILTERED`), active handshakes (`OPEN`), and network routing anomalies (`ERROR`).
* **Leak-Proof Resource Management:** Enforces strict stream teardown with `writer.close()` and `await writer.wait_closed()` across all socket lifecycle states.

---

## 🚀 Installation & Setup

### Option A: Global System Installation via PyPI (Recommended)

Install `portpulse` directly from PyPI into an isolated global environment:

```bash
# Using pipx (Recommended for isolated CLI binaries)
pipx install portpulse

# Or using standard pip
pip install portpulse
```

### Option B: Local Virtual Environment from Source

```bash
# 1. Clone the repository
git clone https://github.com/dhruvrathod68/PortPulse-CLI.git
cd PortPulse-CLI

# 2. Create and activate a virtual environment
# On Linux / macOS / Kali:
python3 -m venv venv
source venv/bin/activate

# On Windows PowerShell:
python -m venv venv
.\venv\Scripts\Activate.ps1

# 3. Install in editable mode
pip install -e .
```

---

## 🔄 Updating PortPulse-CLI

To update your globally installed version to the latest release:

```bash
# If installed via pipx
pipx upgrade portpulse

# If installed via pip
pip install --upgrade portpulse

# If cloned from Git source
git pull origin main
pip install -e .
```

---

## 💻 Usage & Command Reference

```text
usage: portpulse [-h] [-t TARGET_OPT] [-p PORTS] [--timeout TIMEOUT]
                 [-b] [-c CONFIG] [-o OUTPUT]
                 [TARGET]

positional arguments:
  TARGET                Target hostname or IP address to audit (e.g. 127.0.0.1, scanme.nmap.org).

options:
  -h, --help            Show this help message and exit.
  -t, --target          Target hostname or IP address (flag format).
  -p, --ports           Port specification (e.g. '80', '22,80,443', or range '80-100').
  --timeout             Socket connection timeout in seconds (default: 1.5).
  -b, --grab-banner     Attempt active/passive banner grabbing on open ports.
  -c, --config          Custom file path to ports.json configuration.
  -o, --output          File path to export structured JSON telemetry report.
```

### Example Commands

```bash
# 1. Basic Scan Against Localhost (Default Port Registry)
portpulse 127.0.0.1

# 2. Custom Port List with Banner Grabbing & Custom Timeout
portpulse scanme.nmap.org -p 21,22,80,443 -b --timeout 2.0

# 3. Port Range Scan with Structured Telemetry JSON Export
portpulse 192.168.1.1 -p 80-100 -b -o scan_report.json
```

---

## 🛠️ Customizing & Extending Port Definitions

You can supply a custom JSON configuration file without modifying any Python source code. By default, `PortPulse-CLI` ships with built-in signatures for standard infrastructure services.

### Adding Custom Port Definitions

Create a JSON file (e.g., `custom_ports.json`) following this schema:

```json
{
  "common_ports": [
    {
      "port": 8080,
      "service": "Custom-Proxy",
      "probe_type": "http"
    },
    {
      "port": 27017,
      "service": "MongoDB",
      "probe_type": "passive"
    }
  ]
}
```

* **`port`**: TCP port number (1–65535).
* **`service`**: Display name for terminal logs and telemetry reports.
* **`probe_type`**: Probing mechanism (`"http"` for active `HEAD` requests, `"passive"` for greeting reads).

Execute your audit with your custom registry:

```bash
portpulse 127.0.0.1 -c custom_ports.json
```

---

## 📊 Telemetry Output Schema

When `-o` or `--output` is supplied, `PortPulse-CLI` exports a structured JSON report:

```json
{
  "target": "127.0.0.1",
  "timestamp_utc": "2026-08-31T12:00:00Z",
  "duration_seconds": 1.245,
  "summary": {
    "total_audited": 10,
    "open": 1,
    "closed": 0,
    "filtered": 9,
    "error": 0
  },
  "results": [
    {
      "port": 22,
      "service": "SSH",
      "state": "OPEN",
      "latency_ms": 1.25,
      "banner": "SSH-2.0-OpenSSH_9.2p1",
      "error": null
    }
  ]
}
```

### Telemetry Field Definitions

| Field | Type | Description |
| :--- | :--- | :--- |
| `target` | `string` | Resolved hostname or IP address audited. |
| `timestamp_utc` | `string (ISO-8601)` | Execution start timestamp in UTC. |
| `duration_seconds` | `float` | Cumulative clock time consumed by the audit loop. |
| `summary` | `object` | Aggregate counts (`total_audited`, `open`, `closed`, `filtered`, `error`). |
| `results[].port` | `integer` | TCP port number. |
| `results[].service` | `string` | Registered service label from database (or `"Unknown"`). |
| `results[].state` | `string` | Socket classification (`OPEN`, `CLOSED`, `FILTERED`, `ERROR`). |
| `results[].latency_ms` | `float` | Round-trip socket handshake time in milliseconds. |
| `results[].banner` | `string / null` | Sanitized service banner string if captured. |
| `results[].error` | `string / null` | Specific OS error message if state is `ERROR`. |

---

## 📂 Project Directory Structure

```text
PortPulse-CLI/
├── config/
│   └── ports.json          # Well-Known Port Definitions & Probes
├── venv/                   # Python Virtual Environment (git-ignored)
├── .gitignore              # Repository Exclusion Rules
├── LICENSE                 # MIT License (2026 Dhruv Rathod)
├── MANIFEST.in             # Source Distribution Packaging Manifest
├── main.py                 # Core Asynchronous Engine & CLI Entrypoint
├── requirements.txt        # Pinned Dependencies Manifest
├── setup.py                # Setuptools Packaging Manifest & Console Scripts
└── README.md               # Enterprise Documentation Module
```

---

## 🗺️ Roadmap & Upcoming Features

The following enhancements are planned for upcoming releases:

* **SSL/TLS Certificate Fingerprinting:** Extract TLS cipher suites, expiration dates, and SAN extensions on HTTPS/TLS endpoints.
* **UDP Socket Auditing:** Implement asynchronous UDP probing with ICMP port-unreachable error handling.
* **Adaptive Rate Limiting:** Dynamic concurrency throttling using `asyncio.Semaphore` based on network latency feedback.
* **Multi-Format Reporting:** Native export to CSV, Markdown summary tables, and SARIF formats.

---

## 🤝 Contributing & Issue Reporting

Contributions, bug reports, and port registry additions are welcome!

### Reporting Issues

If you encounter false classifications, socket leaks, or unhandled exceptions, please open an issue on the [GitHub Issue Tracker](https://github.com/dhruvrathod68/PortPulse-CLI/issues).

### Submitting Pull Requests

1. Fork the repository.
2. Create a feature branch (`git checkout -b feature/AddTLSAudit`).
3. Commit your changes with clear messages (`git commit -m 'feat: add TLS cert grabber'`).
4. Push to your branch (`git push origin feature/AddTLSAudit`).
5. Open a Pull Request detailing your modifications.

---

## ⚖️ License & Attribution

Distributed under the MIT License. See `LICENSE` for full details.

**Author:** Dhruv Rathod  
**Year:** 2026
