feat(039): allow Docker image override for security scanners

Add per-scanner Docker image override so users can pin a specific version,
use a mirror registry, or substitute a custom build without editing the
bundled registry.

Backend:
  - ScannerPlugin.ImageOverride field (persisted via existing scanner storage)
  - EffectiveImage() helper returns override if set, else bundled DockerImage
  - Engine uses EffectiveImage() for container launch and existence checks
  - PUT /api/v1/security/scanners/{id}/config accepts optional docker_image
    alongside env map (either or both required)

Frontend:
  - Add Docker Image field to Configure dialog (placeholder shows default)
  - Show Configure button for all scanner states, not just installed/configured,
    so users can edit settings on disabled scanners too

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

Author: claude

frontend/src/services/api.ts

@@ -784,10 +784,12 @@ class APIService {
     })
   }
 
-  async configureScanner(id: string, env: Record<string, string>): Promise<APIResponse<void>> {
+  async configureScanner(id: string, env: Record<string, string>, dockerImage?: string): Promise<APIResponse<void>> {
+    const payload: any = { env }
+    if (dockerImage) payload.docker_image = dockerImage
     return this.request<void>(`/api/v1/security/scanners/${encodeURIComponent(id)}/config`, {
       method: 'PUT',
-      body: JSON.stringify({ env }),
+      body: JSON.stringify(payload),
     })
   }
 

frontend/src/views/Security.vue

@@ -196,7 +196,7 @@
                         Set API Key
                       </button>
                       <button
-                        v-else-if="scanner.status === 'installed' || scanner.status === 'configured'"
+                        v-else
                         @click="openConfigDialog(scanner)"
                         class="btn btn-sm btn-outline"
                       >
@@ -339,6 +339,23 @@
               class="input input-bordered"
             />
           </div>
+          <!-- Docker image override -->
+          <div class="divider text-xs">Docker Image</div>
+          <div class="form-control">
+            <label class="label">
+              <span class="label-text">Docker Image</span>
+              <span class="badge badge-sm badge-ghost">Optional</span>
+            </label>
+            <input
+              v-model="configDockerImage"
+              type="text"
+              :placeholder="configScanner?.image_override || configScanner?.docker_image || 'default image'"
+              class="input input-bordered input-sm font-mono"
+            />
+            <label class="label" v-if="configScanner?.docker_image">
+              <span class="label-text-alt text-base-content/40">Default: {{ configScanner.docker_image }}</span>
+            </label>
+          </div>
           <!-- Custom env var -->
           <div class="divider text-xs">Add Custom Variable</div>
           <div class="flex gap-2">
@@ -408,6 +425,7 @@ const configScanner = ref<any>(null)
 const configValues = ref<Record<string, string>>({})
 const customEnvKey = ref('')
 const customEnvValue = ref('')
+const configDockerImage = ref('')
 
 const totalFindings = computed(() => overview.value?.findings_by_severity?.total || 0)
 
@@ -506,6 +524,7 @@ function openConfigDialog(scanner: any) {
   configValues.value = { ...existing }
   customEnvKey.value = ''
   customEnvValue.value = ''
+  configDockerImage.value = scanner.image_override || ''
   configDialog.value?.showModal()
 }
 
@@ -539,8 +558,10 @@ async function saveConfig() {
       toSend[k] = v
     }
   }
-  if (Object.keys(toSend).length > 0) {
-    await api.configureScanner(configScanner.value.id, toSend)
+  const hasEnv = Object.keys(toSend).length > 0
+  const hasImage = configDockerImage.value && configDockerImage.value !== (configScanner.value?.image_override || '')
+  if (hasEnv || hasImage) {
+    await api.configureScanner(configScanner.value.id, toSend, configDockerImage.value || undefined)
   }
   closeConfigDialog()
   await refresh()

internal/httpapi/security_scanner.go

@@ -19,7 +19,7 @@ type SecurityController interface {
 	ListScanners(ctx context.Context) ([]*scanner.ScannerPlugin, error)
 	InstallScanner(ctx context.Context, id string) error
 	RemoveScanner(ctx context.Context, id string) error
-	ConfigureScanner(ctx context.Context, id string, env map[string]string) error
+	ConfigureScanner(ctx context.Context, id string, env map[string]string, dockerImage string) error
 	GetScannerStatus(ctx context.Context, id string) (*scanner.ScannerPlugin, error)
 
 	StartScan(ctx context.Context, serverName string, dryRun bool, scannerIDs []string, sourceDir string) (*scanner.ScanJob, error)
@@ -133,18 +133,19 @@ func (s *Server) handleConfigureScanner(w http.ResponseWriter, r *http.Request)
 	}
 
 	var req struct {
-		Env map[string]string `json:"env"`
+		Env         map[string]string `json:"env"`
+		DockerImage string            `json:"docker_image,omitempty"`
 	}
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 		s.writeError(w, r, http.StatusBadRequest, "invalid request body")
 		return
 	}
