Skip to main content

👻 GhostPort

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 Platform License Version

Getting Started · Commands · How It Works · Safety · Contributing


✦ 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

python -m pip install ghostport-cli

The PyPI package is named ghostport-cli; the command and import name are ghostport.

Install from GitHub

python -m pip install git+https://github.com/CyberStudiosTM/GhostPort.git

Install for development

git clone https://github.com/CyberStudiosTM/GhostPort.git
cd GhostPort
python -m pip install -e ".[dev]"

Your first inspection

ghostport inspect 8080

Check the HTTP response:

ghostport inspect 8080 --http

Expect a JSON response:

ghostport inspect 8080 --http --expect-json

Export a report:

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

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?

ghostport inspect 3000

What's responding on my API port?

ghostport inspect 8000 --http

Is this endpoint returning JSON?

ghostport inspect 8000 --http --expect-json

I need a report for another tool.

ghostport inspect 8000 --http --json

Show additional diagnostics.

ghostport inspect 5432 --verbose

✧ Example Output

This example comes from a local GhostPort test against a Python HTTP server.

$ 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.

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


☁️ 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

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.


✿ 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.

Repository · Issues · Security

End of transmission. The port is still listening. 👻

Metadata

Release files for ghostport-cli 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ghostport-cli 0.1.1
File Size Uploaded Provenance Actions
ghostport_cli-0.1.1.tar.gz 21.1 kB With provenance Details for ghostport_cli-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ghostport-cli 0.1.1
File Interpreter ABI Platform Actions
ghostport_cli-0.1.1-py3-none-any.whl Python 3 none any Details for ghostport_cli-0.1.1-py3-none-any.whl

Total release size: 39.1 kB

Release files / ghostport_cli-0.1.1.tar.gz

Download URL ghostport_cli-0.1.1.tar.gz
Size 21.1 kB
Tags Source
SHA-256 checksum
How to use checksums
dc8e43f6ef14dd0122f4d7a3f144a29796feff9d059f6d58857c57dc362b7574
BLAKE2b-256 checksum
How to use checksums
dc5191c033798b26dd6a3a78982d664b6da02c21e3def6d5a60b88cef64aea76
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / ghostport_cli-0.1.1-py3-none-any.whl

Download URL ghostport_cli-0.1.1-py3-none-any.whl
Size 18.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1da0784ffc5c55bc7ce9c321138f570c14e5e422748277a5e51eed632eecd075
BLAKE2b-256 checksum
How to use checksums
70e8874f40f46b62156a8387f07676f3aafd92b76667496a5561367317125f47
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for ghostport-cli 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ghostport_cli-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page