sysgraph 0.0.11__tar.gz

sysgraph-0.0.11/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eugene Gubenkov
+
+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.

sysgraph-0.0.11/MANIFEST.in

@@ -0,0 +1,7 @@
+# Include the Vite build output
+recursive-include src/sysgraph/dist *
+
+# Include top-level files
+include LICENSE
+include README.md
+include pyproject.toml

sysgraph-0.0.11/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: sysgraph
+Version: 0.0.11
+Summary: Visualizer for processes and their interconnections
+Home-page: https://github.com/gubenkoved/sysgraph
+Author: Eugene Gubenkov
+Author-email: gubenkoved@gmail.com
+License: MIT
+Project-URL: Source, https://github.com/gubenkoved/sysgraph
+Project-URL: Issues, https://github.com/gubenkoved/sysgraph/issues
+Keywords: process,visualization,graph,ipc,system,monitoring,linux,procfs
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil
+Requires-Dist: coloredlogs
+Requires-Dist: fastapi>=0.95
+Requires-Dist: uvicorn[standard]>=0.20
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# sysgraph
+
+Real-time process-graph visualizer that discovers running OS processes, their inter-process communication channels (pipes, Unix domain sockets, TCP/UDP network connections), and renders them as an interactive force-directed graph in the browser.
+
+![Python](https://img.shields.io/badge/python-%3E%3D3.12-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## Features
+
+- **Process discovery** — enumerates all running OS processes and their parent-child relationships
+- **IPC visualization** — discovers pipes, Unix domain sockets, and TCP/UDP connections between processes
+- **Interactive graph** — force-directed graph rendered in the browser with zoom, pan, drag, and search
+- **Real-time** — fetch the latest process graph on demand via the web UI
+- **Fuzzy search** — find processes by name, PID, command line, or any property
+- **Adjacency filtering** — right-click a node to show only its neighbors
+- **Configurable** — tune d3 force parameters, colors, and filters via the settings panel
+- **Export/Import** — save and load graph snapshots as JSON
+
+## Requirements
+
+- **Linux** (relies on `/proc` filesystem and the `ss` command)
+- **Python ≥ 3.12**
+- Root/sudo recommended for full visibility into all processes
+
+## Installation
+
+```bash
+pip install sysgraph
+```
+
+## Usage
+
+```bash
+# Start the web server (default: http://localhost:8000)
+sysgraph
+
+# Specify a custom port
+sysgraph --port 9000
+
+# Or run as a module
+python -m sysgraph
+```
+
+Open your browser to the displayed URL to see the interactive process graph.
+
+For full visibility into all processes and their connections, run with elevated privileges:
+
+```bash
+sudo sysgraph
+```
+
+## Docker
+
+```bash
+docker run --rm -it --pid=host --net=host gubenkoved/sysgraph
+```
+
+The `--pid=host` and `--net=host` flags allow the container to see host processes and network connections.
+
+## How It Works
+
+1. The **FastAPI backend** uses `psutil` and Linux-specific APIs (`/proc`, `ss`) to discover processes, pipes, Unix domain sockets, and network connections.
+2. It builds a graph of processes (nodes) and their IPC channels (edges).
+3. The **browser frontend** fetches the graph via `GET /api/graph` and renders it using [force-graph](https://github.com/vasturiano/force-graph) with d3 physics simulation.
+
+## License
+
+[MIT](LICENSE)

sysgraph-0.0.11/README.md

@@ -0,0 +1,68 @@
+# sysgraph
+
+Real-time process-graph visualizer that discovers running OS processes, their inter-process communication channels (pipes, Unix domain sockets, TCP/UDP network connections), and renders them as an interactive force-directed graph in the browser.
+
+![Python](https://img.shields.io/badge/python-%3E%3D3.12-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## Features
+
+- **Process discovery** — enumerates all running OS processes and their parent-child relationships
+- **IPC visualization** — discovers pipes, Unix domain sockets, and TCP/UDP connections between processes
+- **Interactive graph** — force-directed graph rendered in the browser with zoom, pan, drag, and search
+- **Real-time** — fetch the latest process graph on demand via the web UI
+- **Fuzzy search** — find processes by name, PID, command line, or any property
+- **Adjacency filtering** — right-click a node to show only its neighbors
+- **Configurable** — tune d3 force parameters, colors, and filters via the settings panel
+- **Export/Import** — save and load graph snapshots as JSON
+
+## Requirements
+
+- **Linux** (relies on `/proc` filesystem and the `ss` command)
+- **Python ≥ 3.12**
+- Root/sudo recommended for full visibility into all processes
+
+## Installation
+
+```bash
+pip install sysgraph
+```
+
+## Usage
+
+```bash
+# Start the web server (default: http://localhost:8000)
+sysgraph
+
+# Specify a custom port
+sysgraph --port 9000
+
+# Or run as a module
+python -m sysgraph
+```
+
+Open your browser to the displayed URL to see the interactive process graph.
+
+For full visibility into all processes and their connections, run with elevated privileges:
+
+```bash
+sudo sysgraph
+```
+
+## Docker
+
+```bash
+docker run --rm -it --pid=host --net=host gubenkoved/sysgraph
+```
+
+The `--pid=host` and `--net=host` flags allow the container to see host processes and network connections.
+
+## How It Works
+
+1. The **FastAPI backend** uses `psutil` and Linux-specific APIs (`/proc`, `ss`) to discover processes, pipes, Unix domain sockets, and network connections.
+2. It builds a graph of processes (nodes) and their IPC channels (edges).
+3. The **browser frontend** fetches the graph via `GET /api/graph` and renders it using [force-graph](https://github.com/vasturiano/force-graph) with d3 physics simulation.
+
+## License
+
+[MIT](LICENSE)

sysgraph-0.0.11/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+line-length = 79
+target-version = "py312"
+# Tune ruff rules as needed. Ruff supports many checks and can also format (`ruff format`).
+# See https://beta.ruff.rs/docs/configuration/ for config options.
+exclude = [".venv", "build", "dist", "__pycache__"]
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+use_parentheses = true
+ensure_newline_before_comments = true
+line_length = 88

sysgraph-0.0.11/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sysgraph-0.0.11/setup.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python
+"""A minimal, editable `setup.py` for the project.
+
+This file uses a modern setuptools pattern with a `src/` layout.
+Edit metadata (author, email, description, classifiers, dependencies) as needed.
+"""
+from pathlib import Path
+
+from setuptools import find_packages, setup
+
+HERE = Path(__file__).parent
+
+# Read long description from README if available
+README = (HERE / "README.md").read_text(encoding="utf-8") if (HERE / "README.md").exists() else ""
+
+# Try to read __version__ from package if present, otherwise fall back to 0.0.0
+def read_version():
+    version_file = HERE / "src" / "sysgraph" / "__init__.py"
+    if version_file.exists():
+        for line in version_file.read_text(encoding="utf-8").splitlines():
+            if line.strip().startswith("__version__"):
+                # supports formats: __version__ = '0.1.0' or "0.1.0"
+                delim = '"' if '"' in line else "'"
+                return line.split(delim)[1]
+    return "0.0.0"
+
+# Find packages in src/ (handles ordinary packages). If none found, try namespace packages.
+packages = find_packages(where="src")
+if not packages:
+    try:
+        from setuptools import find_namespace_packages
+
+        packages = find_namespace_packages(where="src")
+    except Exception:
+        packages = []
+
+setup(
+    name="sysgraph",
+    version=read_version(),
+    description="Visualizer for processes and their interconnections",
+    long_description=README,
+    long_description_content_type="text/markdown",
+    author="Eugene Gubenkov",
+    author_email="gubenkoved@gmail.com",
+    url="https://github.com/gubenkoved/sysgraph",
+    packages=packages,
+    package_dir={"": "src"},
+    include_package_data=True,
+    package_data={"sysgraph": ["dist/*", "dist/**/*"]},
+    zip_safe=False,
+    python_requires=">=3.12",
+    install_requires=[
+        "psutil",
+        "coloredlogs",
+        "fastapi>=0.95",
+        "uvicorn[standard]>=0.20",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: POSIX :: Linux",
+        "Topic :: System :: Monitoring",
+        "Topic :: System :: Systems Administration",
+        "Environment :: Web Environment",
+        "Framework :: FastAPI",
+        "Intended Audience :: Developers",
+        "Intended Audience :: System Administrators",
+    ],
+    keywords=[
+        "process",
+        "visualization",
+        "graph",
+        "ipc",
+        "system",
+        "monitoring",
+        "linux",
+        "procfs",
+    ],
+    entry_points={
+        "console_scripts": [
+            "sysgraph=sysgraph.app:main",
+        ],
+    },
+    license="MIT",
+    project_urls={
+        "Source": "https://github.com/gubenkoved/sysgraph",
+        "Issues": "https://github.com/gubenkoved/sysgraph/issues",
+    },
+)

sysgraph-0.0.11/src/sysgraph/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.11"

sysgraph-0.0.11/src/sysgraph/__main__.py

@@ -0,0 +1,3 @@
+from sysgraph.app import main
+
+main()

sysgraph-0.0.11/src/sysgraph/app.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+
+import logging
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+import coloredlogs
+from fastapi import FastAPI
+from fastapi.middleware.gzip import GZipMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from sysgraph.discovery import build_graph
+
+LOGGER = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app):
+    coloredlogs.install()
+    logging.info(f"init for process with PID {os.getpid()}")
+    yield
+    logging.info(f"shutdown for process with PID {os.getpid()}")
+
+
+app = FastAPI(title="sysgraph API", version="0.1.0", lifespan=lifespan)
+app.add_middleware(GZipMiddleware, minimum_size=500)
+
+# Vite build output — run scripts/build-ui.sh to produce it.
+_dist_dir = Path(__file__).parent / "dist"
+
+if not _dist_dir.is_dir():
+    LOGGER.warning(
+        "dist/ not found — frontend will not be served. "
+        "Run scripts/build-ui.sh to produce a production build."
+    )
+
+
+# Root route serves the SPA index — defined before the catch-all mount.
+@app.get("/", include_in_schema=False)
+def index():
+    index_path = _dist_dir / "index.html"
+    return FileResponse(index_path)
+
+
+class GraphNodeSchema(BaseModel):
+    id: str
+    type: str
+    properties: dict[str, Any]
+
+
+class GraphEdgeSchema(BaseModel):
+    id: str
+    source_id: str
+    target_id: str
+    type: str
+    properties: dict[str, Any]
+
+
+class GraphSchema(BaseModel):
+    nodes: list[GraphNodeSchema]
+    edges: list[GraphEdgeSchema]
+
+
+@app.get("/api/health")
+def health():
+    return {"status": "ok"}
+
+
+@app.get("/api/graph", response_model=GraphSchema)
+def get_graph() -> GraphSchema:
+    graph = build_graph()
+    graph_dict = graph.as_dict()
+
+    LOGGER.debug(graph_dict)
+
+    return GraphSchema(
+        nodes=[
+            GraphNodeSchema(
+                id=node["id"], type=node["type"], properties=node["properties"]
+            )
+            for node in graph_dict["nodes"]
+        ],
+        edges=[
+            GraphEdgeSchema(
+                id=edge["id"],
+                source_id=edge["source_id"],
+                target_id=edge["target_id"],
+                type=edge["type"],
+                properties=edge["properties"],
+            )
+            for edge in graph_dict["edges"]
+        ],
+    )
+
+
+# Serve built assets (JS/CSS bundles, Shoelace icons, etc.) from the same
+# directory that provides index.html.  This catch-all mount MUST come after
+# all explicit routes so that /api/* and / are matched first.
+if _dist_dir.is_dir():
+    app.mount(
+        "/", StaticFiles(directory=str(_dist_dir)), name="static"
+    )
+
+
+def main():
+    import argparse
+
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description="sysgraph server")
+    parser.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=int(os.environ.get("PORT", 8000)),
+        help="port to listen on (default: 8000, or PORT env var)",
+    )
+    args = parser.parse_args()
+
+    uvicorn.run(
+        "sysgraph.app:app",
+        host="0.0.0.0",
+        port=args.port,
+        reload=True,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()