-	if len(req.Env) == 0 {
-		s.writeError(w, r, http.StatusBadRequest, "env map is required")
+	if len(req.Env) == 0 && req.DockerImage == "" {
+		s.writeError(w, r, http.StatusBadRequest, "env map or docker_image is required")
 		return
 	}
 
-	if err := s.securityController.ConfigureScanner(r.Context(), id, req.Env); err != nil {
+	if err := s.securityController.ConfigureScanner(r.Context(), id, req.Env, req.DockerImage); err != nil {
 		s.writeError(w, r, http.StatusInternalServerError, err.Error())
 		return
 	}

internal/httpapi/security_scanner_test.go

@@ -53,7 +53,7 @@ func (m *mockSecurityController) RemoveScanner(_ context.Context, id string) err
 	return m.removeErr
 }
 
-func (m *mockSecurityController) ConfigureScanner(_ context.Context, id string, env map[string]string) error {
+func (m *mockSecurityController) ConfigureScanner(_ context.Context, id string, env map[string]string, dockerImage string) error {
 	return m.configureErr
 }
 

internal/security/scanner/engine.go

@@ -179,10 +179,10 @@ func (e *Engine) resolveScanners(requestedIDs []string) ([]*ScannerPlugin, error
 	for _, s := range all {
 		if s.Status == ScannerStatusInstalled || s.Status == ScannerStatusConfigured {
 			// Verify Docker image exists before adding to scan list
-			if e.docker != nil && !e.docker.ImageExists(context.Background(), s.DockerImage) {
+			if e.docker != nil && !e.docker.ImageExists(context.Background(), s.EffectiveImage()) {
 				e.logger.Warn("Skipping scanner: Docker image not found locally",
 					zap.String("scanner", s.ID),
-					zap.String("image", s.DockerImage),
+					zap.String("image", s.EffectiveImage()),
 				)
 				continue
 			}
@@ -382,7 +382,7 @@ func (e *Engine) runSingleScanner(ctx context.Context, s *ScannerPlugin, req Sca
 	// Run scanner container
 	cfg := ScannerRunConfig{
 		ContainerName: GenerateContainerName(s.ID, req.ServerName),
-		Image:         s.DockerImage,
+		Image:         s.EffectiveImage(),
 		Command:       s.Command,
 		Env:           env,
 		SourceDir:     req.SourceDir,

internal/security/scanner/service.go

@@ -276,7 +276,7 @@ func (s *Service) SetSecretStore(store SecretStore) {
 
 // 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 {
+func (s *Service) ConfigureScanner(ctx context.Context, id string, env map[string]string, dockerImage string) error {
 	sc, err := s.storage.GetScanner(id)
 	if err != nil {
 		// If not in storage yet (just registered in registry), create from registry
@@ -306,6 +306,12 @@ func (s *Service) ConfigureScanner(ctx context.Context, id string, env map[strin
 			sc.ConfiguredEnv[k] = v
 		}
 	}
+
+	// Apply Docker image override
+	if dockerImage != "" {
+		sc.ImageOverride = dockerImage
+	}
+
 	sc.Status = ScannerStatusConfigured
 
 	if err := s.storage.SaveScanner(sc); err != nil {
@@ -314,10 +320,11 @@ func (s *Service) ConfigureScanner(ctx context.Context, id string, env map[strin
 
 	_ = s.registry.UpdateStatus(id, ScannerStatusConfigured)
 
-	// Also update the registry's ConfiguredEnv so the engine picks up
-	// new env vars without requiring a restart
+	// Also update the registry's ConfiguredEnv and ImageOverride so the engine
+	// picks up changes without requiring a restart
 	if reg, err := s.registry.Get(id); err == nil {
 		reg.ConfiguredEnv = sc.ConfiguredEnv
+		reg.ImageOverride = sc.ImageOverride
 	}
 
 	return nil

internal/security/scanner/service_test.go

@@ -451,7 +451,7 @@ func TestServiceConfigureScanner(t *testing.T) {
 		"API_KEY":    "my-key",
 		"API_SECRET": "my-secret",
 	}
-	err := svc.ConfigureScanner(context.Background(), "test-scanner", env)
+	err := svc.ConfigureScanner(context.Background(), "test-scanner", env, "")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -475,7 +475,7 @@ func TestServiceConfigureScanner(t *testing.T) {
 func TestServiceConfigureScannerNotInstalled(t *testing.T) {
 	svc, _, _ := newTestService(t)
 
-	err := svc.ConfigureScanner(context.Background(), "nonexistent", map[string]string{"KEY": "val"})
+	err := svc.ConfigureScanner(context.Background(), "nonexistent", map[string]string{"KEY": "val"}, "")
 	if err == nil {
 		t.Fatal("expected error for non-installed scanner")
 	}

internal/security/scanner/types.go

@@ -58,11 +58,20 @@ type ScannerPlugin struct {
 	Status        string            `json:"status"` // available, installed, configured, error
 	InstalledAt   time.Time         `json:"installed_at,omitempty"`
 	ConfiguredEnv map[string]string `json:"configured_env,omitempty"` // Set env values (secrets redacted in API)
+	ImageOverride string            `json:"image_override,omitempty"` // User override for DockerImage
 	LastUsedAt    time.Time         `json:"last_used_at,omitempty"`
 	ErrorMsg      string            `json:"error_message,omitempty"`
 	Custom        bool              `json:"custom,omitempty"` // User-added (not from registry)
 }
 
+// EffectiveImage returns ImageOverride if set, otherwise DockerImage.
+func (s *ScannerPlugin) EffectiveImage() string {
+	if s.ImageOverride != "" {
+		return s.ImageOverride
+	}
+	return s.DockerImage
+}
+
 // Scan pass constants
 const (
 	ScanPassSecurityScan     = 1 // Fast pass: source code + lockfile scanning