ghostport-cli 0.1.1__py3-none-any.whl

ghostport/__init__.py

@@ -0,0 +1,3 @@
+"""GhostPort: a tiny forensic CLI for local TCP ports and unexpected HTTP services."""
+
+__version__ = "0.1.1"

ghostport/__main__.py

@@ -0,0 +1,4 @@
+from ghostport.cli import main
+
+if __name__ == "__main__":
+    main()

ghostport/cli.py

@@ -0,0 +1,111 @@
+"""Typer command-line interface."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Annotated, NoReturn
+
+import typer
+
+from ghostport import __version__
+from ghostport.inspector import inspect_port
+from ghostport.models import EXIT_USAGE, error_envelope
+from ghostport.render import make_console, render
+
+MIN_TIMEOUT = 0.05
+MAX_TIMEOUT = 30.0
+
+app = typer.Typer(
+    name="ghostport",
+    help="A tiny forensic tool for local TCP ports. Localhost only, read-only, no telemetry.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"ghostport {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        bool,
+        typer.Option("--version", callback=_version, is_eager=True, help="Show version and exit."),
+    ] = False,
+) -> None:
+    """GhostPort."""
+
+
+def _fail(code: str, message: str, as_json: bool) -> NoReturn:
+    if as_json:
+        typer.echo(json.dumps(error_envelope(code, message), indent=2))
+    else:
+        make_console(stderr=True).print(
+            f"[gp.bad]error:[/] {message}", markup=True, highlight=False
+        )
+    raise typer.Exit(EXIT_USAGE)
+
+
+def _parse_port(raw: str, as_json: bool) -> int:
+    try:
+        port = int(raw.strip(), 10)
+    except ValueError:
+        _fail("invalid_port", f"invalid port {raw!r}: expected an integer from 1 to 65535", as_json)
+    if not 1 <= port <= 65535:
+        _fail("invalid_port", f"invalid port {port}: must be between 1 and 65535", as_json)
+    return port
+
+
+@app.command("inspect")
+def inspect_command(
+    port: Annotated[str, typer.Argument(metavar="PORT", help="TCP port on localhost (1-65535).")],
+    http: Annotated[bool, typer.Option("--http", help="Send one bounded HTTP GET.")] = False,
+    expect_json: Annotated[
+        bool, typer.Option("--expect-json", help="Check that Content-Type is a JSON media type.")
+    ] = False,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Emit stable machine-readable JSON.")
+    ] = False,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Add diagnostics (sensitive values redacted).")
+    ] = False,
+    timeout: Annotated[
+        float, typer.Option("--timeout", "-t", help="Per-operation timeout in seconds.")
+    ] = 3.0,
+    path: Annotated[str, typer.Option("--path", help="Request path for --http.")] = "/",
+) -> None:
+    """Inspect a localhost TCP port: connectivity, owning process, optional HTTP probe."""
+    number = _parse_port(port, json_output)
+    if not MIN_TIMEOUT <= timeout <= MAX_TIMEOUT:
+        _fail(
+            "invalid_timeout",
+            f"timeout must be between {MIN_TIMEOUT:g} and {MAX_TIMEOUT:g} seconds",
+            json_output,
+        )
+    if expect_json and not http:
+        _fail("usage", "--expect-json requires --http", json_output)
+    if not path.startswith("/") or any(c in path for c in " \r\n\t"):
+        _fail("invalid_path", "--path must start with '/' and contain no whitespace", json_output)
+
+    result = inspect_port(
+        number, timeout=timeout, http=http, expect_json=expect_json, path=path, verbose=verbose
+    )
+    if json_output:
+        typer.echo(json.dumps(result.to_dict(verbose), indent=2))
+    else:
+        render(result, make_console(), verbose)
+    raise typer.Exit(result.exit_code)
+
+
+def main() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(errors="replace")
+    app()
+
+
+if __name__ == "__main__":
+    main()

ghostport/http_probe.py

@@ -0,0 +1,133 @@
+"""Bounded HTTP probe: headers only, no redirects, no body download, no proxies."""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+
+from ghostport import __version__
+from ghostport.models import HttpResult, JsonCheck
+from ghostport.redact import redact_header, redact_url, truncate
+
+_JSON_MEDIA_TYPES = {"application/json", "text/json"}
+MAX_HEADERS = 50
+
+
+def media_type(content_type: str | None) -> str | None:
+    if not content_type:
+        return None
+    return content_type.split(";", 1)[0].strip().lower() or None
+
+
+def is_json_media_type(mt: str | None) -> bool:
+    return bool(mt) and (mt in _JSON_MEDIA_TYPES or mt.endswith("+json"))  # type: ignore[union-attr]
+
+
+def check_json(content_type: str | None) -> JsonCheck:
+    mt = media_type(content_type)
+    if mt is None:
+        return JsonCheck(
+            matched=False,
+            media_type=None,
+            message="no Content-Type header; cannot confirm a JSON response",
+        )
+    if is_json_media_type(mt):
+        return JsonCheck(
+            matched=True,
+            media_type=mt,
+            message=f"Content-Type '{mt}' is a JSON media type (body was not inspected)",
+        )
+    return JsonCheck(
+        matched=False,
+        media_type=mt,
+        message=(
+            f"Content-Type '{mt}' is not a JSON media type; "
+            "this alone does not identify the service"
+        ),
+    )
+
+
+def _url_for(address: str, port: int, path: str) -> str:
+    host = f"[{address}]" if ":" in address else address
+    return f"http://{host}:{port}{path}"
+
+
+def probe_http(
+    address: str,
+    port: int,
+    timeout: float,
+    *,
+    path: str = "/",
+    expect_json: bool = False,
+    verbose: bool = False,
+) -> HttpResult:
+    """Issue one streamed GET and record response metadata.
+
+    The body is never read: leaving the stream context closes the connection.
+    ``trust_env=False`` keeps environment proxies and netrc out of local diagnostics.
+    """
+    url = _url_for(address, port, path)
+    shown_url = redact_url(url)
+    started = time.perf_counter()
+    try:
+        with (
+            httpx.Client(
+                timeout=httpx.Timeout(timeout),
+                follow_redirects=False,
+                trust_env=False,
+                headers={"User-Agent": f"ghostport/{__version__}", "Accept": "*/*"},
+            ) as client,
+            client.stream("GET", url) as response,
+        ):
+            elapsed = round((time.perf_counter() - started) * 1000, 2)
+            content_type = response.headers.get("content-type")
+            server = response.headers.get("server")
+            headers = (
+                tuple(
+                    (name, redact_header(name, value))
+                    for name, value in list(response.headers.items())[:MAX_HEADERS]
+                )
+                if verbose
+                else ()
+            )
+            return HttpResult(
+                status="ok",
+                url=shown_url,
+                status_code=response.status_code,
+                content_type=truncate(content_type) if content_type else None,
+                server=truncate(server) if server else None,
+                response_time_ms=elapsed,
+                json_check=check_json(content_type) if expect_json else None,
+                headers=headers,
+            )
+    except httpx.TimeoutException:
+        return _failure("timeout", shown_url, f"no HTTP response within {timeout:g}s", expect_json)
+    except httpx.ConnectError:
+        return _failure("error", shown_url, "connection failed before HTTP began", expect_json)
+    except (httpx.RemoteProtocolError, httpx.ReadError, httpx.WriteError):
+        return _failure(
+            "error",
+            shown_url,
+            "port is open but did not return a valid HTTP response "
+            "(it may speak another protocol, such as TLS or raw TCP, or reset the connection)",
+            expect_json,
+        )
+    except httpx.HTTPError as exc:
+        return _failure(
+            "error", shown_url, f"HTTP probe failed ({type(exc).__name__})", expect_json
+        )
+
+
+def _failure(status: str, url: str, message: str, expect_json: bool) -> HttpResult:
+    check = (
+        JsonCheck(matched=None, media_type=None, message="not evaluated: no HTTP response")
+        if expect_json
+        else None
+    )
+    return HttpResult(
+        status=status,  # type: ignore[arg-type]
+        url=url,
+        error=message,
+        json_check=check,
+    )

ghostport/inspector.py

@@ -0,0 +1,83 @@
+"""Orchestrates the independent TCP, process, and HTTP checks."""
+
+from __future__ import annotations
+
+import platform
+import sys
+from typing import Any
+
+import httpx
+import psutil
+
+from ghostport import __version__
+from ghostport.http_probe import probe_http
+from ghostport.models import (
+    EXIT_CONNECTION_FAILED,
+    EXIT_HTTP_CHECK_FAILED,
+    EXIT_OK,
+    HttpResult,
+    InspectionResult,
+)
+from ghostport.process import identify_process
+from ghostport.tcp import LOOPBACK_ADDRESSES, probe_tcp
+
+
+def _diagnostics(timeout: float, path: str) -> dict[str, Any]:
+    return {
+        "ghostport": __version__,
+        "python": platform.python_version(),
+        "platform": sys.platform,
+        "psutil": psutil.__version__,
+        "httpx": httpx.__version__,
+        "timeout_seconds": timeout,
+        "loopback_addresses": list(LOOPBACK_ADDRESSES),
+        "http": {
+            "method": "GET",
+            "path": path,
+            "follow_redirects": False,
+            "trust_env": False,
+            "reads_body": False,
+        },
+    }
+
+
+def inspect_port(
+    port: int,
+    *,
+    timeout: float = 3.0,
+    http: bool = False,
+    expect_json: bool = False,
+    path: str = "/",
+    verbose: bool = False,
+) -> InspectionResult:
+    tcp = probe_tcp(port, timeout)
+    # Process lookup is independent: its failure never changes the TCP verdict.
+    process = identify_process(port, verbose=verbose)
+
+    http_result: HttpResult | None = None
+    if http:
+        if tcp.connected and tcp.address:
+            http_result = probe_http(
+                tcp.address, port, timeout, path=path, expect_json=expect_json, verbose=verbose
+            )
+        else:
+            http_result = HttpResult(status="skipped", error="TCP port is not open")
+
+    if not tcp.connected:
+        code = EXIT_CONNECTION_FAILED
+    elif http_result is not None and (
+        http_result.status != "ok"
+        or (http_result.json_check is not None and http_result.json_check.matched is not True)
+    ):
+        code = EXIT_HTTP_CHECK_FAILED
+    else:
+        code = EXIT_OK
+
+    return InspectionResult(
+        port=port,
+        tcp=tcp,
+        process=process,
+        http=http_result,
+        exit_code=code,
+        diagnostics=_diagnostics(timeout, path) if verbose else None,
+    )

ghostport/models.py

@@ -0,0 +1,154 @@
+"""Result types and the stable JSON schema (schema_version 1)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from ghostport import __version__
+
+SCHEMA_VERSION = 1
+TOOL_NAME = "ghostport"
+
+EXIT_OK = 0
+EXIT_CONNECTION_FAILED = 1
+EXIT_USAGE = 2
+EXIT_HTTP_CHECK_FAILED = 3
+
+TcpStatus = Literal["open", "closed", "timeout", "error"]
+ProcessStatus = Literal["identified", "partial", "unavailable", "not_found"]
+HttpStatus = Literal["ok", "error", "timeout", "skipped"]
+
+
+@dataclass(frozen=True)
+class TcpResult:
+    status: TcpStatus
+    address: str | None = None
+    latency_ms: float | None = None
+    error: str | None = None
+
+    @property
+    def connected(self) -> bool:
+        return self.status == "open"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "connected": self.connected,
+            "address": self.address,
+            "latency_ms": self.latency_ms,
+            "error": self.error,
+        }
+
+
+@dataclass(frozen=True)
+class Listener:
+    pid: int | None
+    name: str | None = None
+    exe: str | None = None
+    cmdline: tuple[str, ...] | None = None
+
+    def to_dict(self, verbose: bool) -> dict[str, Any]:
+        data: dict[str, Any] = {"pid": self.pid, "name": self.name}
+        if verbose:
+            data["exe"] = self.exe
+            data["cmdline"] = list(self.cmdline) if self.cmdline is not None else None
+        return data
+
+
+@dataclass(frozen=True)
+class ProcessResult:
+    status: ProcessStatus
+    pid: int | None = None
+    name: str | None = None
+    reason: str | None = None
+    listeners: tuple[Listener, ...] = ()
+
+    def to_dict(self, verbose: bool) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "pid": self.pid,
+            "name": self.name,
+            "reason": self.reason,
+            "listeners": [item.to_dict(verbose) for item in self.listeners],
+        }
+
+
+@dataclass(frozen=True)
+class JsonCheck:
+    matched: bool | None
+    media_type: str | None
+    message: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "expected": True,
+            "matched": self.matched,
+            "media_type": self.media_type,
+            "message": self.message,
+        }
+
+
+@dataclass(frozen=True)
+class HttpResult:
+    status: HttpStatus
+    url: str | None = None
+    status_code: int | None = None
+    content_type: str | None = None
+    server: str | None = None
+    response_time_ms: float | None = None
+    error: str | None = None
+    json_check: JsonCheck | None = None
+    headers: tuple[tuple[str, str], ...] = field(default=())
+
+    def to_dict(self, verbose: bool) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "status": self.status,
+            "url": self.url,
+            "status_code": self.status_code,
+            "content_type": self.content_type,
+            "server": self.server,
+            "response_time_ms": self.response_time_ms,
+            "error": self.error,
+            "json_check": self.json_check.to_dict() if self.json_check else None,
+        }
+        if verbose:
+            data["headers"] = [{"name": n, "value": v} for n, v in self.headers]
+        return data
+
+
+@dataclass(frozen=True)
+class InspectionResult:
+    port: int
+    tcp: TcpResult
+    process: ProcessResult
+    http: HttpResult | None
+    exit_code: int
+    diagnostics: dict[str, Any] | None = None
+
+    def to_dict(self, verbose: bool = False) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "schema_version": SCHEMA_VERSION,
+            "tool": TOOL_NAME,
+            "version": __version__,
+            "ok": self.exit_code == EXIT_OK,
+            "exit_code": self.exit_code,
+            "target": {"host": "localhost", "port": self.port},
+            "tcp": self.tcp.to_dict(),
+            "process": self.process.to_dict(verbose),
+            "http": self.http.to_dict(verbose) if self.http else None,
+        }
+        if verbose:
+            data["diagnostics"] = self.diagnostics
+        return data
+
+
+def error_envelope(code: str, message: str, exit_code: int = EXIT_USAGE) -> dict[str, Any]:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "tool": TOOL_NAME,
+        "version": __version__,
+        "ok": False,
+        "exit_code": exit_code,
+        "error": {"code": code, "message": message},
+    }

