sysgraph 0.0.17

Visualizer for processes and their interconnections

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)

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

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

pip install sysgraph

Usage

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

{
  "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 for a minimal example.

Live process graph (Linux only)

For full visibility into all processes and their connections, run with elevated privileges:

sudo sysgraph

Docker

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

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)

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

pytest src/sysgraph/tests/    # requires Linux /proc

Python linting

./scripts/lint.sh             # ruff check + ruff format + isort

License

MIT