Oxidized NOC Console

A ready-to-run React + TypeScript and FastAPI web app for browsing Oxidized-backed network configuration archives.

What Is Included

• React, TypeScript, Tailwind CSS, React Query, Monaco Editor
• FastAPI API with typed device, config, search, diff, poll, user, and metrics endpoints
• Demo mode with ISP-style sample devices and configs
• GitPython-backed config archive reader when OXIDIZED_GIT_REPO points to a valid Oxidized Git repo
• Editable device metadata with local JSON persistence
• Derived alert/risk scoring for stale backups, failed backups, and slow polls
• Docker Compose with Nginx, FastAPI, PostgreSQL, Redis, Prometheus, and Grafana
• Header-based demo auth that maps LDAP/OIDC groups to readonly, engineer, and admin roles

Quick Start With Docker

docker compose up --build

Copy .env.example to .env first when you want to override defaults for Oxidized, LDAP/OIDC group mapping, Redis, or PostgreSQL.

Open:

• App: http://localhost:8080
• API docs: http://localhost:8000/api/docs
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000

Grafana default login is admin / admin.

Local Development

Backend:

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend:

cd frontend
npm install
npm run dev

Open http://localhost:5173. Vite proxies /api to http://127.0.0.1:8000.

Connecting Oxidized

Set OXIDIZED_GIT_REPO to the path of your Oxidized Git repository. In Docker, mount it into /oxidized-repo:

backend:
  volumes:
    - /srv/oxidized/configs.git:/oxidized-repo:ro

The app will keep using demo data until the configured path is a valid Git repository.

Device Metadata

Device inventory still comes from Oxidized or the demo seed data, but NOC-owned metadata can be edited in the UI:

• site
• owner
• criticality
• groups and tags
• business service
• maintenance window
• notes

Metadata is stored at METADATA_STORE_PATH, which defaults to data/device_metadata.json. Docker Compose mounts ./data/backend into the backend container so edits survive container restarts.

Auth Integration

The backend currently reads x-user and x-groups headers, which makes it easy to place Nginx, oauth2-proxy, Keycloak, or an LDAP-auth gateway in front of the API.

Group mapping is controlled by:

• ADMIN_GROUPS
• ENGINEER_GROUPS
• READONLY_GROUPS

Engineers and admins can trigger manual polls. Read-only users can browse dashboard, history, search, configs, and diffs.

API Surface

• GET /api/dashboard
• GET /api/devices
• GET /api/devices/{name}
• GET /api/devices/{name}/versions
• GET /api/devices/{name}/config
• GET /api/devices/{name}/diff
• PATCH /api/devices/{name}/metadata
• GET /api/search?q=bgp
• POST /api/devices/{name}/poll
• GET /api/alerts
• GET /api/audit
• GET /api/metrics