Merge pull request #522 from docker/feat/pass-run

feat: pass run command

Author: joe0BAB

plugins/pass/command.go

@@ -16,6 +16,7 @@ package pass
 
 import (
 	"context"
+	"errors"
 	"os"
 	"strings"
 
@@ -114,7 +115,7 @@ services:
 // Root returns the root command for the docker-pass CLI plugin
 func Root(ctx context.Context, s store.Store, info commands.VersionInfo) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "pass set|get|ls|rm",
+		Use:   "pass set|get|ls|rm|run",
 		Short: "Manage your local OS keychain secrets.",
 		Long: `Docker Pass is a helper for securely storing secrets in your local OS keychain and injecting them into containers when needed. 
 It uses platform-specific credential storage:
@@ -146,6 +147,7 @@ Secrets can be injected into running containers at runtime using the se:// URI s
 	cmd.AddCommand(wrapRunEWithSpan(commands.ListCommand(s)))
 	cmd.AddCommand(wrapRunEWithSpan(commands.RmCommand(s)))
 	cmd.AddCommand(wrapRunEWithSpan(commands.GetCommand(s)))
+	cmd.AddCommand(wrapRunEWithSpan(commands.RunCommand()))
 	cmd.AddCommand(commands.VersionCommand(info))
 
 	return cmd
@@ -180,9 +182,27 @@ func withOTEL(runE func(cmd *cobra.Command, args []string) error) func(*cobra.Co
 			trace.WithSpanKind(trace.SpanKindInternal),
 			trace.WithAttributes(attribute.String("command", cmd.Name())),
 		)
+
+		pendingExit := -1
+		defer func() {
+			if pendingExit >= 0 {
+				os.Exit(pendingExit)
+			}
+		}()
 		defer span.End()
+
 		cmd.SetContext(ctx)
 		err := runE(cmd, args)
+
+		var exitErr *commands.ExitCodeError
+		if errors.As(err, &exitErr) {
+			pendingExit = exitErr.Code
+			span.SetAttributes(attribute.Int("command.child_exit_code", exitErr.Code))
+			span.SetStatus(codes.Ok, "child exited")
+			calledMetric(ctx, cmd, nil)
+			return nil
+		}
+
 		calledMetric(ctx, cmd, err)
 		if err != nil {
 			span.RecordError(err)

plugins/pass/commands/run.go

@@ -0,0 +1,175 @@
+// Copyright 2025-2026 Docker, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package commands
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"os/signal"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/docker/secrets-engine/client"
+	"github.com/docker/secrets-engine/x/api"
+	"github.com/docker/secrets-engine/x/secrets"
+)
+
+const sePrefix = "se://"
+
+// ExitCodeError is returned from RunCommand when the executed child process
+// terminated with a non-zero status. It carries the exit code the wrapper
+// should exit with. Returning this instead of calling os.Exit directly lets
+// the surrounding OTel span wrapper finish recording metrics and span data
+// before the process exits.
+type ExitCodeError struct {
+	Code int
+}
+
+func (e *ExitCodeError) Error() string {
+	return fmt.Sprintf("child exited with code %d", e.Code)
+}
+
+const runExample = `
+### Run a command with one secret in its environment:
+SE_TOKEN=se://gh-token docker pass run -- gh repo list
+
+### Multiple references:
+DB_PASSWORD=se://myapp/postgres/password \
+API_KEY=se://myapp/anthropic/api-key \
+  docker pass run -- ./my-binary
+`
+
+func RunCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "run -- CMD [ARGS...]",
+		Short: "Run a command with se:// environment references resolved.",
+		Long: `Scans the current environment for variables whose value is exactly se://NAME.
+Each reference is resolved through the secrets-engine daemon and the resolved
+value is passed to the child process. The child inherits stdin, stdout, and
+stderr.
+
+Requires the secrets-engine daemon (Docker Desktop) to be running.
+
+If any reference cannot be resolved, the command fails before the child is
+started and exits non-zero.`,
+		Example: strings.Trim(runExample, "\n"),
+		Args:    cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := client.New(client.WithSocketPath(api.DefaultSocketPath()))
+			if err != nil {
+				return err
+			}
+
+			env, err := resolveEnv(cmd.Context(), c, os.Environ())
+			if err != nil {
+				return err
+			}
+
+			// No CommandContext: the signal forwarder owns the child's
+			// lifecycle. Tying the child to cmd.Context() would let cobra's
+			// ctx cancellation SIGKILL the child out from under the forwarder.
+			child := exec.Command(args[0], args[1:]...)
+			child.Env = env
+			child.Stdin = os.Stdin
+			child.Stdout = os.Stdout
+			child.Stderr = os.Stderr
+			// Isolate the child in its own process group so that
+			// terminal-generated signals (Ctrl-C) are delivered to us alone;
+			// the forwarder is then the sole path that reaches the child.
+			configureChildProcGroup(child)
+
+			// Install the signal handler before Start so a signal arriving in
+			// the window between fork and the forwarder goroutine cannot kill
+			// the parent and orphan the child.
+			sigCh := make(chan os.Signal, 1)
+			signal.Notify(sigCh, forwardableSignals()...)
+			defer signal.Stop(sigCh)
+
+			if err := child.Start(); err != nil {
+				return fmt.Errorf("starting child: %w", err)
+			}
+
+			done := make(chan struct{})
+			go func() {
+				for {
+					select {
+					case sig := <-sigCh:
+						_ = signalChild(child, sig)
+					case <-done:
+						return
+					}
+				}
+			}()
+
+			waitErr := child.Wait()
+			close(done)
+
+			if waitErr != nil {
+				var exitErr *exec.ExitError
+				if errors.As(waitErr, &exitErr) {
+					return &ExitCodeError{Code: childExitCode(exitErr.ProcessState)}
+				}
+				return waitErr
+			}
+			return nil
+		},
+	}
+	return cmd
+}
+
+func resolveEnv(ctx context.Context, r secrets.Resolver, env []string) ([]string, error) {
+	out := make([]string, 0, len(env))
+	for _, kv := range env {
+		key, value, _ := strings.Cut(kv, "=")
+		if !strings.HasPrefix(value, sePrefix) {
+			out = append(out, kv)
+			continue
+		}
+		resolved, err := resolveRef(ctx, r, key, value)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, key+"="+resolved)
+	}
+	return out, nil
+}
+
+func resolveRef(ctx context.Context, r secrets.Resolver, key, value string) (string, error) {
+	name := strings.TrimPrefix(value, sePrefix)
+	// Validate as an ID first so wildcards in the reference are rejected
+	// instead of silently broadening the lookup.
+	if _, err := secrets.ParseID(name); err != nil {
+		return "", fmt.Errorf("resolving %s: %w", key, err)
+	}
+	pattern, err := secrets.ParsePattern(name)
+	if err != nil {
+		return "", fmt.Errorf("resolving %s: %w", key, err)
+	}
+	envs, err := r.GetSecrets(ctx, pattern)
+	if err != nil {
+		return "", fmt.Errorf("resolving %s: %w", key, err)
+	}
+	if len(envs) == 0 {
+		return "", fmt.Errorf("resolving %s: %w", key, secrets.ErrNotFound)
+	}
+	if len(envs) > 1 {
+		return "", fmt.Errorf("resolving %s: %d secrets matched %s", key, len(envs), name)
+	}
+	return string(envs[0].Value), nil
+}