Add CodeQL workflow for code analysis

This is a new CodeQL workflow file for analyzing code in the repository.

.claude-plugin/marketplace.json

@@ -1,5 +1,6 @@
 {
   "name": "kubeshark",
+  "owner": { "name": "kubeshark" },
   "description": "Kubeshark network observability skills for Kubernetes",
   "plugins": [
     {

.github/workflows/codeql.yml

@@ -0,0 +1,101 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+  schedule:
+    - cron: '16 11 * * 5'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: go
+          build-mode: autobuild
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

cmd/console.go

@@ -22,9 +22,15 @@ import (
 
 var consoleCmd = &cobra.Command{
 	Use:   "console",
-	Short: "Stream the scripting console logs into shell",
+	Short: "Stream the scripting console logs into shell (temporarily non-functional — under refactoring after hub API changes)",
+	Long: `Stream the scripting console logs into shell.
+
+NOTE: This command is currently non-functional and under refactoring. The hub
+moved scripting-console log streaming off the /scripts/logs WebSocket onto a
+Connect-RPC streaming service, and this client has not yet been updated to use
+it, so no logs will stream until the migration lands.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
-		runConsole()
+		log.Warn().Msg(fmt.Sprintf(utils.Yellow, "The 'console' command is temporarily non-functional and under refactoring: the hub moved scripting-console log streaming off the /scripts/logs WebSocket onto a Connect-RPC service, and this client has not yet been updated. No logs will stream, so the command exits without doing anything."))
 		return nil
 	},
 }
@@ -42,6 +48,7 @@ func init() {
 	consoleCmd.Flags().StringP(configStructs.ReleaseNamespaceLabel, "s", defaultTapConfig.Release.Namespace, "Release namespace of Kubeshark")
 }
 
+//nolint:unused // retained for the in-progress console refactoring; re-wired once the Connect-RPC client lands
 func runConsoleWithoutProxy() {
 	log.Info().Msg("Starting scripting console ...")
 	time.Sleep(5 * time.Second)
@@ -138,7 +145,10 @@ func runConsoleWithoutProxy() {
 	}
 }
 
+//nolint:unused // retained for the in-progress console refactoring; re-wired once the Connect-RPC client lands
 func runConsole() {
+	log.Warn().Msg(fmt.Sprintf(utils.Yellow, "The 'console' command is temporarily non-functional and under refactoring: the hub moved scripting-console log streaming off the /scripts/logs WebSocket onto a Connect-RPC service, and this client has not yet been updated. No logs will stream."))
+
 	go runConsoleWithoutProxy()
 
 	// Create interrupt channel and setup signal handling once

cmd/mcp.go

@@ -10,6 +10,7 @@ var mcpKubeconfig string
 var mcpListTools bool
 var mcpConfig bool
 var mcpAllowDestructive bool
+var mcpToken string
 
 var mcpCmd = &cobra.Command{
 	Use:   "mcp",
@@ -118,6 +119,7 @@ func init() {
 	rootCmd.AddCommand(mcpCmd)
 
 	mcpCmd.Flags().StringVar(&mcpURL, "url", "", "Direct URL to Kubeshark (e.g., https://kubeshark.example.com). When set, connects directly without kubectl/proxy and disables start/stop tools.")
+	mcpCmd.Flags().StringVar(&mcpToken, "token", "", "ServiceAccount/bearer token for a gated Hub in --url mode (e.g. from 'kubectl create token kubeshark-cli --audience kubeshark-hub'); also read from KUBESHARK_HUB_TOKEN. Ignored without --url, where the token is minted and auto-renewed from kube access.")
 	mcpCmd.Flags().StringVar(&mcpKubeconfig, "kubeconfig", "", "Path to kubeconfig file (e.g., /Users/me/.kube/config)")
 	mcpCmd.Flags().BoolVar(&mcpListTools, "list-tools", false, "List available MCP tools and exit")
 	mcpCmd.Flags().BoolVar(&mcpConfig, "mcp-config", false, "Print MCP client configuration JSON and exit")

cmd/mcpRunner.go

@@ -159,34 +159,47 @@ type mcpServer struct {
 	cachedHubMCP       *hubMCPResponse // Cached tools/prompts from Hub
 	cachedAt           time.Time       // When the cache was populated
 	hubMCPMu           sync.Mutex
-	saToken            string // ServiceAccount token for a gated Hub (phase 2a); empty falls back to License-Key
+	tokenSource        func() string // hub SA token source; proxy mode auto-renews, URL mode is the static --token. nil → License-Key
 }
 
 const hubMCPCacheTTL = 5 * time.Minute
 
+// hubTokenSource builds the SA-token source used to authenticate to a gated
+// Hub. Proxy mode (kube access) returns an auto-renewing minter so long-lived
+// processes keep working past the ~1h token TTL; URL mode returns the static
+// --token / KUBESHARK_HUB_TOKEN (it can't mint without kube access). Returns
+// nil when no token is available, so callers fall back to the License-Key.
+func hubTokenSource(urlMode bool) func() string {
+	if urlMode {
+		staticTok := mcpToken
+		if staticTok == "" {
+			staticTok = os.Getenv("KUBESHARK_HUB_TOKEN")
+		}
+		if staticTok == "" {
+			return nil
+		}
+		return func() string { return staticTok }
+	}
+	provider, err := getKubernetesProviderForCli(true, true)
+	if err != nil {
+		return nil
+	}
+	return kubernetes.NewHubTokenRenewer(provider, config.Config.Tap.Release.Namespace).Token
+}
+
 func runMCPWithConfig(setFlags []string, directURL string, allowDestructive bool) {
 	// Disable zerolog output to stderr (MCP uses stdio)
 	zerolog.SetGlobalLevel(zerolog.Disabled)
 
 	urlMode := directURL != ""
 
-	// Best-effort: mint a scoped ServiceAccount token so the CLI authenticates
-	// to a gated Hub as kubeshark-cli. Falls back to License-Key when minting
-	// isn't possible (no kube access in --url mode, SA missing, or no RBAC).
-	saToken := ""
-	if !urlMode {
-		if provider, err := getKubernetesProviderForCli(true, true); err == nil {
-			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-			if tok, terr := provider.MintHubToken(ctx, config.Config.Tap.Release.Namespace); terr == nil {
-				saToken = tok
-			}
-			cancel()
-		}
-	}
+	// Hub SA-token source: auto-renewing in proxy mode, the static --token in
+	// URL mode; nil falls back to the License-Key. See hubTokenSource.
+	tokenSource := hubTokenSource(urlMode)
 
 	server := &mcpServer{
-		httpClient:       utils.NewHubHTTPClientWithToken(30*time.Second, saToken, config.Config.License),
-		saToken:          saToken,
+		httpClient:       utils.NewHubHTTPClientWithTokenSource(30*time.Second, tokenSource, config.Config.License),
+		tokenSource:      tokenSource,
 		stdin:            os.Stdin,
 		stdout:           os.Stdout,
 		setFlags:         setFlags,
@@ -214,7 +227,7 @@ func (s *mcpServer) validateDirectURL() error {
 	s.directURL = urlStr
 
 	// Use a short timeout for validation
-	client := utils.NewHubHTTPClientWithToken(10*time.Second, s.saToken, config.Config.License)
+	client := utils.NewHubHTTPClientWithTokenSource(10*time.Second, s.tokenSource, config.Config.License)
 
 	// Try to reach the MCP API base endpoint which returns tool definitions
 	testURL := fmt.Sprintf("%s/api/mcp", urlStr)
@@ -225,7 +238,7 @@ func (s *mcpServer) validateDirectURL() error {
 	defer func() { _ = resp.Body.Close() }()
 
 	if utils.IsAuthRequired(resp) {
-		return utils.ErrHubAuthRequired
+		return fmt.Errorf("%s", s.hubAuthErrorMessage())
 	}
 
 	// Try to parse the MCP response to validate it's a valid Kubeshark endpoint
@@ -305,6 +318,20 @@ func (s *mcpServer) ensureBackendConnection() string {
 
 // fetchHubMCP fetches tools and prompts from the Hub's /api/mcp endpoint
 // Returns nil if Hub is not available or returns an error
+// hubAuthErrorMessage returns a clear, user-facing explanation for an
+// auth-required hub response (401, or an unfollowed SSO 302/303 redirect),
+// distinguishing a missing/expired credential from a generic API error. URL
+// mode can't auto-renew, so it points the user at re-minting.
+func (s *mcpServer) hubAuthErrorMessage() string {
+	if s.urlMode {
+		return "Hub requires authentication (401/SSO redirect) and no accepted credential was presented. " +
+			"In URL mode pass a token via --token / KUBESHARK_HUB_TOKEN (mint with " +
+			"`kubectl create token kubeshark-cli --audience kubeshark-hub`) — it can't auto-renew, so re-mint and " +
+			"restart if it expired — or set a valid license (License-Key) if the deployment uses one."
+	}
+	return "Hub rejected the request (401 Unauthorized): the minted kubeshark-cli token was not accepted (check the Hub's AUTH_CLI_SERVICE_ACCOUNTS allowlist and the token audience), or no credential was available — if you lack RBAC to mint the token the CLI falls back to the License-Key, so set a valid license."
+}
+
 func (s *mcpServer) fetchHubMCP() *hubMCPResponse {
 	s.hubMCPMu.Lock()
 	defer s.hubMCPMu.Unlock()
@@ -327,6 +354,10 @@ func (s *mcpServer) fetchHubMCP() *hubMCPResponse {
 	}
 	defer func() { _ = resp.Body.Close() }()
 
+	if utils.IsAuthRequired(resp) {
+		fmt.Fprintf(os.Stderr, "[kubeshark-mcp] %s\n", s.hubAuthErrorMessage())
+		return nil
+	}
 	if resp.StatusCode >= 400 {
 		return nil
 	}
@@ -783,6 +814,9 @@ func (s *mcpServer) callHubTool(toolName string, args map[string]any) (string, b
 		return fmt.Sprintf("Error reading response: %v", err), true
 	}
 
+	if utils.IsAuthRequired(resp) {
+		return s.hubAuthErrorMessage(), true
+	}
 	if resp.StatusCode >= 400 {
 		return fmt.Sprintf("Hub API error (%d): %s", resp.StatusCode, string(body)), true
 	}
@@ -843,7 +877,8 @@ func (s *mcpServer) callDownloadFile(args map[string]any) (string, bool) {
 	// The default s.httpClient has a 30s total timeout which would fail for large files (up to 10GB).
 	// This client sets only connection-level timeouts and lets the body stream without a deadline.
 	downloadClient := &http.Client{
-		Transport: utils.HubAuthTransportWithToken(s.saToken, config.Config.License, &http.Transport{
+		CheckRedirect: utils.StopOnSSORedirect,
+		Transport: utils.HubAuthTransportWithTokenSource(s.tokenSource, config.Config.License, &http.Transport{
 			TLSHandshakeTimeout:   10 * time.Second,
 			ResponseHeaderTimeout: 30 * time.Second,
 		}),
@@ -855,6 +890,11 @@ func (s *mcpServer) callDownloadFile(args map[string]any) (string, bool) {
 	}
 	defer func() { _ = resp.Body.Close() }()
 
+	// Catch auth-required (401 / unfollowed SSO redirect) before treating the
+	// body as a file, so we don't write an HTML login page to disk.
+	if utils.IsAuthRequired(resp) {
+		return s.hubAuthErrorMessage(), true
+	}
 	if resp.StatusCode >= 400 {
 		return fmt.Sprintf("Error downloading file: HTTP %d", resp.StatusCode), true
 	}
@@ -1082,6 +1122,10 @@ func listMCPTools(directURL string) {
 	fmt.Println("=========")
 	fmt.Println()
 
+	// Same hub credential as the running server: renewing minter in proxy
+	// mode, static --token in URL mode (nil → License-Key).
+	tokenSource := hubTokenSource(directURL != "")
+
 	// URL mode - no cluster management, connect directly
 	if directURL != "" {
 		fmt.Printf("URL Mode: %s\n\n", directURL)
@@ -1094,7 +1138,7 @@ func listMCPTools(directURL string) {
 		fmt.Println()
 
 		hubURL := strings.TrimSuffix(directURL, "/") + "/api/mcp"
-		fetchAndDisplayTools(hubURL, 30*time.Second)
+		fetchAndDisplayTools(hubURL, 30*time.Second, tokenSource)
 		return
 	}
 
@@ -1118,7 +1162,7 @@ func listMCPTools(directURL string) {
 	}
 
 	fmt.Printf("Connected to: %s\n\n", hubURL)
-	fetchAndDisplayTools(hubURL, 30*time.Second)
+	fetchAndDisplayTools(hubURL, 30*time.Second, tokenSource)
 }
 
 // establishProxyConnection sets up proxy to Kubeshark and returns the hub URL
@@ -1167,8 +1211,8 @@ func establishProxyConnection(timeout time.Duration) (string, error) {
 }
 
 // fetchAndDisplayTools fetches tools from the Kubeshark API and displays them
-func fetchAndDisplayTools(hubURL string, timeout time.Duration) {
-	client := utils.NewHubHTTPClient(timeout, config.Config.License)
+func fetchAndDisplayTools(hubURL string, timeout time.Duration, tokenSource func() string) {
+	client := utils.NewHubHTTPClientWithTokenSource(timeout, tokenSource, config.Config.License)
 
 	// Fetch tools list from /api/mcp endpoint
 	resp, err := client.Get(strings.TrimSuffix(hubURL, "/mcp") + "/mcp")
@@ -1178,6 +1222,11 @@ func fetchAndDisplayTools(hubURL string, timeout time.Duration) {
 	}
 	defer func() { _ = resp.Body.Close() }()
 
+	if utils.IsAuthRequired(resp) {
+		fmt.Println("Kubeshark API: 401 Unauthorized — the Hub requires a valid credential. In --url mode pass --token (or KUBESHARK_HUB_TOKEN); in proxy mode ensure you have RBAC to mint the kubeshark-cli token.")
+		return
+	}
+
 	// Parse the response using the Hub MCP response format
 	var mcpInfo hubMCPResponse
 	if err := json.NewDecoder(resp.Body).Decode(&mcpInfo); err != nil {

config/configStruct.go

@@ -102,23 +102,10 @@ func CreateDefaultConfig() ConfigStruct {
 				},
 			},
 			Auth: configStructs.AuthConfig{
-				RolesClaim: "role",
-				Roles: map[string]configStructs.Role{
-					"admin": {
-						Filter:          "",
-						CanDownloadPCAP: true,
-						CanUseScripting: true,
-						ScriptingPermissions: configStructs.ScriptingPermissions{
-							CanSave:     true,
-							CanActivate: true,
-							CanDelete:   true,
-						},
-						CanUpdateTargetedPods:   true,
-						CanStopTrafficCapturing: true,
-						CanControlDissection:    true,
-						ShowAdminConsoleLink:    true,
-					},
-				},
+				RolesClaim:   "groups",
+				DefaultRole:  "kubeshark-viewer",
+				GroupMapping: map[string]string{},
+				Roles:        map[string]configStructs.RoleConfig{},
 			},
 			EnabledDissectors: []string{
 				"amqp",

config/configStructs/tapConfig.go

@@ -155,23 +155,6 @@ type ProbeConfig struct {
 	FailureThreshold    int `yaml:"failureThreshold" json:"failureThreshold" default:"3"`
 }
 
-type ScriptingPermissions struct {
-	CanSave     bool `yaml:"canSave" json:"canSave" default:"true"`
-	CanActivate bool `yaml:"canActivate" json:"canActivate" default:"true"`
-	CanDelete   bool `yaml:"canDelete" json:"canDelete" default:"true"`
-}
-
-type Role struct {
-	Filter                  string               `yaml:"filter" json:"filter" default:""`
-	CanDownloadPCAP         bool                 `yaml:"canDownloadPCAP" json:"canDownloadPCAP" default:"false"`
-	CanUseScripting         bool                 `yaml:"canUseScripting" json:"canUseScripting" default:"false"`
-	ScriptingPermissions    ScriptingPermissions `yaml:"scriptingPermissions" json:"scriptingPermissions"`
-	CanUpdateTargetedPods   bool                 `yaml:"canUpdateTargetedPods" json:"canUpdateTargetedPods" default:"false"`
-	CanStopTrafficCapturing bool                 `yaml:"canStopTrafficCapturing" json:"canStopTrafficCapturing" default:"false"`
-	CanControlDissection    bool                 `yaml:"canControlDissection" json:"canControlDissection" default:"false"`
-	ShowAdminConsoleLink    bool                 `yaml:"showAdminConsoleLink" json:"showAdminConsoleLink" default:"false"`
-}
-
 type SamlConfig struct {
 	IdpMetadataUrl string `yaml:"idpMetadataUrl" json:"idpMetadataUrl"`
 	X509crt        string `yaml:"x509crt" json:"x509crt"`
@@ -190,12 +173,70 @@ type AuthConfig struct {
 	// NOTE: prior releases routed `oidc` to Descope. If you were using `oidc`
 	// to mean Descope, switch to `descope` (or `default`). The rename is a
 	// breaking change documented in the release notes.
-	Type          string          `yaml:"type" json:"type" default:"saml"`
-	Roles         map[string]Role `yaml:"roles" json:"roles"`
-	RolesClaim    string          `yaml:"rolesClaim" json:"rolesClaim"`
-	DefaultRole   string          `yaml:"defaultRole" json:"defaultRole"`
-	DefaultFilter string          `yaml:"defaultFilter" json:"defaultFilter"`
-	Saml          SamlConfig      `yaml:"saml" json:"saml"`
+	Type       string `yaml:"type" json:"type" default:"saml"`
+	RolesClaim string `yaml:"rolesClaim" json:"rolesClaim"`
+	// DefaultRole is applied when the authenticated user's SSO claim has no
+	// recognized group. Must be one of the four built-in roles
+	// (kubeshark-admin / kubeshark-realtime / kubeshark-snapshot /
+	// kubeshark-viewer), the name of an operator-defined role under
+	// `tap.auth.roles`, or empty for strict-deny.
+	DefaultRole string `yaml:"defaultRole" json:"defaultRole"`
+	// GroupMapping translates SSO group names into role names (built-in or
+	// operator-defined). Optional — groups whose name already matches a
+	// built-in role are identity-matched and don't need an entry here.
+	// Operator-defined role names MUST appear here to participate in
+	// resolution (identity-match is built-in-only).
+	GroupMapping map[string]string `yaml:"groupMapping" json:"groupMapping"`
+	// Roles is the operator-defined role catalogue, keyed by role name.
+	// Each role has its own capability set + namespace scope. Names with
+	// the `kubeshark-` prefix are reserved for built-ins and will be
+	// rejected at hub startup. Unknown capability strings are dropped
+	// with a warning; empty / "*" namespace specs mean deny-all-data and
+	// allow-all respectively.
+	Roles map[string]RoleConfig `yaml:"roles" json:"roles"`
+	Cli   CliAuthConfig         `yaml:"cli" json:"cli"`
+	Saml  SamlConfig            `yaml:"saml" json:"saml"`
+}
+
+// CliAuthConfig gates ServiceAccount-token auth for the CLI. When enabled, the
+// chart creates a `kubeshark-cli` ServiceAccount plus a Role permitting
+// `create` on its token, and the hub allowlists it via the
+// AUTH_CLI_SERVICE_ACCOUNTS env var. The CLI mints a short-lived token for
+// that SA to authenticate to a gated hub. Map `kubeshark-cli` to a role via
+// GroupMapping (or DefaultRole); without a mapping it falls back to
+// DefaultRole.
+type CliAuthConfig struct {
+	Enabled bool `yaml:"enabled" json:"enabled" default:"false"`
+	// Subjects are the RBAC subjects permitted to mint the kubeshark-cli
+	// token — i.e. who may use the CLI against a gated hub. Rendered verbatim
+	// into the kubeshark-cli-token-minter RoleBinding; empty means the Role is
+	// created but bound to nobody.
+	Subjects []CliAuthSubject `yaml:"subjects" json:"subjects"`
+}
+
+// CliAuthSubject is one entry under tap.auth.cli.subjects, mirroring
+// rbacv1.Subject: Kind is User, Group or ServiceAccount; ApiGroup is
+// rbac.authorization.k8s.io for User and Group and must be empty for
+// ServiceAccount; Namespace applies to ServiceAccount only. The empty-able
+// fields are omitted when unset so the rendered RoleBinding stays valid for
+// every kind.
+type CliAuthSubject struct {
+	Kind      string `yaml:"kind" json:"kind"`
+	Name      string `yaml:"name" json:"name"`
+	ApiGroup  string `yaml:"apiGroup,omitempty" json:"apiGroup,omitempty"`
+	Namespace string `yaml:"namespace,omitempty" json:"namespace,omitempty"`
+}
+
+// RoleConfig is an operator-defined role declared under tap.auth.roles.
+// Capabilities is the closed vocabulary documented in the hub project
+// (snapshot:read / snapshot:write / snapshot:dissection / dissection:live /
+// dissection:control / pods:target:write / settings:write); unknown
+// capability strings are warn-dropped at hub startup. Namespaces is a
+// comma-separated list with `*` (allow-all) and glob (`foo-*`, `*-bar`,
+// `*mid*`) support; empty string means deny-all-data.
+type RoleConfig struct {
+	Capabilities []string `yaml:"capabilities" json:"capabilities"`
+	Namespaces   string   `yaml:"namespaces" json:"namespaces"`
 }
 
 type IngressConfig struct {

helm-chart/README.md

@@ -218,6 +218,8 @@ Example for overriding image names:
 | `tap.auth.rolesClaim`                     | Name of the JWT claim (OIDC) or SAML attribute carrying role memberships. | `role` |
 | `tap.auth.defaultRole`                    | Optional role name inside `tap.auth.roles` applied as fallback when an authenticated user has no matching role. Empty string = no fallback, zero-valued permissions. | `""` |
 | `tap.auth.roles`                          | Backend-neutral role map shared by SAML and OIDC. Each role's `namespaces` is a comma-separated list controlling which Kubernetes namespaces the role's users see traffic for: `""` = deny all, `"*"` = allow all, `"foo"` = literal namespace, `"foo,bar"` = OR over literals, `"foo-*"` = glob expansion against the cluster's known namespaces. Empty/unset `tap.auth.roles` grants nothing — admins opt into elevated access by populating this map. | `{"admin":{"namespaces":"*","canDownloadPCAP":true,"canUpdateTargetedPods":true,"canUseScripting":true,"scriptingPermissions":{"canSave":true,"canActivate":true,"canDelete":true},"canStopTrafficCapturing":true,"canControlDissection":true,"showAdminConsoleLink":true}}` |
+| `tap.auth.cli.enabled`                    | Enable ServiceAccount-token auth for the CLI. Creates a `kubeshark-cli` ServiceAccount plus a Role permitting `create` on its token, and allowlists it on the hub via `AUTH_CLI_SERVICE_ACCOUNTS`. The CLI mints a short-lived token for that SA to authenticate to a gated hub. Map `kubeshark-cli` to a role via `tap.auth.groupMapping`; without a mapping it falls back to `tap.auth.defaultRole`. | `false` |
+| `tap.auth.cli.subjects`                   | RBAC subjects permitted to mint the `kubeshark-cli` token — i.e. who may use the CLI against a gated hub. Each entry mirrors an `rbacv1.Subject`: `kind` (`User`, `Group` or `ServiceAccount`), `name`, `apiGroup` (`rbac.authorization.k8s.io` for `User`/`Group`, omitted for `ServiceAccount`) and `namespace` (`ServiceAccount` only). Empty means the Role is created but bound to nobody. | `[]` |
 | `tap.auth.saml.idpMetadataUrl`            | SAML IDP metadata URL <br/>(effective, if `tap.auth.type = saml`)                                  | ``                                                                                                                                                                                                                                               |
 | `tap.auth.saml.x509crt`                   | A self-signed X.509 `.cert` contents <br/>(effective, if `tap.auth.type = saml`)          | ``                                                                                                                                                                                                                                               |
 | `tap.auth.saml.x509key`                   | A self-signed X.509 `.key` contents <br/>(effective, if `tap.auth.type = saml`)           | ``                                                                                                                                                                                                                                               |

helm-chart/templates/09-worker-daemon-set.yaml

@@ -146,6 +146,10 @@ spec:
             value: '{{ (include "sentry.enabled" .) }}'
           - name: SENTRY_ENVIRONMENT
             value: '{{ .Values.tap.sentry.environment }}'
+          {{- if (((.Values.tap).auth).enabled) }}
+          - name: HUB_INTERNAL_TOKEN_PATH
+            value: /var/run/secrets/kubeshark/hub-token/token
+          {{- end }}
           resources:
             limits:
               {{ if ne (toString .Values.tap.resources.sniffer.limits.cpu) "0" }}
@@ -235,6 +239,11 @@ spec:
 {{- if .Values.tap.persistentStorage }}
               subPathExpr: $(NODE_NAME)
 {{- end }}
+            {{- if (((.Values.tap).auth).enabled) }}
+            - mountPath: /var/run/secrets/kubeshark/hub-token
+              name: hub-internal-token
+              readOnly: true
+            {{- end }}
       {{- if .Values.tap.tls }}
         - command:
             - ./tracer
@@ -430,3 +439,12 @@ spec:
           emptyDir:
             sizeLimit: {{ .Values.tap.storageLimit }}
 {{- end }}
+        {{- if (((.Values.tap).auth).enabled) }}
+        - name: hub-internal-token
+          projected:
+            sources:
+              - serviceAccountToken:
+                  path: token
+                  audience: kubeshark-hub
+                  expirationSeconds: 3600
+        {{- end }}

helm-chart/templates/12-config-map.yaml

@@ -29,11 +29,11 @@ data:
                   {{ (default false .Values.demoModeEnabled) | ternary "default" .Values.tap.auth.type }}
                 {{- end }}'
     AUTH_SAML_IDP_METADATA_URL: '{{ .Values.tap.auth.saml.idpMetadataUrl }}'
-    AUTH_ROLES: '{{ .Values.tap.auth.roles | toJson }}'
     AUTH_CLI_SERVICE_ACCOUNTS: '{{ if (((.Values.tap).auth).cli).enabled }}{{ .Release.Namespace }}:kubeshark-cli{{ end }}'
     AUTH_ROLES_CLAIM: '{{ .Values.tap.auth.rolesClaim }}'
     AUTH_DEFAULT_ROLE: '{{ default "" .Values.tap.auth.defaultRole }}'
-    AUTH_GROUP_MAPPING: '{{ .Values.tap.auth.groupMapping | default dict | toJson }}'
+    AUTH_GROUP_MAPPING: '{{ default (dict) .Values.tap.auth.groupMapping | toJson }}'
+    AUTH_ROLES: '{{ default (dict) .Values.tap.auth.roles | toJson }}'
     AUTH_OIDC_ISSUER: '{{ default "not set" (((.Values.tap).auth).oidc).issuer }}'
     AUTH_OIDC_REFRESH_TOKEN_LIFETIME: '{{ default "3960h" (((.Values.tap).auth).oidc).refreshTokenLifetime }}'
     AUTH_OIDC_STATE_PARAM_EXPIRY: '{{ default "10m" (((.Values.tap).auth).oidc).oauth2StateParamExpiry }}'

helm-chart/values.yaml

@@ -153,36 +153,12 @@ tap:
   auth:
     enabled: false
     type: saml
-    roles:
-      admin:
-        filter: ""
-        canDownloadPCAP: true
-        canUseScripting: true
-        scriptingPermissions:
-          canSave: true
-          canActivate: true
-          canDelete: true
-        canUpdateTargetedPods: true
-        canStopTrafficCapturing: true
-        canControlDissection: true
-        showAdminConsoleLink: true
-    rolesClaim: role
-    defaultRole: ""
-    defaultFilter: ""
-    # CLI ServiceAccount-token auth (gated-auth phase 2a). When enabled, the
-    # chart creates a `kubeshark-cli` ServiceAccount and a Role permitting
-    # `create` on its token, and the Hub allowlists it via
-    # AUTH_CLI_SERVICE_ACCOUNTS. The CLI mints a short-lived token for that SA
-    # to authenticate to a gated Hub. Map `kubeshark-cli` to a role via
-    # `groupMapping` (or `defaultRole`); without a mapping it falls back to
-    # `defaultRole`.
+    rolesClaim: groups
+    defaultRole: kubeshark-viewer
+    groupMapping: {}
+    roles: {}
     cli:
       enabled: false
-      # RBAC subjects allowed to mint the kubeshark-cli token — i.e. who may
-      # use the CLI against a gated Hub. Example:
-      #   - kind: User
-      #     name: alice@example.com
-      #     apiGroup: rbac.authorization.k8s.io
       subjects: []
     saml:
       idpMetadataUrl: ""

kubernetes/hubtoken.go

@@ -3,6 +3,8 @@ package kubernetes
 import (
 	"context"
 	"fmt"
+	"sync"
+	"time"
 
 	authenticationv1 "k8s.io/api/authentication/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
@@ -17,6 +19,13 @@ const (
 	CLIServiceAccountName = "kubeshark-cli"
 
 	hubTokenExpirySeconds = 3600
+	// hubTokenRenewMargin re-mints this long before expiry so requests in
+	// flight always carry a comfortably valid token.
+	hubTokenRenewMargin = 5 * time.Minute
+	// hubTokenMintRetryInterval throttles re-minting after a failure so a
+	// cluster where minting can't succeed (no RBAC, SA missing) doesn't pay a
+	// blocking CreateToken round-trip on every request.
+	hubTokenMintRetryInterval = 30 * time.Second
 )
 
 // MintHubToken requests a short-lived ServiceAccount token (audience
@@ -25,6 +34,14 @@ const (
 // kube RBAC must permit `create` on serviceaccounts/token for that SA — which
 // is what gates who may use the CLI against a gated Hub.
 func (provider *Provider) MintHubToken(ctx context.Context, namespace string) (string, error) {
+	tok, _, err := provider.mintHubToken(ctx, namespace)
+	return tok, err
+}
+
+// mintHubToken is MintHubToken plus the token's expiry (from the TokenRequest
+// response, so a cluster that caps the duration below the request is respected;
+// falls back to the requested TTL if the API omits it).
+func (provider *Provider) mintHubToken(ctx context.Context, namespace string) (string, time.Time, error) {
 	exp := int64(hubTokenExpirySeconds)
 	tr, err := provider.clientSet.CoreV1().ServiceAccounts(namespace).CreateToken(
 		ctx,
@@ -38,7 +55,58 @@ func (provider *Provider) MintHubToken(ctx context.Context, namespace string) (s
 		metav1.CreateOptions{},
 	)
 	if err != nil {
-		return "", fmt.Errorf("minting hub token for serviceaccount %s/%s: %w", namespace, CLIServiceAccountName, err)
+		return "", time.Time{}, fmt.Errorf("minting hub token for serviceaccount %s/%s: %w", namespace, CLIServiceAccountName, err)
 	}
-	return tr.Status.Token, nil
+	expireAt := tr.Status.ExpirationTimestamp.Time
+	if expireAt.IsZero() {
+		expireAt = time.Now().Add(time.Duration(hubTokenExpirySeconds) * time.Second)
+	}
+	return tr.Status.Token, expireAt, nil
+}
+
+// HubTokenRenewer hands out a hub SA token, transparently re-minting it before
+// it expires. Safe for concurrent use; intended for long-lived CLI processes
+// (mcp/console proxy mode) that would otherwise 401 after the ~1h token TTL.
+type HubTokenRenewer struct {
+	provider  *Provider
+	namespace string
+
+	mu          sync.Mutex
+	token       string
+	expireAt    time.Time
+	nextAttempt time.Time // earliest time to retry minting after a failure
+}
+
+// NewHubTokenRenewer builds a renewer that mints kubeshark-cli tokens in the
+// given namespace.
+func NewHubTokenRenewer(provider *Provider, namespace string) *HubTokenRenewer {
+	return &HubTokenRenewer{provider: provider, namespace: namespace}
+}
+
+// Token returns a currently-valid hub token, minting or re-minting as needed.
+// On a mint failure it returns the last token (possibly "") so the caller can
+// fall back to the License-Key rather than hard-failing.
+func (r *HubTokenRenewer) Token() string {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	needsMint := r.token == "" || time.Now().After(r.expireAt.Add(-hubTokenRenewMargin))
+	if needsMint && time.Now().After(r.nextAttempt) {
+		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		tok, expireAt, err := r.provider.mintHubToken(ctx, r.namespace)
+		cancel()
+		if err != nil {
+			// Throttle retries so a failing cluster doesn't block every request
+			// on a doomed mint; fall through to the expiry check below.
+			r.nextAttempt = time.Now().Add(hubTokenMintRetryInterval)
+		} else {
+			r.token, r.expireAt, r.nextAttempt = tok, expireAt, time.Time{}
+		}
+	}
+	// Never hand out an already-expired token: return "" so the auth
+	// round-tripper falls back to the License-Key instead of looping on 401s
+	// (it prefers any non-empty SA token over the License-Key).
+	if r.token != "" && !r.expireAt.IsZero() && time.Now().After(r.expireAt) {
+		return ""
+	}
+	return r.token
 }

mcp/README.md

@@ -88,6 +88,30 @@ Connect directly to an existing Kubeshark deployment:
 }
 ```
 
+For a **gated Hub** (`AUTH_ENABLED=true`), URL mode can't mint a token (no kube
+access), so supply one explicitly via `--token` (or the `KUBESHARK_HUB_TOKEN`
+env var). Mint it from a machine that has cluster access:
+
+```bash
+kubectl create token kubeshark-cli -n <release-namespace> --audience kubeshark-hub
+```
+
+```json
+{
+  "mcpServers": {
+    "kubeshark": {
+      "command": "kubeshark",
+      "args": ["mcp", "--url", "https://kubeshark.example.com", "--token", "<token>"]
+    }
+  }
+}
+```
+
+The token is short-lived (~1h) and URL mode **cannot auto-renew** it; when it
+expires the server reports a clear `401 ... token expired/invalid` message — re-mint
+and restart. Proxy mode (default, with kube access) mints the `kubeshark-cli`
+token automatically and **auto-renews** it, so long-running sessions don't expire.
+
 #### With Destructive Operations
 
 ```json
@@ -179,6 +203,7 @@ Found 5 services connecting to postgres:5432:
 | Option | Description |
 |--------|-------------|
 | `--url` | Direct URL to Kubeshark Hub |
+| `--token` | Hub SA/bearer token for `--url` mode against a gated Hub (also `KUBESHARK_HUB_TOKEN`); ignored in proxy mode, which mints and auto-renews the token |
 | `--kubeconfig` | Path to kubeconfig file |
 | `--allow-destructive` | Enable start/stop operations |
 | `--list-tools` | List available tools and exit |

utils/http.go

@@ -29,10 +29,14 @@ var ErrHubAuthRequired = errors.New("hub requires authentication: set a valid li
 // ServiceAccount token (CLI_AUTH_HEADER) when present, falling back to the
 // License-Key (admin/transitional). Both are custom headers so they survive
 // the kube API-server service proxy, unlike an Authorization bearer.
+//
+// The SA token is sourced via saTokenFunc on every request rather than captured
+// once, so a caller with cluster access (proxy mode) can hand in a renewing
+// source and long-lived clients keep working past the token's ~1h expiry.
 type hubAuthRoundTripper struct {
-	saToken    string
-	licenseKey string
-	base       http.RoundTripper
+	saTokenFunc func() string
+	licenseKey  string
+	base        http.RoundTripper
 }
 
 func (rt *hubAuthRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
@@ -40,11 +44,15 @@ func (rt *hubAuthRoundTripper) RoundTrip(req *http.Request) (*http.Response, err
 	if base == nil {
 		base = http.DefaultTransport
 	}
+	saToken := ""
+	if rt.saTokenFunc != nil {
+		saToken = rt.saTokenFunc()
+	}
 	switch {
-	case rt.saToken != "":
+	case saToken != "":
 		if req.Header.Get(CLI_AUTH_HEADER) == "" {
 			req = req.Clone(req.Context())
-			req.Header.Set(CLI_AUTH_HEADER, rt.saToken)
+			req.Header.Set(CLI_AUTH_HEADER, saToken)
 		}
 	case rt.licenseKey != "":
 		if req.Header.Get(LICENSE_KEY_HEADER) == "" {
@@ -55,22 +63,60 @@ func (rt *hubAuthRoundTripper) RoundTrip(req *http.Request) (*http.Response, err
 	return base.RoundTrip(req)
 }
 
+// staticToken adapts a fixed token string to the saTokenFunc source, returning
+// nil for an empty token so the round-tripper falls back to the License-Key.
+func staticToken(saToken string) func() string {
+	if saToken == "" {
+		return nil
+	}
+	return func() string { return saToken }
+}
+
+// StopOnSSORedirect is an *http.Client CheckRedirect that does NOT follow
+// SSO-style auth redirects (302 Found / 303 See Other) — it returns the
+// redirect response so callers can detect auth-required via IsAuthRequired
+// instead of silently following it to an HTML login page (and, for downloads,
+// writing that page to disk). Other redirects (301/307/308) are still followed.
+func StopOnSSORedirect(req *http.Request, _ []*http.Request) error {
+	if req.Response != nil {
+		switch req.Response.StatusCode {
+		case http.StatusFound, http.StatusSeeOther:
+			return http.ErrUseLastResponse
+		}
+	}
+	return nil
+}
+
 // NewHubHTTPClient returns an *http.Client that authenticates to the Hub with
-// the License-Key header (Phase 1).
+// the License-Key header.
 func NewHubHTTPClient(timeout time.Duration, licenseKey string) *http.Client {
 	return &http.Client{
-		Timeout:   timeout,
-		Transport: &hubAuthRoundTripper{licenseKey: licenseKey},
+		Timeout:       timeout,
+		CheckRedirect: StopOnSSORedirect,
+		Transport:     &hubAuthRoundTripper{licenseKey: licenseKey},
 	}
 }
 
 // NewHubHTTPClientWithToken returns an *http.Client that authenticates to the
-// Hub with a ServiceAccount token when saToken is set, otherwise the
+// Hub with a fixed ServiceAccount token when saToken is set, otherwise the
 // License-Key.
 func NewHubHTTPClientWithToken(timeout time.Duration, saToken, licenseKey string) *http.Client {
 	return &http.Client{
-		Timeout:   timeout,
-		Transport: &hubAuthRoundTripper{saToken: saToken, licenseKey: licenseKey},
+		Timeout:       timeout,
+		CheckRedirect: StopOnSSORedirect,
+		Transport:     &hubAuthRoundTripper{saTokenFunc: staticToken(saToken), licenseKey: licenseKey},
+	}
+}
+
+// NewHubHTTPClientWithTokenSource is NewHubHTTPClientWithToken with a token
+// source consulted per request, so a renewing source keeps the client
+// authenticated past the token's expiry. A nil source falls back to the
+// License-Key.
+func NewHubHTTPClientWithTokenSource(timeout time.Duration, saTokenFunc func() string, licenseKey string) *http.Client {
+	return &http.Client{
+		Timeout:       timeout,
+		CheckRedirect: StopOnSSORedirect,
+		Transport:     &hubAuthRoundTripper{saTokenFunc: saTokenFunc, licenseKey: licenseKey},
 	}
 }
 
@@ -81,16 +127,24 @@ func HubAuthTransport(licenseKey string, base http.RoundTripper) http.RoundTripp
 	return &hubAuthRoundTripper{licenseKey: licenseKey, base: base}
 }
 
-// HubAuthTransportWithToken is HubAuthTransport with a ServiceAccount token
-// (preferred over the License-Key when set).
+// HubAuthTransportWithToken is HubAuthTransport with a fixed ServiceAccount
+// token (preferred over the License-Key when set).
 func HubAuthTransportWithToken(saToken, licenseKey string, base http.RoundTripper) http.RoundTripper {
-	return &hubAuthRoundTripper{saToken: saToken, licenseKey: licenseKey, base: base}
+	return &hubAuthRoundTripper{saTokenFunc: staticToken(saToken), licenseKey: licenseKey, base: base}
+}
+
+// HubAuthTransportWithTokenSource is HubAuthTransportWithToken with a token
+// source consulted per request (see NewHubHTTPClientWithTokenSource).
+func HubAuthTransportWithTokenSource(saTokenFunc func() string, licenseKey string, base http.RoundTripper) http.RoundTripper {
+	return &hubAuthRoundTripper{saTokenFunc: saTokenFunc, licenseKey: licenseKey, base: base}
 }
 
 // IsAuthRequired reports whether the response indicates the Hub demanded
-// authentication — a 401, or a 302 redirect to an SSO login page.
+// authentication — a 401, or a 302/303 redirect to an SSO login page (the
+// hub clients are configured not to follow those; see StopOnSSORedirect).
 func IsAuthRequired(resp *http.Response) bool {
-	return resp != nil && (resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusFound)
+	return resp != nil && (resp.StatusCode == http.StatusUnauthorized ||
+		resp.StatusCode == http.StatusFound || resp.StatusCode == http.StatusSeeOther)
 }
 
 // Get - When err is nil, resp always contains a non-nil resp.Body.