Metadata-Version: 2.5
Name: portinspector
Version: 0.1.1
Summary: Lightweight cross-platform CLI developer utility for inspecting network ports and processes
Project-URL: Homepage, https://github.com/ramalingamthangamani/PortCheck
Project-URL: Documentation, https://github.com/ramalingamthangamani/PortCheck#readme
Project-URL: Issues, https://github.com/ramalingamthangamani/PortCheck/issues
Project-URL: Repository, https://github.com/ramalingamthangamani/PortCheck.git
Author: PortInspector Contributors
License: MIT
License-File: LICENSE
Keywords: cli,developer-tools,lsof,netstat,network,port,portcheck,portinspector,process
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# PortInspector

[![CI](https://github.com/ramalingamthangamani/PortCheck/actions/workflows/ci.yml/badge.svg)](https://github.com/ramalingamthangamani/PortCheck/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/portinspector.svg)](https://pypi.org/project/portinspector/)
[![Python versions](https://img.shields.io/pypi/pyversions/portinspector.svg)](https://pypi.org/project/portinspector/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**PortInspector** is a lightweight, cross-platform developer utility for inspecting local network ports and the processes using them.

Built with pure Python standard library primitives, PortInspector requires **zero runtime dependencies**, installs instantly, and works across **Windows**, **Linux**, and **macOS**.

---

## Key Features

- **Instant Visibility**: See all active and listening ports, addresses, PIDs, and process names in milliseconds.
- **Port Inspection**: Quickly check if a specific port is `ACTIVE/LISTENING` or `AVAILABLE`.
- **Port Finder**: Find the next available local port for web servers and microservices.
- **Fast Range Scanning**: Scan thousands of ports in milliseconds using OS connection caching.
- **Process Inspection**: View detailed process metadata (PID, executable path, command line, parent PID).
- **Safe Process Termination**: Kill hung processes with mandatory interactive confirmation and `--yes` automation support.
- **Continuous Watch Mode**: Real-time port monitoring that alerts when ports open or close.
- **Structured JSON Output**: Full `--json` support across commands for CI/CD pipelines, dev tooling, and scripts.
- **Zero Dependencies**: Pure Python with native platform integrations. No heavy C extensions or compilation required.

---

## Installation

```bash
pip install portinspector
```

Or using [uv](https://github.com/astral-sh/uv):

```bash
uv tool install portinspector
```

---

## Quick Reference

| Command | Description |
| :--- | :--- |
| `portinspector` | Show all active/listening local ports with process details |
| `portinspector 8000` | Inspect port 8000 (status, process, PID, protocol, address) |
| `portinspector --active` | Show only active/listening ports |
| `portinspector --scan 3000-9000` | Scan a port range and summarize active vs available ports |
| `portinspector --find` | Find an available local port (defaults to starting at 8000) |
| `portinspector --find 8000` | Start at port 8000 and find the next available port |
| `portinspector --process 8000` | Show detailed process information for the process on port 8000 |
| `portinspector --kill 8000` | Terminate the process using port 8000 (interactive confirmation) |
| `portinspector --kill 8000 --yes` | Terminate the process using port 8000 without prompting |
| `portinspector --watch` | Continuously monitor ports and report opened/closed events |
| `portinspector --watch --interval 2` | Monitor ports with a custom polling interval in seconds |
| `portinspector --json` | Output structured JSON suitable for scripts and automation |
| `portinspector --version` | Display version number |
| `portinspector --help` | Display help and usage manual |

---

## Usage Examples

### 1. List Active & Listening Ports
```bash
$ portinspector
PORT   PROTO  ADDRESS                    STATUS  PID    PROCESS
-----  -----  -------------------------  ------  -----  ---------------
22     TCP    0.0.0.0                    LISTEN  7104   sshd.exe
80     TCP    0.0.0.0                    LISTEN  1234   nginx
3000   TCP    127.0.0.1                  LISTEN  9821   node.exe
8000   TCP    127.0.0.1                  LISTEN  4218   python.exe
```

### 2. Inspect a Specific Port
```bash
$ portinspector 8000
Port 8000:
  Status:      ACTIVE/LISTENING
  Protocol:    TCP
  Address:     127.0.0.1
  Process:     python.exe
  PID:         4218
```

If the port is free:
```bash
$ portinspector 8001
Port 8001:
  Status:      AVAILABLE
  Message:     Port 8001 is available for use.
```

### 3. Find Next Available Port
Useful for configuring dev servers or automated tests:
```bash
$ portinspector --find 8000
Port 8000 is ACTIVE/LISTENING. Next available port is 8001.

$ portinspector --find 8000 --json
{
  "start_port": 8000,
  "available_port": 8001,
  "is_available": true
}
```

### 4. Scan a Port Range
```bash
$ portinspector --scan 3000-3005
Port Scan Summary (3000-3005):
  Total Scanned:    6
  Active Ports:     2
  Available Ports:  4

Active Ports:
PORT   PROTO  ADDRESS    STATUS  PID    PROCESS
-----  -----  ---------  ------  -----  -------
3000   TCP    127.0.0.1  LISTEN  9821   node.exe
3001   TCP    127.0.0.1  LISTEN  9822   vite.exe

Available Ports:
  3002, 3003, 3004, 3005
```

### 5. Detailed Process Information
```bash
$ portinspector --process 8000
Process Details (Port 8000):
  PID:         4218
  Name:        python.exe
  Status:      running
  Executable:  C:\Users\developer\AppData\Local\Programs\Python\Python310\python.exe
  Command:     python -m http.server 8000
  Parent PID:  1024
  Ports Used:  8000
```

### 6. Terminate a Process Using a Port
PortInspector prioritizes safety. Process termination always prompts for explicit confirmation unless `--yes` is passed:

```bash
$ portinspector --kill 8000
============================================================
WARNING: DANGEROUS OPERATION - PROCESS TERMINATION
============================================================
Terminating this process will immediately close its network sockets
and may cause unsaved data loss or crash dependent applications.

  Port:         8000
  PID:          4218
  Process Name: python.exe
  Path:         C:\Users\developer\AppData\Local\Programs\Python\Python310\python.exe
  Command:      python -m http.server 8000
============================================================
Are you sure you want to terminate process 4218 (python.exe)? [y/N]: y
Successfully terminated process 4218 (python.exe) on port 8000.
```

For non-interactive scripts:
```bash
portinspector --kill 8000 --yes
```

### 7. Real-Time Watch Mode
Monitor ports dynamically as services spin up or shut down:
```bash
$ portinspector --watch --interval 1.5
[13:30:00] Monitoring listening ports every 1.5s (Press Ctrl+C to stop)...
[13:30:00] Initial state: 18 listening ports detected.
[13:30:04] [OPENED] Port 5173 (TCP) on 127.0.0.1 by vite (PID: 14205)
[13:30:22] [CLOSED] Port 5173 (TCP) (was vite (PID: 14205))
^C
[13:30:30] Monitoring stopped.
```

---

## Platform Support & Architecture

PortInspector implements isolated, native OS providers:

- **Windows (`src/portinspector/platform/windows.py`)**:
  - Leverages the Windows IP Helper API (`iphlpapi.dll`) via `ctypes` (`GetExtendedTcpTable`, `GetExtendedUdpTable`).
  - Fetches complete TCP and UDP connection tables directly in-memory without spawning slow subprocesses.
  - Fallback parser for `netstat -ano`.
  - Process queries via `kernel32` (`QueryFullProcessImageNameW`) and WMI.
- **Linux (`src/portinspector/platform/linux.py`)**:
  - Reads `/proc/net/tcp`, `/proc/net/tcp6`, `/proc/net/udp`, `/proc/net/udp6`.
  - Resolves socket inodes to PIDs via `/proc/<pid>/fd/*`.
  - Fallback parser for `ss` or `netstat`.
  - Reads `/proc/<pid>/comm`, `cmdline`, `status`, and `exe`.
- **macOS (`src/portinspector/platform/macos.py`)**:
  - Built-in `lsof` parser with fallback to BSD `netstat -anv`.
  - Process metadata via `ps`.

### Permissions
- **Read-Only Inspection**: Administrator/root privileges are **never required** for normal scanning.
- **Permission Handling**: When a process is owned by another user or system account, PortInspector still reports the active port, protocol, and address gracefully while noting when PID details are restricted by OS security boundaries.
- **Process Termination**: Terminating processes owned by other users or system services requires elevated privileges.

---

## License

This project is licensed under the terms of the [MIT License](LICENSE).