ghostport/process.py

@@ -0,0 +1,96 @@
+"""Best-effort listener identification. Never raises; never needs elevation."""
+
+from __future__ import annotations
+
+import ipaddress
+
+import psutil
+
+from ghostport.models import Listener, ProcessResult
+from ghostport.redact import redact_cmdline, redact_path
+
+_WILDCARDS = {"", "0.0.0.0", "::"}
+
+
+def _is_local_bind(ip: str) -> bool:
+    if ip in _WILDCARDS:
+        return True
+    try:
+        addr = ipaddress.ip_address(ip.split("%", 1)[0])
+    except ValueError:
+        return False
+    mapped = getattr(addr, "ipv4_mapped", None)
+    return (mapped or addr).is_loopback
+
+
+def _describe(pid: int, verbose: bool) -> Listener:
+    name: str | None = None
+    exe: str | None = None
+    cmdline: tuple[str, ...] | None = None
+    try:
+        proc = psutil.Process(pid)
+        try:
+            name = proc.name()
+        except (psutil.Error, OSError):
+            name = None
+        if verbose:
+            try:
+                exe = redact_path(proc.exe()) or None
+            except (psutil.Error, OSError):
+                exe = None
+            try:
+                cmdline = redact_cmdline(proc.cmdline()) or None
+            except (psutil.Error, OSError):
+                cmdline = None
+    except (psutil.Error, OSError):
+        pass
+    return Listener(pid=pid, name=name, exe=exe, cmdline=cmdline)
+
+
+def identify_process(port: int, verbose: bool = False) -> ProcessResult:
+    try:
+        connections = psutil.net_connections(kind="tcp")
+    except psutil.AccessDenied:
+        return ProcessResult(
+            "unavailable", reason="permission denied reading the system socket table"
+        )
+    except (psutil.Error, OSError, NotImplementedError) as exc:
+        return ProcessResult(
+            "unavailable", reason=f"could not read the socket table ({type(exc).__name__})"
+        )
+
+    pids: list[int | None] = []
+    for conn in connections:
+        laddr = conn.laddr
+        if (
+            conn.status == psutil.CONN_LISTEN
+            and laddr
+            and laddr.port == port
+            and _is_local_bind(laddr.ip)
+            and conn.pid not in pids
+        ):
+            pids.append(conn.pid)
+
+    if not pids:
+        return ProcessResult(
+            "not_found",
+            reason="no listening socket found for this port (it may belong to a process "
+            "this account cannot see, or have closed)",
+        )
+
+    visible = [pid for pid in pids if pid is not None]
+    if not visible:
+        return ProcessResult(
+            "unavailable", reason="a listener exists but its owning PID is hidden by permissions"
+        )
+
+    listeners = tuple(_describe(pid, verbose) for pid in visible)
+    primary = next((item for item in listeners if item.name), listeners[0])
+    if primary.name:
+        return ProcessResult("identified", pid=primary.pid, name=primary.name, listeners=listeners)
+    return ProcessResult(
+        "partial",
+        pid=primary.pid,
+        reason="process name is not readable with current permissions",
+        listeners=listeners,
+    )

