Metadata-Version: 2.4
Name: sysgraph
Version: 0.0.17
Summary: Visualizer for processes and their interconnections
Author-email: Eugene Gubenkov <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: license-file

# sysgraph

An interactive force-directed **network graph visualizer** for the browser — with two modes:

- **Import any graph** — load any JSON graph (nodes + edges) to explore and visualize it interactively, no Linux or special privileges required
- **Live process graph** — discover running OS processes and their inter-process communication channels (pipes, Unix domain sockets, TCP/UDP connections) in real time (Linux only)

![Python](https://img.shields.io/badge/python-%3E%3D3.12-blue)
![License](https://img.shields.io/badge/license-MIT-green)

## Features

- **Import any graph** — load a JSON file with nodes and edges to visualize any network, social graph, dependency tree, or dataset
- **Export/Import** — save and reload graph snapshots as JSON; use the sample at [`data/simplest-graph.json`](data/simplest-graph.json) as a format reference
- **Interactive graph** — force-directed graph rendered in the browser with zoom, pan, drag, and search
- **Fuzzy search** — find nodes by any property
- **Adjacency filtering** — right-click a node to show only its neighbors
- **Configurable** — tune d3 force parameters, colors, and type filters via the settings panel
- **Process discovery** *(Linux only)* — enumerates running OS processes and their parent-child relationships
- **IPC visualization** *(Linux only)* — discovers pipes, Unix domain sockets, and TCP/UDP connections between processes
- **Real-time** *(Linux only)* — fetch the latest process graph on demand via the web UI

## Demo

[Demo](https://github.com/user-attachments/assets/7d19daca-042c-43f1-bedd-4d74344e1e89)

## Requirements

- **Python ≥ 3.12**
- **Linux** is required only for live process-graph discovery (relies on `/proc` and `ss`); importing and visualizing your own graphs works on any platform
- Root/sudo recommended for full process visibility (Linux only)

## 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.

### Visualize your own graph

Use the **Import** button in the UI to load any JSON file in the following format:

```json
{
  "nodes": [
    {"id": "1", "type": "person", "properties": {"name": "Alice"}},
    {"id": "2", "type": "person", "properties": {"name": "Bob"}}
  ],
  "edges": [
    {"source_id": "1", "target_id": "2", "type": "knows", "properties": {}}
  ]
}
```

See [`data/simplest-graph.json`](data/simplest-graph.json) for a minimal example.

### Live process graph (Linux only)

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 **browser frontend** renders interactive force-directed graphs using [force-graph](https://github.com/vasturiano/force-graph) with d3 physics simulation.
2. Graphs can be **imported from JSON** directly in the browser, or fetched live from the backend.
3. The **FastAPI backend** uses `psutil` and Linux-specific APIs (`/proc`, `ss`) to discover processes, pipes, Unix domain sockets, and network connections, building a graph served via `GET /api/graph`.

## Development

### Prerequisites
- Python ≥ 3.12, Linux, Docker
- Node.js 22 runs inside Docker; no host installation required

### Backend
```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e . && pip install -r requirements-dev.in
python src/sysgraph/app.py   # → http://localhost:8000
```

### Frontend (TypeScript + Vite)
```bash
./scripts/build-ui.sh         # production build → src/sysgraph/dist/
./scripts/dev-ui.sh           # Vite dev server with HMR on :5173
./scripts/typecheck-ui.sh     # TypeScript type checking
./scripts/lint-ui.sh          # Biome linter (pass --fix to auto-fix)
```

### Tests
```bash
pytest src/sysgraph/tests/    # requires Linux /proc
```

### Python linting
```bash
./scripts/lint.sh             # ruff check + ruff format + isort
```

## License

[MIT](LICENSE)
