ISE Flow Assistant

A RAG chatbot that explains Cisco ISE and RADIUS/AAA flows — and draws them.

---

Ask a plain-English question about Cisco ISE authentication/authorization or the RADIUS protocol — "walk me through 802.1X wired auth", "explain CoA and ANC quarantine", "how does RADIUS accounting work" — and get back an answer grounded in curated Cisco ISE and FreeRADIUS documentation, plus a live-rendered Mermaid sequence diagram of the flow.

Nothing is answered from the model's general knowledge alone: every response is retrieved from a local vector index built over hand-authored ISE flow guides and real docs pulled from the CiscoISE and FreeRADIUS GitHub orgs, with sources cited on every answer.

sequenceDiagram
    participant Endpoint
    participant NAD as NAD (switch / WLC)
    participant ISE as ISE / RADIUS
    Endpoint->>NAD: Connect
    NAD->>ISE: RADIUS Access-Request
    ISE->>NAD: RADIUS Access-Challenge
    NAD->>Endpoint: EAP-Request
    Endpoint-->>NAD: EAP-Response
    NAD->>ISE: RADIUS Access-Request
    ISE->>NAD: RADIUS Access-Accept
    NAD->>Endpoint: Policy enforced

Loading

(This is exactly the kind of diagram the assistant generates on demand — not a static image.)

Features

• Grounded Q&A — answers are built only from retrieved context; if the knowledge base doesn't cover a question, the model says so instead of guessing.
• Flow diagrams on demand — structured OpenAI output returns { answer, mermaid, sources } in one call; the frontend renders the Mermaid diagram inline.
• Curated, cited sources — every answer lists exactly which docs it drew from.
• Knowledge Base page — browse everything currently ingested (title, source path, chunk count, link back to GitHub) at /knowledge.
• Example prompts — one-click starter questions for every supported flow, each with its own icon.
• Light, responsive UI — routed React app (Chat + Knowledge Base), widened for landscape screens, with an animated AAA-flow hero banner and a subtle security-themed background — all original inline SVG, no external image/GIF assets.

What it covers

Domain	Flows
Cisco ISE	802.1X (wired/wireless), MAC Authentication Bypass (MAB), TACACS+ device administration, TrustSec SGT propagation, pxGrid, Change of Authorization (CoA) & Adaptive Network Control (ANC) quarantine
RADIUS protocol	AAA model overview, authentication, authorization, accounting, session processing, PAP/CHAP/EAP comparison

Architecture

graph LR
    UI["React UI<br/>(Chat + Knowledge Base)"] -->|POST /api/chat<br/>GET /api/sources| API["FastAPI backend"]
    API --> RAG["RAG retrieval<br/>(Chroma, local)"]
    API --> LLM["OpenAI<br/>chat + embeddings"]
    RAG --> KB["Knowledge docs<br/>(hand-authored)"]
    RAG --> GH["Curated GitHub docs<br/>(CiscoISE, FreeRADIUS)"]

Loading

1. The frontend sends a question to POST /api/chat.
2. The backend embeds the question, retrieves the top matching chunks from the local Chroma index, and asks OpenAI to answer using only that context.
3. OpenAI returns structured JSON: an answer, an optional Mermaid diagram, and the sources used.
4. The frontend renders the answer, the diagram, and source pills.

Knowledge sources

18 sources, ~82 chunks (run uv run python -m genai_app.rag.ingest to rebuild after any change):

ISE Flow Guides — 6 hand-authored docs, grounded in Cisco's public ISE documentation

• 802.1X Authentication (Wired and Wireless)
• MAC Authentication Bypass (MAB)
• TACACS+ Device Administration
• TrustSec Security Group Tag (SGT) Propagation
• pxGrid (Platform Exchange Grid)
• Change of Authorization (CoA) and Adaptive Network Control (ANC) Quarantine

Cisco ISE SDK & Automation — 3 README docs pulled live from GitHub

• CiscoISE/ciscoisesdk — Python SDK for the ISE API
• CiscoISE/ansible-ise — Ansible collection for ISE
• CiscoISE/terraform-provider-ciscoise — Terraform provider

FreeRADIUS Protocol Docs — 9 docs pulled live from GitHub

• FreeRADIUS/freeradius-server — README plus Antora concept docs: AAA overview, authentication, authorization, accounting, sessions, request processing, auth protocols (PAP/CHAP/EAP)
• mcnewton/freeradius-server — README (a personal fork, 382 commits behind upstream; included because it was explicitly requested, content overlaps heavily with upstream)

netascode (Cisco ACI/NX-OS Terraform) and cisco-system-traffic-generator (TRex) were evaluated and intentionally excluded — neither has ISE- or RADIUS-specific content.

Project structure

genai_app/
├── src/genai_app/
│   ├── knowledge/        # hand-authored ISE flow markdown docs
│   ├── rag/               # sources.py (curated list), ingest.py, store.py (Chroma)
│   ├── llm/                # system prompt + OpenAI client (structured output)
│   ├── api/                # chat.py (POST /api/chat), knowledge.py (GET /api/sources)
│   ├── main.py             # FastAPI app
│   └── config.py           # pydantic-settings (.env)
└── frontend/
    └── src/
        ├── pages/           # ChatPage, KnowledgeBasePage
        ├── components/      # Layout, ChatWindow, MessageBubble, MermaidDiagram,
        │                     PromptChips, HeroBanner
        └── api/client.ts    # fetch wrappers for the backend

Getting started

Prerequisites: Python 3.12+, uv, Node.js 18+, and an OpenAI API key.

Backend

uv sync
cp .env.example .env                    # fill in OPENAI_API_KEY
uv run python -m genai_app.rag.ingest    # build the local Chroma index
uv run genai-app                        # http://localhost:8000

Re-run the ingest step any time a knowledge doc or source changes.

Frontend

cd frontend
npm install
npm run dev                              # http://localhost:5173

API

Method	Path	Description
POST	/api/chat	{ message } → { answer, mermaid, sources }
GET	/api/sources	Ingested sources grouped by category, with per-source chunk counts
GET	/health	Liveness check