📝 docs(security): add mermaid diagrams to SECURITY-MODEL.md#8206
Merged
clubanderson merged 1 commit intomainfrom Apr 15, 2026
Merged
📝 docs(security): add mermaid diagrams to SECURITY-MODEL.md#8206clubanderson merged 1 commit intomainfrom
clubanderson merged 1 commit intomainfrom
Conversation
Enhances the merged security doc (#8203) with four mermaid diagrams that make the architecture and posture choices visible at a glance: 1. **Component diagram** — replaces the ASCII-art architecture block with a richer mermaid flowchart that groups components by trust boundary (user machine / console deployment / managed clusters / AI providers), uses solid vs dashed arrows to distinguish mandatory vs optional flows, and color-codes the boundaries. 2. **Auth + transport defense-in-depth** — shows the four layers that gate traffic into kc-agent (bind check on 127.0.0.1, CORS allow-list, DNS-rebinding guard, optional KC_AGENT_TOKEN) so readers can see why loopback alone isn't the whole story and when they should set the token. 3. **Posture comparison** — stacks the three network postures (fully online / restricted egress / fully air-gapped) side by side with red dotted arrows marking the flows explicitly blocked at egress in each posture. 4. **Local-LLM provider-slot routing** — shows how setting GROQ_BASE_URL (or OPENROUTER_BASE_URL / OPEN_WEBUI_URL) redirects the provider slot to Ollama, vLLM, LM Studio, or a corporate gateway without touching the console code. Also adds a short "Local LLM as a security posture" subsection framing the override as the correct choice for air-gapped and high-sensitivity environments — not a feature gap. This is deliberately scoped to the security doc; broader local-LLM support work lives elsewhere. No runtime behavior changes. Documentation only. Signed-off-by: Andrew Anderson <[email protected]>
kubestellar-prow
Bot
added
the
dco-signoff: yes
Contributor
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
✅ Deploy Preview for kubestellarconsole canceled.
|
kubestellar-prow
Bot
added
the
size/L
Contributor
|
👋 Hey @clubanderson — thanks for opening this PR!
This is an automated message. |
Contributor
There was a problem hiding this comment.
Pull request overview
Enhances the security model documentation by replacing the ASCII architecture depiction with Mermaid diagrams that visualize trust boundaries, request flows, and deployment postures.
Changes:
- Replaces the component ASCII art with a Mermaid component/trust-boundary diagram.
- Adds Mermaid diagrams for kc-agent defense-in-depth and for the three egress postures.
- Adds a Mermaid diagram explaining local-LLM routing via overridable provider base URLs, plus supporting explanatory text.
| A_KA[kc-agent] --> A_K8S[Kubernetes] | ||
| A_KA --> A_AI[Public AI provider] | ||
| A_GB[Go backend] --> A_GH[GitHub OAuth] | ||
| A_GB --> A_UP[Update checks] |
Comment on lines
+257
to
+262
| KA[kc-agent] -->|provider: groq<br/>GROQ_BASE_URL=...| SLOT[Groq provider slot<br/>pkg/agent/provider_groq.go] | ||
| SLOT -.default.-> GRQ[api.groq.com/v1] | ||
| SLOT -->|override| OLLA[Ollama<br/>localhost:11434/v1] | ||
| SLOT -->|override| VLLM[vLLM<br/>local:8000/v1] | ||
| SLOT -->|override| LM[LM Studio<br/>local:1234/v1] | ||
| SLOT -->|override| GW[Corporate LLM gateway<br/>llm.internal/v1] |
| │ console runs in │ | ||
| └──────────────────┘ | ||
| ``` | ||
| The three-process architecture: a browser, a Go backend (serves UI, bootstrap-only identity), and kc-agent running on the user's own laptop (identity is the user's kubeconfig). Every cluster mutation flows through kc-agent. |
| end | ||
|
|
||
| B -->|HTTP/WS :8080<br/>serves UI, OAuth| GB | ||
| B -->|HTTP/WS :8585<br/>all cluster ops| KA |
Comment on lines
+128
to
+131
| BIND[Bind check<br/>127.0.0.1 only<br/>server.go:578] | ||
| CORS[Origin allow-list<br/>strict match<br/>server.go:92-100] | ||
| REB[DNS-rebinding guard<br/>matchOrigin<br/>server.go:799-822] | ||
| TOK["Token check<br/>(optional, off by default)<br/>server.go:214-218"] |
This was referenced Apr 15, 2026
Contributor
|
Thank you for your contribution! Your PR has been merged. Check out what's new:
Stay connected: Slack #kubestellar-dev | Multi-Cluster Survey |
Contributor
|
Post-merge build verification passed ✅ Both Go and frontend builds compiled successfully against merge commit |
clubanderson
added a commit
that referenced
this pull request
Apr 15, 2026
The previous 'simplification' removed all the descriptive labels and
trust-boundary classDef coloring that made the diagrams useful. The
real root cause of GitHub's last-character truncation is that mermaid
v9.2+ defaults to HTML foreignObject elements for label rendering,
which GitHub's rendering pipeline mis-measures.
The official upstream workaround is the init directive
%%{init: {'flowchart': {'htmlLabels': false, 'useMaxWidth': false}}}%%
which forces SVG <text> elements instead. SVG text is sized correctly
by the renderer in all environments.
This commit:
- Reverts SECURITY-MODEL.md to the rich content from #8206 (full
detailed labels, classDef trust-boundary coloring, descriptive
edge labels, complete defense-in-depth structure)
- Adds the htmlLabels:false init directive to all 4 mermaid blocks
- No content changes other than the init directive
Refs:
- mermaid-js/mermaid#7354
- mermaid-js/mermaid#3525
Signed-off-by: Andrew Anderson <[email protected]>
clubanderson
added a commit
that referenced
this pull request
Apr 15, 2026
…DME (#8207) Fixes #8207 Addresses all 6 Copilot review comments from PR #8203 (security docs bundle). Verified each claim against source before applying: - Verified InitializeProviders (pkg/agent/registry.go:283) registers only CLI-based tool agents and explicitly excludes API-key HTTP providers (claude/openai/gemini/groq/openrouter/open-webui). - Verified update_checker.go lives in pkg/agent/ (local kc-agent), not in the Go backend server pod. - Verified DEV_MODE is read in cmd/kc-agent/main.go:18 while KC_DEV_MODE=1 is only used in pkg/agent/server_http.go:2202 for the backend-driven agent restart path. Changes: 1. README.md (finding #1): The "security model" paragraph no longer claims users can point an OpenAI-compatible local LLM at kc-agent via GROQ_BASE_URL / OPENROUTER_BASE_URL / OPEN_WEBUI_URL today. Reframed as a planned follow-up; currently supported path is the CLI-based agents. 2. SECURITY-MODEL.md §1 data flow (finding #2): Replaced the single-sentence "Key consequence" block with the two-path distinction (CLI tool agents vs direct HTTP providers). Notes that CLI agents can exfiltrate cluster data indirectly via kubectl/helm tool output; direct HTTP providers are not registered at runtime today. 3. SECURITY-MODEL.md §2 Posture B (finding #3): Rewrote the restricted-egress section to match runtime reality. AI gating is by registered CLI agent availability, not by API-key env vars. Setting *_API_KEY does not by itself enable AI. Settings → API Keys modal documented as non-operative. 4. SECURITY-MODEL.md §1 "leaves the cluster" (finding #5): Corrected the update_checker.go reference. The local kc-agent (not the backend pod) performs any GitHub update polling. In-cluster backend deployments do not poll GitHub from the server pod. 5. SECURITY-MODEL.md §3 Local/Self-hosted LLMs (finding #4): Added a prominent "current registration status" subsection stating that Groq/OpenRouter/Open WebUI provider implementations exist but are NOT registered by InitializeProviders. Relabeled the Ollama / vLLM / LM Studio / internal-gateway recipes as "planned follow-up" (not operative today). Base-URL env vars noted as "parsed, not wired". Retained the mermaid diagrams from PR #8206 and framed them as the intended direction. 6. SECURITY-MODEL.md §4 env var cheat sheet (finding #6): Split the KC_DEV_MODE row into two entries — DEV_MODE (general kc-agent dev/logging toggle, read in cmd/kc-agent/main.go) and KC_DEV_MODE (backend-driven restart/dev path in pkg/agent/server_http.go) — so operators don't set the wrong variable. Docs-only change. web build + lint pass. Signed-off-by: Andy Anderson <[email protected]>
clubanderson
added a commit
that referenced
this pull request
Apr 15, 2026
…DME (#8207) (#8223) Fixes #8207 Addresses all 6 Copilot review comments from PR #8203 (security docs bundle). Verified each claim against source before applying: - Verified InitializeProviders (pkg/agent/registry.go:283) registers only CLI-based tool agents and explicitly excludes API-key HTTP providers (claude/openai/gemini/groq/openrouter/open-webui). - Verified update_checker.go lives in pkg/agent/ (local kc-agent), not in the Go backend server pod. - Verified DEV_MODE is read in cmd/kc-agent/main.go:18 while KC_DEV_MODE=1 is only used in pkg/agent/server_http.go:2202 for the backend-driven agent restart path. Changes: 1. README.md (finding #1): The "security model" paragraph no longer claims users can point an OpenAI-compatible local LLM at kc-agent via GROQ_BASE_URL / OPENROUTER_BASE_URL / OPEN_WEBUI_URL today. Reframed as a planned follow-up; currently supported path is the CLI-based agents. 2. SECURITY-MODEL.md §1 data flow (finding #2): Replaced the single-sentence "Key consequence" block with the two-path distinction (CLI tool agents vs direct HTTP providers). Notes that CLI agents can exfiltrate cluster data indirectly via kubectl/helm tool output; direct HTTP providers are not registered at runtime today. 3. SECURITY-MODEL.md §2 Posture B (finding #3): Rewrote the restricted-egress section to match runtime reality. AI gating is by registered CLI agent availability, not by API-key env vars. Setting *_API_KEY does not by itself enable AI. Settings → API Keys modal documented as non-operative. 4. SECURITY-MODEL.md §1 "leaves the cluster" (finding #5): Corrected the update_checker.go reference. The local kc-agent (not the backend pod) performs any GitHub update polling. In-cluster backend deployments do not poll GitHub from the server pod. 5. SECURITY-MODEL.md §3 Local/Self-hosted LLMs (finding #4): Added a prominent "current registration status" subsection stating that Groq/OpenRouter/Open WebUI provider implementations exist but are NOT registered by InitializeProviders. Relabeled the Ollama / vLLM / LM Studio / internal-gateway recipes as "planned follow-up" (not operative today). Base-URL env vars noted as "parsed, not wired". Retained the mermaid diagrams from PR #8206 and framed them as the intended direction. 6. SECURITY-MODEL.md §4 env var cheat sheet (finding #6): Split the KC_DEV_MODE row into two entries — DEV_MODE (general kc-agent dev/logging toggle, read in cmd/kc-agent/main.go) and KC_DEV_MODE (backend-driven restart/dev path in pkg/agent/server_http.go) — so operators don't set the wrong variable. Docs-only change. web build + lint pass. Signed-off-by: Andy Anderson <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #8203 — enhances the merged `docs/security/SECURITY-MODEL.md` with four mermaid diagrams that make the architecture and posture choices visible at a glance.
What's added
127.0.0.1bind check, CORS allow-list, DNS-rebinding guard (`matchOrigin`), and the optional `KC_AGENT_TOKEN`. Readers can see why loopback alone isn't the whole story and when they should set the token.Also adds a short "Local LLM as a security posture" subsection framing the override as the correct choice for air-gapped / regulated environments — not a feature gap. Deliberately scoped: broader local-LLM support work is tracked separately.
Scope
Test plan