Metadata-Version: 2.4
Name: sysgraph
Version: 0.0.13
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)
