ghostport-cli 0.1.1__tar.gz

ghostport_cli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Format check
+        run: ruff format --check .
+      - name: Test
+        run: python -m pytest

ghostport_cli-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ghostport_cli-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

ghostport_cli-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# 🌱 Contributing to GhostPort
+
+**Welcome to the little corner of cyberspace where GhostPort lives.**
+
+GhostPort is a CyberStudios™ open-source project built around a simple idea: developer tools can be lightweight, reliable, and pleasant to use.
+
+Whether you're fixing a bug, improving documentation, adding a regression test, or investigating a platform-specific issue, contributions are welcome.
+
+## ✦ Before You Begin
+
+GhostPort is intentionally focused.
+
+Its purpose is to inspect local TCP ports and report observable diagnostic information. Contributions should preserve that purpose rather than expand the project into a general-purpose network scanner.
+
+For larger features, please open an issue to discuss the proposed scope before implementation.
+
+## 🖥️ Development Setup
+
+Requires Python 3.11 or newer.
+
+Clone the repository:
+
+```bash
+git clone https://github.com/CyberStudiosTM/GhostPort.git
+cd GhostPort
+```
+
+Create a virtual environment:
+
+```bash
+python -m venv .venv
+```
+
+Activate it on Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+Or on Linux/macOS:
+
+```bash
+source .venv/bin/activate
+```
+
+Install development dependencies:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## 🧪 Test Before You Submit
+
+Run the project's checks:
+
+```bash
+ruff check .
+ruff format --check .
+python -m pytest
+```
+
+The GitHub Actions workflow also tests Windows, Ubuntu, and macOS across supported Python versions.
+
+If a check cannot run in your environment, explain that limitation in your pull request.
+
+## 🌿 Contribution Guidelines
+
+### Keep it local
+
+GhostPort only inspects IPv4 and IPv6 loopback addresses. Do not introduce arbitrary remote scanning, telemetry, or background monitoring.
+
+### Preserve read-only behavior
+
+GhostPort must not terminate, signal, or modify processes.
+
+### Keep diagnostics independent
+
+TCP connectivity, process identification, and HTTP checks are separate observations.
+
+A process lookup failure must not turn a successful TCP result into a failure.
+
+### Respect response boundaries
+
+HTTP inspection must not read or display response bodies.
+
+Keep requests bounded, avoid following redirects, and preserve the existing proxy isolation.
+
+### Protect sensitive information
+
+New diagnostic output must not expose credentials, authentication headers, tokens, or other sensitive values.
+
+### Maintain the JSON contract
+
+Additive changes may retain `schema_version: 1`. Breaking changes require a schema-version update and corresponding documentation.
+
+### Test the behavior
+
+Add or update regression tests when changing functionality.
+
+Tests should use mocks or local test servers and must not depend on external hosts.
+
+## ✿ Opening a Pull Request
+
+A useful pull request should explain:
+
+1. What changed and why.
+2. Which issue or behavior it addresses.
+3. What tests were run.
+4. Any platform-specific limitations.
+5. Whether the JSON schema, CLI behavior, or documented safety boundaries changed.
+
+Keep pull requests focused and reviewable.
+
+## ♡ Code of Conduct
+
+Be respectful, constructive, and considerate when discussing issues or reviewing contributions.
+
+Disagreements about implementation are normal. Personal attacks, harassment, and discriminatory behavior are not welcome.
+
+This section describes project expectations and does not imply a separate formal Code of Conduct policy exists.
+
+## 📜 Licensing
+
+By contributing, you agree that your contributions are licensed under the project's [MIT License](LICENSE).
+
+---
+
+**Thanks for helping GhostPort grow.**
+
+*Every good tool starts somewhere. Sometimes that somewhere is localhost.* 👻
+
+**CyberStudios™**

ghostport_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CyberStudios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghostport_cli-0.1.1/PKG-INFO

