Skip to content

Commit efa433f

Browse files
clubandersonclubanderson
committed
Add KubeStellar Console security self-assessment
Add TAG-Security self-assessment for the KubeStellar Console project following the CNCF template. Includes actors, actions, security functions, secure development practices, and a Data Storage Summary documenting all persistence layers (backend SQLite, metrics history, browser caches, in-memory SSE cache). Signed-off-by: Andrew Anderson <andy@clubanderson.com>
1 parent 8271a4b commit efa433f

1 file changed

Lines changed: 181 additions & 0 deletions

File tree

‎projects/kubestellar/security-assessment/self-assessment.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Security Self-Assessment: KubeStellar Console
2+
3+
This document follows the [CNCF TAG-Security self-assessment template](https://github.com/cncf/tag-security/blob/main/assessments/guide/self-assessment.md).
4+
5+
## Table of Contents
6+
7+
- [Metadata](#metadata)
8+
- [Overview](#overview)
9+
- [Self-Assessment Use](#self-assessment-use)
10+
- [Security Functions and Features](#security-functions-and-features)
11+
- [Project Compliance](#project-compliance)
12+
- [Secure Development Practices](#secure-development-practices)
13+
- [Security Issue Resolution](#security-issue-resolution)
14+
- [Appendix](#appendix)
15+
- [Data Storage Summary](#data-storage-summary)
16+
17+
## Metadata
18+
19+
| | |
20+
|---|---|
21+
| **Software** | [KubeStellar Console](https://github.com/kubestellar/console) |
22+
| **Security Provider** | No — Console is a user-facing dashboard, not a security tool |
23+
| **Languages** | Go (backend), TypeScript/React (frontend) |
24+
| **SBOM** | Not currently generated; planned via GoReleaser in future releases |
25+
26+
## Overview
27+
28+
### Background
29+
30+
KubeStellar Console is an AI-powered multi-cluster Kubernetes dashboard that provides:
31+
32+
- **Cluster management** — Visual overview of resources across multiple Kubernetes clusters
33+
- **Guided install missions** — Step-by-step deployment of CNCF projects with pre-flight checks, validation, and rollback
34+
- **AI-assisted operations** — Natural language queries about cluster state via MCP (Model Context Protocol) bridge
35+
- **Real-time monitoring** — WebSocket-powered live event streaming from connected clusters
36+
37+
### Actors
38+
39+
| Actor | Description |
40+
|-------|-------------|
41+
| **Console User** | Authenticated (GitHub OAuth) or unauthenticated (demo mode) user accessing the web dashboard |
42+
| **kc-agent** | Local agent running on user's machine that bridges browser to local kubeconfig and MCP servers |
43+
| **AI Provider** | External service (Claude, OpenAI, or Gemini) that processes natural language queries via MCP |
44+
| **Kubernetes API** | Target clusters accessed via kubeconfig contexts |
45+
| **Netlify Functions** | Serverless backend for the hosted console.kubestellar.io deployment |
46+
47+
### Actions
48+
49+
| Action | Actor | Description |
50+
|--------|-------|-------------|
51+
| View cluster resources | Console User | Browse pods, deployments, services, events across connected clusters |
52+
| Execute mission | Console User | Run guided install/uninstall missions on target clusters |
53+
| AI chat query | Console User → AI Provider | Ask natural language questions about cluster state |
54+
| Connect clusters | kc-agent | Discover and tunnel local kubeconfig contexts to hosted Console |
55+
| Authenticate | Console User | Sign in via GitHub OAuth 2.0 |
56+
57+
### Goals
58+
59+
- Provide secure, authenticated access to Kubernetes cluster information
60+
- Never store or transmit Kubernetes credentials beyond the user's local machine
61+
- Enforce principle of least privilege — Console inherits the user's existing kubeconfig RBAC
62+
- Protect user sessions with short-lived JWT tokens
63+
- Prevent cross-site scripting (XSS) and other web application attacks
64+
65+
### Non-Goals
66+
67+
- Console does **not** manage Kubernetes RBAC policies — it inherits existing permissions
68+
- Console does **not** provide network security or service mesh capabilities
69+
- Console does **not** persistently store raw Kubernetes resource data on the server — pods, deployments, and services are fetched on-demand via the Kubernetes API. See [Data Storage Summary](#data-storage-summary) for details on what is persisted.
70+
- Console is **not** a secrets management tool
71+
72+
## Self-Assessment Use
73+
74+
This self-assessment is created by the KubeStellar Console maintainers to perform an internal analysis of the project's security. It is intended to assist TAG-Security in their joint assessment and to identify areas for improvement.
75+
76+
## Security Functions and Features
77+
78+
### Critical
79+
80+
| Component | Description |
81+
|-----------|-------------|
82+
| **GitHub OAuth 2.0** | Primary authentication mechanism; no passwords stored |
83+
| **JWT Session Tokens** | Short-lived tokens for session management; validated on every API request |
84+
| **kubeconfig isolation** | Kubernetes credentials never leave the user's machine; kc-agent proxies requests locally |
85+
| **HTTPS transport** | All production traffic encrypted via TLS (Netlify/Ingress termination) |
86+
| **WebSocket authentication** | WebSocket connections require valid JWT before data is transmitted |
87+
88+
### Security Relevant
89+
90+
| Component | Description |
91+
|-----------|-------------|
92+
| **Content Security Policy** | HTTP headers restrict script sources and frame embedding |
93+
| **CORS configuration** | API restricts cross-origin requests to known Console origins |
94+
| **Input sanitization** | User inputs (search queries, mission parameters) sanitized before rendering |
95+
| **Dependency scanning** | Dependabot, npm audit, and CodeQL identify vulnerable dependencies |
96+
| **Secret scanning** | GitHub repository-level secret scanning enabled (not yet integrated into CI/CD workflows) |
97+
98+
## Project Compliance
99+
100+
KubeStellar Console does not currently hold formal compliance certifications. The project follows:
101+
102+
- **CNCF Code of Conduct** — Adopted and enforced
103+
- **Apache License 2.0** — CNCF-compatible open-source license
104+
- **DCO (Developer Certificate of Origin)** — Required for all contributions
105+
- **OpenSSF Scorecard** — Automated weekly scoring
106+
107+
## Secure Development Practices
108+
109+
### Development Pipeline
110+
111+
| Practice | Implementation |
112+
|----------|---------------|
113+
| **Static Analysis (Go)** | CodeQL with extended security queries, gosec, nilaway |
114+
| **Static Analysis (TypeScript)** | CodeQL with extended queries, ESLint, TypeScript strict mode null checks |
115+
| **Dependency Management** | Dependabot (Go, npm, GitHub Actions), weekly automated updates |
116+
| **Container Scanning** | Planned — container image vulnerability scanning not yet integrated into CI/CD |
117+
| **Secret Detection** | GitHub repository-level secret scanning enabled; CI/CD integration planned |
118+
| **Code Review** | All changes require PR review; direct commits to main prohibited |
119+
| **Signed Commits** | DCO sign-off required on all commits |
120+
| **Branch Protection** | Main branch protected; CI must pass before merge |
121+
122+
### Communication Channels
123+
124+
| Channel | Address |
125+
|---------|---------|
126+
| **Internal (maintainers)** | [kubestellar-dev-private@googlegroups.com](mailto:kubestellar-dev-private@googlegroups.com) |
127+
| **Incoming (users)** | GitHub Issues, [#kubestellar-dev Slack](https://cloud-native.slack.com/channels/kubestellar-dev) |
128+
| **Security Announcements** | [kubestellar-security-announce@googlegroups.com](mailto:kubestellar-security-announce@googlegroups.com) |
129+
130+
## Security Issue Resolution
131+
132+
### Responsible Disclosure Process
133+
134+
Vulnerability reports should be sent to [kubestellar-security-announce@googlegroups.com](mailto:kubestellar-security-announce@googlegroups.com). See [SECURITY.md](https://github.com/kubestellar/console/blob/main/SECURITY.md) for full details.
135+
136+
### Response Timeline
137+
138+
| Step | Timeline |
139+
|------|----------|
140+
| **Acknowledgment** | Within 3 working days |
141+
| **Initial Assessment** | Within 5 working days |
142+
| **Patch Development** | Critical: 72 hours; High: 7 days |
143+
| **Public Disclosure** | After patch is available, coordinated with reporter |
144+
145+
### Incident Response
146+
147+
The security response team (listed in [SECURITY_CONTACTS](https://github.com/kubestellar/console/blob/main/SECURITY_CONTACTS)) triages all reports. Critical vulnerabilities trigger an immediate patch release; non-critical issues are addressed in the next scheduled release.
148+
149+
## Appendix
150+
151+
### Data Storage Summary
152+
153+
The following table details all data persisted by KubeStellar Console, both server-side and client-side:
154+
155+
| Storage | Type | What is Stored | Location | Retention |
156+
|---------|------|----------------|----------|-----------|
157+
| **Backend SQLite** | Relational DB | User accounts, dashboard layouts, card configurations, GPU utilization snapshots, revoked JWT tokens, user analytics events, feature requests | Server: `/data/console.db` | Indefinite |
158+
| **Metrics History** | JSON file | Rolling cluster metrics (CPU/memory %, node counts, pod issues, GPU allocation per node) | kc-agent host: `~/.kc/metrics_history.json` | 7 days |
159+
| **Frontend SQLite (OPFS)** | Browser DB | Cached Kubernetes resource data (pods, deployments, services) for performance | Browser OPFS: `/kc-cache.sqlite3` | Until browser cache cleared |
160+
| **Frontend IndexedDB** | Browser DB | Same as OPFS (fallback when OPFS unavailable) | Browser IndexedDB: `kc_cache` | Until browser cache cleared |
161+
| **localStorage** | Browser KV | User preferences, theme, AI settings, UI state | Browser localStorage | Until browser data cleared |
162+
| **In-memory SSE cache** | Process memory | Short-lived Kubernetes API responses | Server memory | 15-second TTL; lost on restart |
163+
164+
**Key points:**
165+
166+
- Raw Kubernetes resource data (pods, deployments, services) is **not** stored server-side — it is fetched on-demand and cached only in browser storage and a 15-second in-memory server cache.
167+
- Kubernetes **credentials** never leave the user's machine — the kc-agent proxies requests locally.
168+
- The backend SQLite database stores user preferences and dashboard configuration, plus GPU utilization snapshots for historical trend analysis.
169+
- The kc-agent's metrics history file (`~/.kc/metrics_history.json`) stores 7 days of aggregated cluster health metrics on the user's local machine for AI-assisted trend analysis.
170+
171+
### Known Issues and Areas for Improvement
172+
173+
1. **AI provider data flow** — Queries sent to external AI providers (Claude, OpenAI, Gemini) may include cluster resource names and metadata. Users should be aware that AI chat queries are processed by third-party services.
174+
2. **Demo mode** — Unauthenticated demo mode uses synthetic data only; no cluster access is possible without authentication.
175+
3. **kc-agent trust model** — The kc-agent runs with the user's local permissions. A compromised kc-agent could access any cluster the user has kubeconfig access to. This is mitigated by the agent running locally (not as a network service).
176+
177+
### Related Security Documentation
178+
179+
- [SECURITY.md](https://github.com/kubestellar/console/blob/main/SECURITY.md) — Vulnerability reporting process
180+
- [SECURITY_CONTACTS](https://github.com/kubestellar/console/blob/main/SECURITY_CONTACTS) — Security response team
181+
- [HARDCODED_URLS.md](https://github.com/kubestellar/console/blob/main/docs/security/HARDCODED_URLS.md) — Explanation of intentional hardcoded URLs

0 commit comments

Comments
 (0)