PortPulse-CLI (portpulse)

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.

[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:

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

# Or using standard pip
pip install portpulse

Option B: Local Virtual Environment from Source

# 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:

# 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

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

# 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:

{
  "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:

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:

{
  "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

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.

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