@@ -0,0 +1,358 @@
+Metadata-Version: 2.5
+Name: ghostport-cli
+Version: 0.1.1
+Summary: A tiny forensic CLI for diagnosing local TCP ports and unexpected HTTP services.
+Project-URL: Homepage, https://github.com/CyberStudiosTM/GhostPort
+Project-URL: Issues, https://github.com/CyberStudiosTM/GhostPort/issues
+Author: CyberStudios
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,developer-tools,diagnostics,http,localhost,ports
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: psutil>=5.9
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 👻 GhostPort
+
+<div align="center">
+
+**A little ghost in your localhost.**
+
+*Find out what's listening, who's behind it, and whether it's answering the way you expected.*
+
+**A CyberStudios™ developer utility**
+
+![Python](https://img.shields.io/badge/Python-3.11%2B-BDA9F2?style=flat-square)
+![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-A9E8DC?style=flat-square)
+![License](https://img.shields.io/badge/License-MIT-B9DDF6?style=flat-square)
+![Version](https://img.shields.io/badge/Version-0.1.0-F4C7E8?style=flat-square)
+
+[Getting Started](#-getting-started) · [Commands](#-commands) · [How It Works](#-how-it-works) · [Safety](#-safety--privacy) · [Contributing](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## ✦ Welcome to GhostPort
+
+Somewhere inside your computer, a service is listening.
+
+Maybe it's your development server. Maybe it's an MCP endpoint. Maybe something else has occupied the port you expected to use.
+
+**GhostPort helps you investigate.**
+
+It's a lightweight, local-first command-line utility that inspects TCP ports on your own machine, identifies listening processes when possible, and checks how local HTTP services respond.
+
+No dashboards. No cloud account. No background daemon.
+
+Just you, your terminal, and a little ghost with questions.
+
+### What can it do?
+
+- **Inspect local ports.** Check whether a TCP port accepts connections.
+- **Identify processes.** Find the associated PID and process name when the operating system permits.
+- **Probe HTTP services.** Inspect status codes, content types, server headers, and response times.
+- **Check JSON expectations.** Find out when a service isn't returning the expected JSON media type.
+- **Generate structured reports.** Use machine-readable JSON output in scripts and developer workflows.
+- **Keep diagnostics private.** No telemetry, external requests, or process termination.
+
+GhostPort is an independent CyberStudios™ project. It does not require CyberCore or any other CyberStudios software.
+
+---
+
+## 🌱 Getting Started
+
+**Requirements:** Python 3.11 or newer.
+
+### Install from PyPI
+
+```bash
+python -m pip install ghostport-cli
+```
+
+The PyPI package is named `ghostport-cli`; the command and import name are `ghostport`.
+
+### Install from GitHub
+
+```bash
+python -m pip install git+https://github.com/CyberStudiosTM/GhostPort.git
+```
+
+### Install for development
+
+```bash
+git clone https://github.com/CyberStudiosTM/GhostPort.git
+cd GhostPort
+python -m pip install -e ".[dev]"
+```
+
+### Your first inspection
+
+```bash
+ghostport inspect 8080
+```
+
+Check the HTTP response:
+
+```bash
+ghostport inspect 8080 --http
+```
+
+Expect a JSON response:
+
+```bash
+ghostport inspect 8080 --http --expect-json
+```
+
+Export a report:
+
+```bash
+ghostport inspect 8080 --json
+```
+
+> **Note:** A successful connection doesn't prove which service owns a port. GhostPort reports the evidence it can observe without inventing an identity.
+
+---
+
+## 🖥️ Commands
+
+```text
+ghostport inspect PORT [--http] [--expect-json] [--json] [--verbose]
+                       [--timeout SECONDS] [--path /PATH]
+```
+
+| Option | Description |
+|---|---|
+| `--http` | Send one bounded HTTP GET request and inspect response headers. |
+| `--expect-json` | Validate that the HTTP content type is a supported JSON media type. Requires `--http`. |
+| `--json` | Return structured, machine-readable output. |
+| `--verbose`, `-v` | Display additional diagnostics with sensitive values redacted. |
+| `--timeout`, `-t` | Set the per-operation timeout from 0.05 to 30 seconds. Default: 3 seconds. |
+| `--path` | Specify the HTTP request path. Default: `/`. |
+
+### Example investigations
+
+**Is my development server listening?**
+
+```bash
+ghostport inspect 3000
+```
+
+**What's responding on my API port?**
+
+```bash
+ghostport inspect 8000 --http
+```
+
+**Is this endpoint returning JSON?**
+
+```bash
+ghostport inspect 8000 --http --expect-json
+```
+
+**I need a report for another tool.**
+
+```bash
+ghostport inspect 8000 --http --json
+```
+
+**Show additional diagnostics.**
+
+```bash
+ghostport inspect 5432 --verbose
+```
+
+---
+
+## ✧ Example Output
+
+This example comes from a local GhostPort test against a Python HTTP server.
+
+```text
+$ ghostport inspect 8765 --http --expect-json
+
+ghostport v0.1.0 · localhost:8765
+
+TCP       [+] open on 127.0.0.1 · 1.11 ms
+PROCESS   [+] python.exe · pid 17724
+HTTP      [+] 200 · text/html; charset=utf-8
+              403.44 ms · SimpleHTTP/0.6 Python/3.11.9
+JSON      [x] Content-Type is not a JSON media type
+
+Port is open, but the HTTP check did not pass.
+This does not identify the service.
+```
+
+The actual terminal interface uses rounded panels and a pastel color palette. GhostPort also respects `NO_COLOR`.
+
+---
+
+## 🔎 How It Works
+
+GhostPort separates its diagnostics into three independent stages.
+
+### 01 / TCP inspection
+
+Attempts a connection to the requested port using IPv4 and IPv6 loopback addresses.
+
+Reports whether the connection succeeds, fails, or times out.
+
+### 02 / Process inspection
+
+Attempts to identify the listening process using available operating-system information.
+
+Process identification may be unavailable due to permissions or platform limitations. That does not change the TCP result.
+
+### 03 / HTTP inspection
+
+When requested, sends a single HTTP GET request and inspects the response headers.
+
+GhostPort does not read or display the response body, follow redirects, or infer a service's identity from its content type.
+
+---
+
+## 📡 JSON Reports
+
+GhostPort provides a stable, versioned JSON report format.
+
+```json
+{
+  "schema_version": 1,
+  "tool": "ghostport",
+  "version": "0.1.0",
+  "ok": true,
+  "exit_code": 0,
+  "target": {
+    "host": "localhost",
+    "port": 8765
+  },
+  "tcp": {
+    "status": "open",
+    "connected": true,
+    "address": "127.0.0.1",
+    "latency_ms": 2.7,
+    "error": null
+  },
+  "process": {
+    "status": "identified",
+    "pid": 17724,
+    "name": "python.exe",
+    "reason": null,
+    "listeners": []
+  },
+  "http": null
+}
+```
+
+The `tcp`, `process`, and `http` sections remain independent. Unavailable values are represented as `null`.
+
+Supported status values:
+
+- TCP: `open`, `closed`, `timeout`, `error`
+- Process: `identified`, `partial`, `unavailable`, `not_found`
+- HTTP: `ok`, `error`, `timeout`, `skipped`
+
+When `--http` is enabled, the HTTP section includes the URL, status code, content type, server, response time, error information, and optional JSON validation result.
+
+Verbose output may additionally include redacted diagnostics, listener details, and HTTP headers.
+
+Invalid input returns a JSON error object containing the schema version, tool name, version, failure status, exit code, and structured error.
+
+Additive schema changes preserve `schema_version: 1`. Breaking changes require a new schema version.
+
+---
+
+## 🚦 Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | TCP connection succeeded and requested HTTP checks passed. |
+| `1` | TCP connection failed, timed out, or encountered an error. |
+| `2` | Invalid arguments or unsupported option combinations. |
+| `3` | TCP succeeded, but the requested HTTP or JSON check failed. |
+
+HTTP status codes such as `404` or `500` still count as valid HTTP responses for exit-code purposes.
+
+Failure to identify the process does not change the TCP result.
+
+---
+
+## 🔐 Safety & Privacy
+
+GhostPort is designed for local diagnostics.
+
+- Connects only to `127.0.0.1` and `::1`.
+- Does not offer arbitrary host scanning.
+- Never kills, signals, or modifies processes.
+- Does not require administrator privileges.
+- Does not send telemetry or contact external services.
+- Does not follow HTTP redirects.
+- Does not read or display HTTP response bodies.
+- Disables environment proxy inheritance for HTTP probes.
+- Redacts sensitive headers, credentials, query values, and command-line arguments in supported verbose diagnostics.
+
+For vulnerability reporting, see [SECURITY.md](SECURITY.md).
+
+---
+
+## ☁️ Known Limitations
+
+GhostPort is intentionally small and transparent about its capabilities.
+
+- Process identification depends on OS permissions.
+- macOS socket inspection may require elevated permissions; GhostPort continues when process information is unavailable.
+- Some Windows system processes may expose a PID without a process name.
+- Closed loopback ports may take approximately two seconds to report on Windows.
+- The default timeout is three seconds and applies per network operation, not as a total execution deadline.
+- A JSON content type does not conclusively identify a service.
+- TLS-only services are not supported by the plain HTTP probe.
+- Only IPv4 and IPv6 loopback addresses are inspected.
+
+---
+
+## 🛠️ Development
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+python -m pytest
+```
+
+GitHub Actions runs the test and lint checks on Windows, Ubuntu, and macOS using Python 3.11, 3.12, and 3.13.
+
+Want to help improve GhostPort? Read [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## ✿ Made in Cyberspace
+
+GhostPort is part of **CyberStudios™**, a creative software ecosystem exploring development tools, game systems, digital environments, and interactive experiences.
+
+Small tools deserve thoughtful engineering, too.
+
+**Developed under CyberStudios™.**
+
+Licensed under the [MIT License](LICENSE).
+
+[Repository](https://github.com/CyberStudiosTM/GhostPort) · [Issues](https://github.com/CyberStudiosTM/GhostPort/issues) · [Security](SECURITY.md)
+
+*End of transmission. The port is still listening.* 👻