👻 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
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.1and::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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.