Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added .github/screenshots/main.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
217 changes: 35 additions & 182 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,210 +1,63 @@
<div align="center">

![nethermind banner](docs/assets/banner.svg)

# nethermind

**AI-powered network switch management** — multi-vendor SSH and serial access, 50+ Jinja2 templates, an AI agent, and security auditing for mixed network fleets.
> AI-assisted management console for mixed-vendor network switches — SSH/serial config operations, Jinja2 templating, and security auditing for network engineers and MSPs running heterogeneous fleets.

<a href="https://github.com/OneByJorah/nethermind/stargazers"><img src="https://img.shields.io/github/stars/OneByJorah/nethermind?style=flat-square" alt="Stars"></a>
<a href="https://github.com/OneByJorah/nethermind/commits"><img src="https://img.shields.io/github/last-commit/OneByJorah/nethermind?style=flat-square" alt="Last commit"></a>
<img src="https://img.shields.io/github/license/OneByJorah/nethermind?style=flat-square" alt="License">
<img src="https://img.shields.io/badge/Python-3.12-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">
<img src="https://img.shields.io/badge/FastAPI-009688?style=flat-square&logo=fastapi&logoColor=white" alt="FastAPI">
<img src="https://img.shields.io/badge/Electron-desktop-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron desktop">
[![License](https://img.shields.io/github/license/OneByJorah/NetCore?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/NetCore)
[![Top Language](https://img.shields.io/github/languages/top/OneByJorah/NetCore?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/NetCore)
[![Stars](https://img.shields.io/github/stars/OneByJorah/NetCore?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/NetCore/stargazers)
[![Last Commit](https://img.shields.io/github/last-commit/OneByJorah/NetCore?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/NetCore/commits)

![nethermind screenshot](docs/assets/screenshot.png)
![nethermind dashboard](.github/screenshots/main.png)
[![CI](https://img.shields.io/github/actions/workflow/status/OneByJorah/NetCore/ci.yml?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/NetCore/actions)

## What This Is

</div>
Managing Cisco, Aruba, Juniper, and Arista gear usually means bouncing between SSH sessions and hand-edited configs. nethermind pulls that work into one app: it connects over SSH or a serial console, parses running-configs into structured data, renders new configs from templates, and logs every change behind an approval workflow. It is built for network engineers and MSPs who want an audit trail behind every change to a mixed-vendor fleet.

## Quick Start

```bash
git clone https://github.com/OneByJorah/nethermind.git
cd nethermind
git clone https://github.com/OneByJorah/NetCore.git && cd nethermind
cp .env.example .env # set OPENAI_API_KEY and SSH credentials
docker compose up -d
```

Open **http://localhost:3000** for the web UI, or **http://localhost:8000/docs** for the API docs.

## What This Is

nethermind is a full-stack platform for managing network switches and routers across vendors. It connects over SSH or a serial console, generates configs from templates, parses existing running-configs into structured data, runs AI-assisted operations, and enforces change discipline through an approval workflow. It is built for network engineers and MSPs who manage heterogeneous hardware and want an audit trail behind every change.

> [!NOTE]
> This project has been consolidated into **hermes-switch-manager**, which is now the actively developed repository. nethermind retains its desktop application and standalone CLI.
Open **http://localhost:3000** for the web UI, or **http://localhost:8000/docs** for the API.

## Features

- **Multi-vendor support** — Cisco IOS/XR/NX-OS, HP ArubaOS-Switch (ProCurve), Juniper JunOS, Arista EOS, and Linux.
- **SSH and serial console** — Netmiko for SSH, pyserial for RS-232/USB out-of-band access, plus Telnet deploy.
- **50+ Jinja2 templates** — built-in configuration templates for Aruba, Cisco, and generic devices.
- **Config parser** — turn existing running-config text into structured data for editing and re-rendering.
- **AI chat assistant** — OpenAI-powered agent with tool calling for natural-language operations.
- **IRIS-style workflow engine** — disciplined config change management with approval gates.
- **Security auditing** — CVE scanning, AAA checks, and CIS/NIST compliance findings.
- **Config diff and rollback** — compare versions and restore previous configs.
- **Device health monitoring** — CPU, memory, and interface status metrics.
- **Immutable audit trail** — every action logged with actor, target, and timestamp.
- **Desktop app** — an Electron package bundles backend and frontend into one installer.
- Pulls and backs up running configs over Netmiko SSH or a pyserial RS-232/USB console
- Parses existing running-config text into structured data for editing and re-rendering
- Ships 50+ Jinja2 config templates for Aruba, Cisco, and generic devices
- Diff and rollback for config versions, with SHA-tracked snapshots
- IRIS-style workflow engine gates risky changes behind human approval steps
- Security auditing: CVE scanning, AAA/ACL checks, CIS/NIST-oriented findings
- OpenAI-powered chat agent with tool calling for natural-language switch operations
- Device health metrics (CPU, memory, interface status) and a topology view
- Optional Electron desktop build bundling backend and frontend

## Architecture

```mermaid
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#0a0a09','primaryTextColor':'#FFB300','lineColor':'#FFB300'}}}%%
flowchart LR
UI["Next.js dashboard"] -->|REST| API["FastAPI backend"]
API --> SSH["Netmiko SSH / serial client"]
API --> TPL["Jinja2 template engine"]
API --> WF["Workflow engine + audit trail"]
API --> SEC["Security auditor"]
API --> DB["SQLite / PostgreSQL"]
SSH --> SW["Cisco / Aruba / Juniper / Arista / Linux"]
```
┌─────────────────────────────────────────────────┐
│ Frontend │
│ Next.js + TypeScript + Tailwind │
│ Dashboard │ Switches │ Configs │ Templates │
│ Chat │ Workflows │ Security │ Topology │
└──────────────────────┬──────────────────────────┘
│ REST API
┌──────────────────────▼──────────────────────────┐
│ Backend │
│ FastAPI + SQLAlchemy │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌────────┐ │
│ │ Netmiko SSH │ │ Serial/COM │ │ AI │ │
│ │ Client │ │ Client │ │ Agent │ │
│ └─────────────┘ └──────────────┘ └────────┘ │
│ ┌─────────────┐ ┌──────────────┐ ┌────────┐ │
│ │ Template │ │ Config │ │Workflow│ │
│ │ Engine │ │ Parser │ │ Engine │ │
│ └─────────────┘ └──────────────┘ └────────┘ │
│ ┌─────────────┐ ┌──────────────┐ ┌────────┐ │
│ │ Deployer │ │ Security │ │Audit │ │
│ │ │ │ Auditor │ │Trail │ │
│ └─────────────┘ └──────────────┘ └────────┘ │
└──────────────────────┬──────────────────────────┘
│
┌────────▼────────┐
│ SQLite / PG │
│ Database │
└─────────────────┘
```

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/switches/` | List all switches |
| `POST` | `/api/switches/` | Add a new switch |
| `POST` | `/api/switches/{id}/backup` | Pull running config via SSH |
| `GET` | `/api/configs/{id}` | Get a config backup |
| `POST` | `/api/config/parse` | Upload `.txt` config → structured JSON |
| `POST` | `/api/config/validate` | Validate a config before deploy |
| `POST` | `/api/config/render` | Render config to CLI text |
| `POST` | `/api/config/deploy` | Deploy config to a switch |
| `GET` | `/api/templates/` | List config templates |
| `POST` | `/api/templates/render` | Render a template with variables |
| `POST` | `/api/chat/` | Chat with the AI assistant |
| `GET` | `/api/workflows/` | List workflows |
| `GET` | `/api/security/` | Security findings |
| `GET` | `/api/system/serial-ports` | List serial ports |
| `GET` | `/health` | Health check |

## Configuration

Copy `.env.example` to `.env` and set real values:

| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_URL` | `sqlite:///./switches.db` | Database connection string |
| `OPENAI_API_KEY` | *(empty)* | OpenAI API key for the AI agent |
| `OPENAI_MODEL` | `gpt-4o` | Model used by the AI agent |
| `SSH_USERNAME` | `admin` | Default SSH username for switches |
| `SSH_PASSWORD` | *(empty)* | Default SSH password |
| `SECRET_KEY` | `change-me` | Application secret key |
| `LOG_LEVEL` | `INFO` | Log verbosity |
| `CORS_ORIGINS` | `http://localhost:3000,http://localhost:5173` | Allowed frontend origins |
| `NEXT_PUBLIC_API_URL` | `http://localhost:8000` | Frontend → backend API base URL |

> [!WARNING]
> SSH passwords are stored encrypted at rest, but the default `SECRET_KEY` and SQLite database are development defaults. Set a strong `SECRET_KEY`, uncomment the PostgreSQL service, and switch `DATABASE_URL` before production use.

## CLI

nethermind also ships a CLI for quick config operations:

```bash
cd scripts
python cli.py render --hostname MY-SW --mgmt-ip 192.168.1.10
python cli.py parse /path/to/running-config.txt
python cli.py deploy --transport telnet --host 192.168.1.1 --port 9023
```
## Stack

## Local Development

```bash
# Backend
cd backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Frontend
cd frontend
npm install
npm run dev
```

## Desktop App

An Electron package bundles the backend and frontend into a single app. Build with `desktop/build-win.bat` (Windows) or `desktop/build-linux.sh` (AppImage/deb/rpm), or run from source with `npx electron .` from `desktop/`.

## Use Cases

1. **Network engineers** — manage and back up a mixed-vendor fleet from one UI.
2. **MSPs** — standardize config generation and keep an audit trail per customer.
3. **Lab engineers** — pair with containerlab topologies for testing.
4. **Security teams** — run repeatable CVE/AAA/compliance audits.

## Tech Stack

FastAPI, SQLAlchemy, Netmiko, pyserial, Jinja2, OpenAI SDK, Next.js 16 (TypeScript), Tailwind CSS, Electron, SQLite/PostgreSQL, Docker Compose, uv/Ruff/pytest.

## Screenshots

| View | Preview |
|------|---------|
| Dashboard | ![Dashboard](docs/assets/screenshots/01-dashboard.png) |
| Switches | ![Switches](docs/assets/screenshots/02-switches.png) |
| Configs | ![Configs](docs/assets/screenshots/03-configs.png) |
| Templates | ![Templates](docs/assets/screenshots/04-templates.png) |
| AI chat | ![AI chat](docs/assets/screenshots/05-chat.png) |
| Workflows | ![Workflows](docs/assets/screenshots/06-workflows.png) |
| Security | ![Security](docs/assets/screenshots/07-security.png) |
| Topology | ![Topology](docs/assets/screenshots/08-topology.png) |
| Metrics | ![Metrics](docs/assets/screenshots/09-metrics.png) |
| API docs | ![API docs](docs/assets/screenshots/10-api-docs.png) |

## Project Structure

```
nethermind/
├── backend/ # FastAPI app (routers, services, models)
├── frontend/ # Next.js dashboard
├── desktop/ # Electron desktop packaging
├── scripts/ # cli.py + helper scripts
├── templates/ # Config templates
├── docker-compose.yml # Backend + frontend deployment
├── manifest.json # Repo metadata
├── pyproject.toml # Ruff + pytest config
├── install.sh / install.ps1
└── docs/ # Architecture + assets
```
FastAPI, SQLAlchemy, Netmiko, pyserial, Jinja2, OpenAI SDK, Next.js (TypeScript), Tailwind CSS, Electron, SQLite/PostgreSQL, Docker Compose.

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), then [open an issue](https://github.com/OneByJorah/nethermind/issues) or a pull request.
Contributions are welcome — read [CONTRIBUTING.md](CONTRIBUTING.md), then [open an issue](https://github.com/OneByJorah/NetCore/issues).

## License

MIT — see [LICENSE](LICENSE).

## Connect

- [jorahone.com](https://jorahone.com)
- [GitHub Org](https://github.com/OneByJorah)
- [info@jorahone.com](mailto:info@jorahone.com)
MIT — see LICENSE.
4 changes: 2 additions & 2 deletions frontend/next-env.d.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";
import "./.next/types/root-params.d.ts";
import "./.next/dev/types/routes.d.ts";
import "./.next/dev/types/root-params.d.ts";

// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
2 changes: 1 addition & 1 deletion manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "nethermind",
"description": "AI-powered network switch management — multi-vendor SSH + serial, Jinja2 templates, AI agent, and security auditing.",
"tagline": "AI-powered network switch management",
"repo_url": "https://github.com/OneByJorah/nethermind",
"repo_url": "https://github.com/OneByJorah/NetCore",
"what_it_does": "Full-stack web app for managing network switches: SSH/serial connections, 50+ config templates, AI chat assistant, workflow engine, security auditing, and config diff/rollback.",
"quickstart": "[ -f .env.example ] && cp .env.example .env\ndocker compose up -d",
"features": [
Expand Down
Loading