portslayer 1.1.0__py3-none-any.whl

portslayer/__init__.py

@@ -0,0 +1,5 @@
+"""PortSlayer — cross-platform port inspector and process killer."""
+
+__version__ = "1.1.0"
+__author__ = "PortSlayer Contributors"
+__license__ = "MIT"

portslayer/cli.py

@@ -0,0 +1,306 @@
+"""
+PortSlayer CLI — powered by Typer + Rich.
+
+Commands:
+  portslayer                   Launch the interactive TUI dashboard
+  portslayer list              List all active ports
+  portslayer find <port>       Show all bindings matching a port or prefix (e.g. '808' -> 8080/8081/8083)
+  portslayer kill <port>       Kill the process(es) bound to an exact port
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm
+from rich.table import Table
+from rich.text import Text
+
+from .core import PortInfo, PortScanner, ProcessKiller
+from .utils import get_platform, is_admin, validate_port, validate_port_prefix
+
+app = typer.Typer(
+    name="portslayer",
+    help="[bold cyan]PortSlayer[/] — inspect and kill processes by port.",
+    rich_markup_mode="rich",
+    no_args_is_help=False,
+)
+
+console = Console()
+scanner = PortScanner()
+killer = ProcessKiller()
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ────────────────────────────────────────────────────────────────────────────
+
+
+def _state_style(state: str) -> str:
+    s = state.upper()
+    if "LISTEN" in s:
+        return "bold green"
+    if "ESTABLISHED" in s:
+        return "cyan"
+    if "TIME_WAIT" in s or "CLOSE" in s:
+        return "yellow"
+    return "white"
+
+
+def _build_table(entries: list[PortInfo], title: str = "Active Ports") -> Table:
+    table = Table(
+        title=title,
+        box=box.ROUNDED,
+        header_style="bold magenta",
+        show_lines=False,
+        expand=False,
+    )
+    table.add_column("Port", style="bold yellow", justify="right", no_wrap=True)
+    table.add_column("Protocol", justify="center")
+    table.add_column("State", no_wrap=True)
+    table.add_column("PID", justify="right", style="dim")
+    table.add_column("Process", style="bold")
+    table.add_column("Local Address")
+    table.add_column("Remote Address", style="dim")
+
+    for e in entries:
+        table.add_row(
+            str(e.port),
+            e.protocol,
+            Text(e.state, style=_state_style(e.state)),
+            str(e.pid) if e.pid else "—",
+            e.process_name,
+            e.local_address,
+            e.remote_address,
+        )
+    return table
+
+
+class _NullStatus:
+    def __enter__(self) -> "_NullStatus":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        return None
+
+
+def _status(message: str, *, quiet: bool = False):
+    """Return a Rich status spinner, or a no-op context manager when *quiet*."""
+    return _NullStatus() if quiet else console.status(message)
+
+
+def _print_entries(entries: list[PortInfo], title: str, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps([e.as_dict() for e in entries], indent=2))
+        return
+    console.print(_build_table(entries, title=title))
+
+
+def _abort(msg: str) -> None:
+    console.print(f"[bold red]Error:[/] {msg}")
+    raise typer.Exit(code=1)
+
+
+def _check_port_arg(port: int) -> None:
+    ok, reason = validate_port(port)
+    if not ok:
+        _abort(reason)
+
+
+def _check_port_prefix_arg(port: str) -> None:
+    ok, reason = validate_port_prefix(port)
+    if not ok:
+        _abort(reason)
+
+
+def _warn_if_no_admin() -> None:
+    if not is_admin():
+        console.print(
+            Panel(
+                "[yellow]Warning:[/] Some processes may be hidden without "
+                "root / Administrator privileges.",
+                expand=False,
+                border_style="yellow",
+            )
+        )
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Commands
+# ────────────────────────────────────────────────────────────────────────────
+
+
+@app.command("list")
+def cmd_list(
+    port: Optional[str] = typer.Option(
+        None,
+        "--port",
+        "-p",
+        help="Filter by port number or partial prefix, e.g. '808' matches 8080/8081/8083.",
+    ),
+    process: Optional[str] = typer.Option(None, "--process", "-n", help="Filter by process name."),
+    protocol: Optional[str] = typer.Option(
+        None, "--protocol", "-P", help="Filter by protocol (tcp|udp)."
+    ),
+    listening_only: bool = typer.Option(
+        False, "--listening", "-l", help="Show only LISTENING ports."
+    ),
+    as_json: bool = typer.Option(
+        False, "--json", help="Output as JSON instead of a table (for scripting)."
+    ),
+) -> None:
+    """List all active ports with process details."""
+    if not as_json:
+        _warn_if_no_admin()
+
+    if port is not None:
+        _check_port_prefix_arg(port)
+
+    if protocol and protocol.upper() not in ("TCP", "UDP"):
+        _abort("Protocol must be 'tcp' or 'udp'.")
+
+    with _status("[cyan]Scanning ports…[/]", quiet=as_json):
+        entries = scanner.list_ports(port_prefix=port, process=process, protocol=protocol)
+
+    if listening_only:
+        entries = [e for e in entries if e.is_listening]
+
+    if not entries and not as_json:
+        console.print("[yellow]No matching ports found.[/]")
+        raise typer.Exit()
+
+    _print_entries(entries, title=f"Active Ports ({len(entries)} entries)", as_json=as_json)
+
+
+@app.command("find")
+def cmd_find(
+    port: str = typer.Argument(
+        ...,
+        help="Port number or partial prefix to inspect, e.g. '808' matches 8080/8081/8083.",
+    ),
+    as_json: bool = typer.Option(
+        False, "--json", help="Output as JSON instead of a table (for scripting)."
+    ),
+) -> None:
+    """Show all processes bound to ports starting with PORT."""
+    _check_port_prefix_arg(port)
+    if not as_json:
+        _warn_if_no_admin()
+
+    with _status(f"[cyan]Looking up ports matching '{port}'…[/]", quiet=as_json):
+        entries = scanner.find_ports_by_prefix(port)
+
+    if not entries and not as_json:
+        console.print(f"[yellow]No process found on any port matching '{port}'.[/]")
+        raise typer.Exit()
+
+    distinct_ports = sorted({e.port for e in entries})
+    title = f"Port {port}" if distinct_ports == [int(port)] else f"Ports matching '{port}' ({len(distinct_ports)} ports)"
+    _print_entries(entries, title=title, as_json=as_json)
+
+
+@app.command("kill")
+def cmd_kill(
+    port: Optional[int] = typer.Argument(
+        None, help="Exact port whose process(es) should be killed."
+    ),
+    name: Optional[str] = typer.Option(
+        None,
+        "--name",
+        "-n",
+        help="Kill by process name instead of port (matches every port that process owns).",
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Skip confirmation prompt (use with care)."
+    ),
+) -> None:
+    """Kill the process(es) bound to PORT, or all processes matching --name, after confirmation."""
+    if (port is None) == (name is None):
+        _abort("Provide exactly one of PORT or --name.")
+
+    _warn_if_no_admin()
+
+    if port is not None:
+        _check_port_arg(port)
+        with console.status(f"[cyan]Looking up port {port}…[/]"):
+            entries = scanner.find_port(port)
+        not_found_msg = f"No process found on port {port}."
+        title = f"[red]About to kill — Port {port}[/]"
+    else:
+        with console.status(f"[cyan]Looking up processes named '{name}'…[/]"):
+            entries = scanner.list_ports(process=name)
+        not_found_msg = f"No process found matching name '{name}'."
+        title = f"[red]About to kill — processes matching '{name}'[/]"
+
+    if not entries:
+        console.print(f"[yellow]{not_found_msg}[/]")
+        raise typer.Exit()
+
+    # Show what will be killed
+    console.print(_build_table(entries, title=title))
+
+    unique_pids = {e.pid for e in entries if e.pid > 0}
+    pid_summary = ", ".join(str(p) for p in sorted(unique_pids))
+    console.print(
+        f"\n[bold]PID(s) to terminate:[/] [red]{pid_summary}[/]\n"
+    )
+
+    if not force:
+        confirmed = Confirm.ask(
+            "[bold red]Confirm kill?[/] This cannot be undone",
+            default=False,
+        )
+        if not confirmed:
+            console.print("[yellow]Aborted.[/]")
+            raise typer.Exit()
+
+    results = killer.kill_by_port(entries)
+    for r in results:
+        if r.success:
+            console.print(f"[bold green]OK[/] {r.message}")
+        else:
+            console.print(f"[bold red]FAIL[/] {r.message}")
+
+    if not all(r.success for r in results):
+        raise typer.Exit(code=1)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Version command
+# ────────────────────────────────────────────────────────────────────────────
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        from . import __version__
+        console.print(f"PortSlayer [bold cyan]{__version__}[/]")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-v",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """[bold cyan]PortSlayer[/] — cross-platform port inspector and process killer."""
+    if ctx.invoked_subcommand is None:
+        from .tui import run_tui
+
+        run_tui()
+
+
+if __name__ == "__main__":
+    app()

portslayer/core/__init__.py

@@ -0,0 +1,5 @@
+from .models import PortInfo
+from .port_scanner import PortScanner
+from .process_killer import ProcessKiller
+
+__all__ = ["PortInfo", "PortScanner", "ProcessKiller"]

portslayer/core/models.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class PortInfo:
+    """Represents a single active port binding."""
+
+    port: int
+    pid: int
+    process_name: str
+    protocol: str          # "TCP" | "UDP"
+    state: str             # "LISTEN" | "ESTABLISHED" | "TIME_WAIT" | …
+    local_address: str
+    remote_address: str = "—"
+
+    # ------------------------------------------------------------------ #
+    # Convenience helpers
+    # ------------------------------------------------------------------ #
+
+    @property
+    def is_listening(self) -> bool:
+        return "LISTEN" in self.state.upper()
+
+    def matches(
+        self,
+        port: Optional[int] = None,
+        port_prefix: Optional[str] = None,
+        process: Optional[str] = None,
+        protocol: Optional[str] = None,
+    ) -> bool:
+        """Return True if this entry satisfies all supplied filter criteria."""
+        if port is not None and self.port != port:
+            return False
+        if port_prefix is not None and not str(self.port).startswith(port_prefix):
+            return False
+        if process is not None and process.lower() not in self.process_name.lower():
+            return False
+        if protocol is not None and self.protocol.upper() != protocol.upper():
+            return False
+        return True
+
+    def as_dict(self) -> dict:
+        return {
+            "port": self.port,
+            "pid": self.pid,
+            "process_name": self.process_name,
+            "protocol": self.protocol,
+            "state": self.state,
+            "local_address": self.local_address,
+            "remote_address": self.remote_address,
+        }

portslayer/core/port_scanner.py

@@ -0,0 +1,331 @@
+"""
+Platform-aware port scanner.
+
+Linux  – primary: ``ss -tulnp``  / fallback: ``lsof -i``
+Windows – ``netstat -ano`` + ``tasklist``
+macOS   – ``lsof -i -n -P``
+
+All subprocess calls use explicit argument lists — never shell=True —
+to prevent command-injection.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from typing import Optional
+
+from .models import PortInfo
+from ..utils.platform_utils import Platform, get_platform
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Public interface
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class PortScanner:
+    """Collect active port bindings for the current platform."""
+
+    def __init__(self) -> None:
+        self._platform = get_platform()
+
+    # ------------------------------------------------------------------
+    # Main entry-points
+    # ------------------------------------------------------------------
+
+    def list_ports(
+        self,
+        port: Optional[int] = None,
+        port_prefix: Optional[str] = None,
+        process: Optional[str] = None,
+        protocol: Optional[str] = None,
+    ) -> list[PortInfo]:
+        """Return all active ports, optionally filtered."""
+        raw = self._collect()
+        return [
+            e
+            for e in raw
+            if e.matches(port=port, port_prefix=port_prefix, process=process, protocol=protocol)
+        ]
+
+    def find_port(self, port: int) -> list[PortInfo]:
+        """Return every binding on the exact port *port*."""
+        return self.list_ports(port=port)
+
+    def find_ports_by_prefix(self, prefix: str) -> list[PortInfo]:
+        """Return every binding whose port number starts with *prefix*.
+
+        E.g. prefix "808" matches 8080, 8081, 8083, ...
+        """
+        return self.list_ports(port_prefix=prefix)
+
+    # ------------------------------------------------------------------
+    # Platform dispatch
+    # ------------------------------------------------------------------
+
+    def _collect(self) -> list[PortInfo]:
+        if self._platform == Platform.LINUX:
+            return self._collect_linux()
+        if self._platform == Platform.WINDOWS:
+            return self._collect_windows()
+        if self._platform == Platform.MACOS:
+            return self._collect_macos()
+        raise RuntimeError(f"Unsupported platform: {self._platform}")
+
+    # ------------------------------------------------------------------
+    # Linux
+    # ------------------------------------------------------------------
+
+    def _collect_linux(self) -> list[PortInfo]:
+        try:
+            return self._linux_via_ss()
+        except Exception:
+            pass
+        try:
+            return self._linux_via_lsof()
+        except Exception:
+            return []
+
+    def _linux_via_ss(self) -> list[PortInfo]:
+        result = _run(["ss", "-tulnp"])
+        return _parse_ss(result.stdout)
+
+    def _linux_via_lsof(self) -> list[PortInfo]:
+        result = _run(["lsof", "-i", "-n", "-P"])
+        return _parse_lsof(result.stdout)
+
+    # ------------------------------------------------------------------
+    # Windows
+    # ------------------------------------------------------------------
+
+    def _collect_windows(self) -> list[PortInfo]:
+        result = _run(["netstat", "-ano"])
+        pid_names = _windows_pid_names()
+        return _parse_netstat(result.stdout, pid_names)
+
+    # ------------------------------------------------------------------
+    # macOS
+    # ------------------------------------------------------------------
+
+    def _collect_macos(self) -> list[PortInfo]:
+        result = _run(["lsof", "-i", "-n", "-P"])
+        return _parse_lsof(result.stdout)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Parsers
+# ────────────────────────────────────────────────────────────────────────────
+
+
+def _parse_ss(output: str) -> list[PortInfo]:
+    """
+    Parse ``ss -tulnp`` output.
+
+    Example line:
+        tcp   LISTEN  0  128  0.0.0.0:22  0.0.0.0:*  users:(("sshd",pid=783,fd=3))
+    """
+    entries: list[PortInfo] = []
+    for line in output.splitlines():
+        line = line.strip()
+        # Skip header or empty lines
+        if not line or line.startswith("Netid"):
+            continue
+
+        parts = line.split()
+        if len(parts) < 5:
+            continue
+
+        proto = parts[0].upper()   # tcp / udp
+        state = parts[1].upper() if proto == "TCP" else "—"
+        local = parts[4]
+
+        # Extract port from "address:port"
+        port = _extract_port(local)
+        if port is None:
+            continue
+
+        # Extract PID and process name from users:(("name",pid=N,fd=N))
+        pid, pname = _parse_ss_process(line)
+
+        entries.append(
+            PortInfo(
+                port=port,
+                pid=pid,
+                process_name=pname,
+                protocol=proto,
+                state=state,
+                local_address=local,
+                remote_address=parts[5] if len(parts) > 5 else "—",
+            )
+        )
+    return entries
+
+
+_SS_PROCESS_RE = re.compile(r'users:\(\("([^"]+)",pid=(\d+)')
+
+
+def _parse_ss_process(line: str) -> tuple[int, str]:
+    m = _SS_PROCESS_RE.search(line)
+    if m:
+        return int(m.group(2)), m.group(1)
+    return 0, "—"
+
+
+def _parse_lsof(output: str) -> list[PortInfo]:
+    """
+    Parse ``lsof -i -n -P`` output.
+
+    Example line:
+        sshd  783  root  3u  IPv4  12345  0t0  TCP  *:22 (LISTEN)
+    """
+    entries: list[PortInfo] = []
+    for line in output.splitlines():
+        parts = line.split()
+        # Expect at minimum: COMMAND PID USER FD TYPE DEVICE SIZE NODE NAME
+        if len(parts) < 9:
+            continue
+        pname = parts[0]
+        try:
+            pid = int(parts[1])
+        except ValueError:
+            continue
+
+        proto = parts[7].upper()  # TCP / UDP
+        addr_field = parts[8]
+
+        # State is inside parentheses at the end, e.g. "(LISTEN)"
+        state = "—"
+        if len(parts) >= 10:
+            raw_state = parts[9].strip("()")
+            state = raw_state.upper()
+
+        port = _extract_port(addr_field)
+        if port is None:
+            continue
+
+        entries.append(
+            PortInfo(
+                port=port,
+                pid=pid,
+                process_name=pname,
+                protocol=proto,
+                state=state,
+                local_address=addr_field,
+            )
+        )
+    return entries
+
+
+def _parse_netstat(output: str, pid_names: dict[int, str]) -> list[PortInfo]:
+    """
+    Parse ``netstat -ano`` on Windows.
+
+    Example line:
+        TCP    0.0.0.0:80    0.0.0.0:0    LISTENING    1234
+    """
+    entries: list[PortInfo] = []
+    for line in output.splitlines():
+        line = line.strip()
+        if not line or line.startswith("Active") or line.startswith("Proto"):
+            continue
+
+        parts = line.split()
+        if len(parts) < 4:
+            continue
+
+        proto = parts[0].upper()
+        local = parts[1]
+        remote = parts[2]
+
+        # TCP lines: Proto Local Foreign State PID
+        # UDP lines: Proto Local Foreign PID
+        if proto == "TCP":
+            if len(parts) < 5:
+                continue
+            state = parts[3].upper()
+            try:
+                pid = int(parts[4])
+            except ValueError:
+                continue
+        else:  # UDP
+            state = "—"
+            try:
+                pid = int(parts[3])
+            except ValueError:
+                continue
+
+        port = _extract_port(local)
+        if port is None:
+            continue
+
+        pname = pid_names.get(pid, "—")
+
+        entries.append(
+            PortInfo(
+                port=port,
+                pid=pid,
+                process_name=pname,
+                protocol=proto,
+                state=state,
+                local_address=local,
+                remote_address=remote,
+            )
+        )
+    return entries
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Windows helpers
+# ────────────────────────────────────────────────────────────────────────────
+
+
+def _windows_pid_names() -> dict[int, str]:
+    """Return {pid: process_name} mapping from ``tasklist``."""
+    try:
+        result = _run(["tasklist", "/FO", "CSV", "/NH"])
+        names: dict[int, str] = {}
+        for line in result.stdout.splitlines():
+            line = line.strip().strip('"')
+            parts = [p.strip('"') for p in line.split('","')]
+            if len(parts) >= 2:
+                try:
+                    names[int(parts[1])] = parts[0]
+                except ValueError:
+                    pass
+        return names
+    except Exception:
+        return {}
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Shared utilities
+# ────────────────────────────────────────────────────────────────────────────
+
+
+def _extract_port(addr: str) -> Optional[int]:
+    """
+    Extract the port number from strings like:
+        0.0.0.0:8080  [::]:443  *:22  :::8080
+    Returns None if no port can be parsed.
+    """
+    # IPv6 bracket notation: [::1]:8080
+    m = re.search(r"\]:(\d+)$", addr)
+    if m:
+        return int(m.group(1))
+    # IPv4 / wildcard: 0.0.0.0:8080 or *:22
+    m = re.search(r":(\d+)$", addr)
+    if m:
+        return int(m.group(1))
+    return None
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess:
+    """Run *cmd* safely (no shell) and return the completed process."""
+    return subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=15,
+    )