ghostport/redact.py

@@ -0,0 +1,79 @@
+"""Redaction helpers so verbose output never leaks credentials."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from pathlib import Path
+
+REDACTED = "***"
+
+_SENSITIVE_NAME = re.compile(
+    r"auth|token|secret|passw|pwd|key|cookie|session|credential|bearer|signature|sig$",
+    re.IGNORECASE,
+)
+_QUERY_PAIR = re.compile(r"([?&;])([^=&;\s]+)=([^&;\s]*)")
+_USERINFO = re.compile(r"(://)[^/@\s]+@")
+
+MAX_VALUE_LEN = 200
+MAX_ARGS = 20
+
+
+def is_sensitive_name(name: str) -> bool:
+    return bool(_SENSITIVE_NAME.search(name))
+
+
+def truncate(value: str, limit: int = MAX_VALUE_LEN) -> str:
+    return value if len(value) <= limit else value[: limit - 3] + "..."
+
+
+def redact_text(value: str) -> str:
+    """Mask URL credentials and sensitive query values inside free text."""
+
+    def _query(match: re.Match[str]) -> str:
+        sep, key, val = match.groups()
+        return f"{sep}{key}={REDACTED if is_sensitive_name(key) else val}"
+
+    return _QUERY_PAIR.sub(_query, _USERINFO.sub(r"\1" + REDACTED + "@", value))
+
+
+def redact_header(name: str, value: str) -> str:
+    if is_sensitive_name(name):
+        return REDACTED
+    return truncate(redact_text(value))
+
+
+def redact_url(url: str) -> str:
+    return redact_text(url)
+
+
+def redact_path(path: str) -> str:
+    home = str(Path.home())
+    if home and path.lower().startswith(home.lower()):
+        return "~" + path[len(home) :]
+    return path
+
+
+def redact_cmdline(args: Iterable[str]) -> tuple[str, ...]:
+    """Mask values of sensitive flags (`--token=x`, `--token x`, `KEY=x`) and URL userinfo."""
+    out: list[str] = []
+    mask_next = False
+    for raw in args:
+        if len(out) >= MAX_ARGS:
+            out.append("...")
+            break
+        if mask_next:
+            out.append(REDACTED)
+            mask_next = False
+            continue
+        if "=" in raw:
+            key, _, _val = raw.partition("=")
+            if is_sensitive_name(key):
+                out.append(f"{key}={REDACTED}")
+                continue
+        elif raw.startswith("-") and is_sensitive_name(raw):
+            out.append(raw)
+            mask_next = True
+            continue
+        out.append(truncate(redact_text(raw)))
+    return tuple(out)

ghostport/render.py

@@ -0,0 +1,137 @@
+"""Rich terminal rendering (pastel cybercore palette)."""
+
+from __future__ import annotations
+
+from rich import box
+from rich.console import Console, Group, RenderableType
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich.theme import Theme
+
+from ghostport import __version__
+from ghostport.models import HttpResult, InspectionResult, ProcessResult, TcpResult
+
+THEME = Theme(
+    {
+        "gp.title": "bold #c9b6ff",
+        "gp.label": "bold #a9d8ff",
+        "gp.ok": "#a8ffd8",
+        "gp.warn": "#ffe3a8",
+        "gp.bad": "#ff9fc2",
+        "gp.dim": "#9aa5c4",
+    }
+)
+
+_MARK = {"ok": ("[+]", "gp.ok"), "warn": ("[~]", "gp.warn"), "bad": ("[x]", "gp.bad")}
+
+
+def make_console(**kwargs: object) -> Console:
+    return Console(theme=THEME, highlight=False, **kwargs)  # type: ignore[arg-type]
+
+
+def _line(level: str, *parts: tuple[str, str | None]) -> Text:
+    mark, style = _MARK[level]
+    text = Text()
+    text.append(mark + " ", style=style)
+    for value, part_style in parts:
+        text.append(value, style=part_style)
+    return text
+
+
+def _tcp_line(tcp: TcpResult) -> Text:
+    if tcp.connected:
+        return _line("ok", (f"open on {tcp.address}", None), (f"  {tcp.latency_ms} ms", "gp.dim"))
+    level = "warn" if tcp.status == "timeout" else "bad"
+    return _line(level, (tcp.status, None), (f"  {tcp.error or ''}", "gp.dim"))
+
+
+def _process_line(proc: ProcessResult) -> Text:
+    if proc.status == "identified":
+        return _line("ok", (f"{proc.name}", "bold"), (f"  pid {proc.pid}", "gp.dim"))
+    if proc.status == "partial":
+        return _line(
+            "warn", (f"pid {proc.pid}", None), (f"  name unavailable: {proc.reason}", "gp.dim")
+        )
+    label = "no listener found" if proc.status == "not_found" else "unavailable"
+    return _line("warn", (label, None), (f"  {proc.reason}", "gp.dim"))
+
+
+def _http_line(http: HttpResult) -> Text:
+    if http.status == "ok":
+        text = _line("ok", (f"{http.status_code}", "bold"))
+        text.append(f"  {http.content_type or 'no content-type'}", style=None)
+        text.append(f"  {http.response_time_ms} ms", style="gp.dim")
+        text.append(f"  server: {http.server or 'not sent'}", style="gp.dim")
+        return text
+    level = "warn" if http.status in ("timeout", "skipped") else "bad"
+    return _line(level, (http.status, None), (f"  {http.error or ''}", "gp.dim"))
+
+
+def _verdict(result: InspectionResult) -> Text:
+    if not result.tcp.connected:
+        return Text("Nothing accepted a localhost connection on this port.", style="gp.bad")
+    if result.exit_code == 0:
+        return Text(
+            "Port is accepting connections. These checks do not conclusively identify the service.",
+            style="gp.ok",
+        )
+    return Text(
+        "Port is open, but the HTTP check did not pass. This does not identify the service.",
+        style="gp.warn",
+    )
+
+
+def render(result: InspectionResult, console: Console, verbose: bool = False) -> None:
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="gp.label", no_wrap=True)
+    grid.add_column()
+    grid.add_row("TCP", _tcp_line(result.tcp))
+    grid.add_row("PROCESS", _process_line(result.process))
+    if result.http is not None:
+        grid.add_row("HTTP", _http_line(result.http))
+        if result.http.json_check is not None:
+            check = result.http.json_check
+            level = "ok" if check.matched else ("bad" if check.matched is False else "warn")
+            grid.add_row("JSON", _line(level, (check.message, None)))
+
+    body: list[RenderableType] = [grid, Text(), _verdict(result)]
+    if verbose:
+        body.append(Text())
+        body.append(_verbose_table(result))
+
+    title = Text.assemble(
+        ("ghostport", "gp.title"),
+        (f" v{__version__}", "gp.dim"),
+        (f"  localhost:{result.port}", None),
+    )
+    console.print(
+        Panel(
+            Group(*body),
+            title=title,
+            title_align="left",
+            box=box.ROUNDED,
+            border_style="#c9b6ff",
+            padding=(1, 2),
+        )
+    )
+
+
+def _verbose_table(result: InspectionResult) -> Table:
+    table = Table.grid(padding=(0, 2))
+    table.add_column(style="gp.dim", no_wrap=True)
+    table.add_column(overflow="fold")
+    for listener in result.process.listeners:
+        table.add_row("listener", f"pid={listener.pid} name={listener.name}")
+        if listener.exe:
+            table.add_row("  exe", listener.exe)
+        if listener.cmdline:
+            table.add_row("  cmdline", " ".join(listener.cmdline))
+    if result.http and result.http.url:
+        table.add_row("url", result.http.url)
+    if result.http:
+        for name, value in result.http.headers:
+            table.add_row(f"  {name}", value)
+    for key, value in (result.diagnostics or {}).items():
+        table.add_row(key, str(value))
+    return table

ghostport/tcp.py

@@ -0,0 +1,69 @@
+"""Localhost-only TCP connectivity probe."""
+
+from __future__ import annotations
+
+import socket
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Literal
+
+from ghostport.models import TcpResult
+
+LOOPBACK_ADDRESSES: tuple[str, ...] = ("127.0.0.1", "::1")
+
+Outcome = tuple[Literal["open", "refused", "timeout", "error"], str, float, str | None]
+
+
+def _family(address: str) -> socket.AddressFamily:
+    return socket.AF_INET6 if ":" in address else socket.AF_INET
+
+
+def _attempt(address: str, port: int, timeout: float) -> Outcome:
+    sock: socket.socket | None = None
+    started = time.perf_counter()
+    try:
+        sock = socket.socket(_family(address), socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        sock.connect((address, port))
+    except ConnectionRefusedError:
+        return ("refused", address, 0.0, None)
+    except TimeoutError:
+        return ("timeout", address, 0.0, None)
+    except OSError as exc:
+        # e.g. IPv6 loopback unavailable; only matters if nothing else answered.
+        return ("error", address, 0.0, f"{address}: {exc.strerror or type(exc).__name__}")
+    finally:
+        if sock is not None:
+            sock.close()
+    return ("open", address, round((time.perf_counter() - started) * 1000, 2), None)
+
+
+def probe_tcp(
+    port: int,
+    timeout: float,
+    addresses: tuple[str, ...] = LOOPBACK_ADDRESSES,
+) -> TcpResult:
+    """Probe loopback addresses concurrently; the first successful connect wins.
+
+    Only loopback addresses are ever contacted. Attempts run in parallel because
+    Windows can take about two seconds to report a refused loopback connection.
+    """
+    outcomes: list[Outcome] = []
+    pool = ThreadPoolExecutor(max_workers=len(addresses))
+    try:
+        futures = [pool.submit(_attempt, addr, port, timeout) for addr in addresses]
+        for future in as_completed(futures):
+            outcome = future.result()
+            if outcome[0] == "open":
+                return TcpResult("open", address=outcome[1], latency_ms=outcome[2])
+            outcomes.append(outcome)
+    finally:
+        pool.shutdown(wait=False, cancel_futures=True)
+
+    kinds = {o[0] for o in outcomes}
+    if "timeout" in kinds:
+        return TcpResult("timeout", error=f"no response within {timeout:g}s")
+    if "refused" in kinds:
+        return TcpResult("closed", error="connection refused")
+    errors = [o[3] for o in outcomes if o[3]]
+    return TcpResult("error", error=errors[0] if errors else "unable to connect")

ghostport_cli-0.1.1.dist-info/METADATA

@@ -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.* 👻

ghostport_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+ghostport/__init__.py,sha256=68ov8FwMJh6NoR0KdWLHjujyM3RLTzgTx89KOlOd45Q,110
+ghostport/__main__.py,sha256=8SYNfmgNObGkv3PdRC8JxKG90S48AxXr1g4Ri0g9Zk8,70
+ghostport/cli.py,sha256=-FeLDz0YqfBI3Ux8M3vQTxmKWeuFcHzV-rZh0mrE4K8,3549
+ghostport/http_probe.py,sha256=-AGL4-xQBI7eBhccjOb24XSdrTkSD-pbSoVjqjy1LTw,4465
+ghostport/inspector.py,sha256=QBrUGAZNpqsfmumZ5q1J7U_qyGxO2qVAqX6Wb9xZHPY,2291
+ghostport/models.py,sha256=BboU8DyC1o9c4EVx7yP-abzpXSM5D0IxfeXtj5ulXwc,4398
+ghostport/process.py,sha256=NC6Kau8SjcBXDPBoHsCbcXICRpkFpeiiTg7XHv6ndzM,3023
+ghostport/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ghostport/redact.py,sha256=erbsAeNZKWi1qhieAZHJLrVrsspvf_vjmT4111QsAh0,2236
+ghostport/render.py,sha256=voygW6gwHOS7xdbYuPiHBLB8DxeznxAm86ZenWPHVlo,4895
+ghostport/tcp.py,sha256=T5kNE9yUrNTDwvzwd2uZDxGwHfo8Srg8644_IhpmBu8,2525
+ghostport_cli-0.1.1.dist-info/METADATA,sha256=5huQT5KlzkKA-NhgoYn0j6yy0t9laHbvybcIdmMZV5A,10745
+ghostport_cli-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+ghostport_cli-0.1.1.dist-info/entry_points.txt,sha256=32CZvhl2CfwkosJ6EquO5o2SWb03p4CHetjhrkWHOPc,49
+ghostport_cli-0.1.1.dist-info/licenses/LICENSE,sha256=Q7X2NS-UVrfPWkwSsN6Y9qPWFEP_DUbtmgI3nHeNSNQ,1069
+ghostport_cli-0.1.1.dist-info/RECORD,,

ghostport_cli-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ghostport_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ghostport = ghostport.cli:main

ghostport_cli-0.1.1.dist-info/licenses/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.