feat(039): store scanner API keys in OS keyring, not plaintext

Scanner API keys configured via the API or CLI are now stored in the
OS keyring (macOS Keychain / Linux Secret Service / Windows Credential
Manager) using the existing mcpproxy secrets system.

- ConfigureScanner stores values via keyring, keeps ${keyring:...} refs
- Engine resolves keyring references at scan time before passing to containers
- Secrets visible in `mcpproxy secrets list` alongside server secrets
- Fallback to direct storage if keyring is unavailable

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: claude

internal/security/scanner/engine.go

@@ -4,18 +4,23 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"strings"
 	"sync"
 	"time"
 
 	"go.uber.org/zap"
 )
 
+// SecretResolverFunc resolves a secret reference like ${keyring:name} to its value
+type SecretResolverFunc func(ctx context.Context, ref string) (string, error)
+
 // Engine orchestrates parallel scanner execution for a server
 type Engine struct {
-	docker   *DockerRunner
-	registry *Registry
-	logger   *zap.Logger
-	dataDir  string
+	docker         *DockerRunner
+	registry       *Registry
+	logger         *zap.Logger
+	dataDir        string
+	secretResolver SecretResolverFunc
 
 	// Track active scans (one per server)
 	mu          sync.Mutex
@@ -265,9 +270,20 @@ func (e *Engine) runSingleScanner(ctx context.Context, s *ScannerPlugin, req Sca
 	}
 
 	// Build env vars: scanner config + request env
+	// Resolve ${keyring:...} references if a secret resolver is available
 	env := make(map[string]string)
 	for k, v := range s.ConfiguredEnv {
-		env[k] = v
+		if e.secretResolver != nil && strings.HasPrefix(v, "${keyring:") {
+			resolved, err := e.secretResolver(ctx, v)
+			if err != nil {
+				e.logger.Warn("Failed to resolve secret for scanner env",
+					zap.String("key", k), zap.Error(err))
+				continue // Skip unresolvable secrets
+			}
+			env[k] = resolved
+		} else {
+			env[k] = v
+		}
 	}
 	for k, v := range req.Env {
 		env[k] = v

internal/security/scanner/service.go

@@ -3,6 +3,7 @@ package scanner
 import (
 	"context"
 	"fmt"
+	"strings"
 	"time"
 
 	"go.uber.org/zap"
@@ -67,6 +68,7 @@ type Service struct {
 	emitter        EventEmitter
 	sourceResolver *SourceResolver
 	serverInfo     ServerInfoProvider
+	secretStore    SecretStore
 	logger         *zap.Logger
 }
 
@@ -232,18 +234,55 @@ func (s *Service) RemoveScanner(ctx context.Context, id string) error {
 	return nil
 }
 
-// ConfigureScanner sets environment variables (API keys) for a scanner
+// SecretStore allows storing and resolving secrets via the OS keyring
+type SecretStore interface {
+	StoreSecret(ctx context.Context, name, value string) error
+	ResolveSecret(ctx context.Context, ref string) (string, error)
+}
+
+// SetSecretStore sets the secret store for secure API key management.
+// Also wires secret resolution into the scan engine for resolving
+// ${keyring:...} references in scanner env vars at scan time.
+func (s *Service) SetSecretStore(store SecretStore) {
+	s.secretStore = store
+	if store != nil {
+		s.engine.secretResolver = func(ctx context.Context, ref string) (string, error) {
+			return store.ResolveSecret(ctx, ref)
+		}
+	}
+}
+
+// ConfigureScanner sets environment variables (API keys) for a scanner.
+// Secret values are stored in the OS keyring; only references are kept in config.
 func (s *Service) ConfigureScanner(ctx context.Context, id string, env map[string]string) error {
 	sc, err := s.storage.GetScanner(id)
 	if err != nil {
-		return fmt.Errorf("scanner not installed: %w", err)
+		// If not in storage yet (just registered in registry), create from registry
+		regScanner, regErr := s.registry.Get(id)
+		if regErr != nil {
+			return fmt.Errorf("scanner not found: %w", err)
+		}
+		sc = regScanner
 	}
 
 	if sc.ConfiguredEnv == nil {
 		sc.ConfiguredEnv = make(map[string]string)
 	}
+
+	// Store secrets in keyring, keep references in config
 	for k, v := range env {
-		sc.ConfiguredEnv[k] = v
+		if s.secretStore != nil && v != "" {
+			keyringName := fmt.Sprintf("scanner_%s_%s", id, strings.ToLower(k))
+			if err := s.secretStore.StoreSecret(ctx, keyringName, v); err != nil {
+				s.logger.Warn("Failed to store secret in keyring, storing as reference",
+					zap.String("key", k), zap.Error(err))
+				sc.ConfiguredEnv[k] = v // Fallback: store directly
+			} else {
+				sc.ConfiguredEnv[k] = fmt.Sprintf("${keyring:%s}", keyringName)
+			}
+		} else {
+			sc.ConfiguredEnv[k] = v
+		}
 	}
 	sc.Status = ScannerStatusConfigured
 

internal/server/server.go

@@ -1659,6 +1659,7 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 		secDocker := scanner.NewDockerRunner(s.logger)
 		secService := scanner.NewService(sm, secRegistry, secDocker, dataDir, s.logger)
 		secService.SetServerInfoProvider(&configServerInfoProvider{cfg: cfg})
+		secService.SetSecretStore(&keyringSecretStore{resolver: secret.NewResolver()})
 		httpAPIServer.SetSecurityController(secService)
 	}
 	// Wire teams multi-user OAuth (no-op in personal edition)
@@ -2352,6 +2353,24 @@ func (s *Server) GetToolApprovalStatus(serverName, toolName string) (string, err
 	return string(record.Status), nil
 }
 
+// keyringSecretStore adapts secret.Resolver to scanner.SecretStore for API key management.
+type keyringSecretStore struct {
+	resolver *secret.Resolver
+}
+
+func (k *keyringSecretStore) StoreSecret(ctx context.Context, name, value string) error {
+	ref := secret.Ref{Type: "keyring", Name: name}
+	return k.resolver.Store(ctx, ref, value)
+}
+
+func (k *keyringSecretStore) ResolveSecret(ctx context.Context, refStr string) (string, error) {
+	ref, err := secret.ParseSecretRef(refStr)
+	if err != nil {
+		return "", err
+	}
+	return k.resolver.Resolve(ctx, *ref)
+}
+
 // configServerInfoProvider implements scanner.ServerInfoProvider using the config.
 type configServerInfoProvider struct {
 	cfg *config.Config