From 08152041b05e8d018f3a05186e5c0aeff9168187 Mon Sep 17 00:00:00 2001 From: Daniel Fox Date: Mon, 16 Nov 2026 13:16:19 -0700 Subject: [PATCH 1/7] Add support for 'sensitive' flags --- command.go | 39 ++++++++++- command_test.go | 12 ++++ docs.go | 2 +- flag.go | 70 ++++++++++++++++++++ flag_impl.go | 57 +++++++++++++++- flag_sensitive_test.go | 142 ++++++++++++++++++++++++++++++++++++++++ godoc-current.txt | 26 ++++++++ testdata/godoc-v3.x.txt | 26 ++++++++ 8 files changed, 371 insertions(+), 3 deletions(-) create mode 100644 flag_sensitive_test.go diff --git a/command.go b/command.go index df7181b4a7..c5642e4064 100644 --- a/command.go +++ b/command.go @@ -416,7 +416,7 @@ func (cmd *Command) set(fName string, f Flag, val string) error { cmd.setFlags[f] = struct{}{} cmd.setMultiValueParsingConfig(f) if err := f.Set(fName, val); err != nil { - return fmt.Errorf("invalid value %q for flag -%s: %v", val, fName, err) + return fmt.Errorf("invalid value %q for flag -%s: %v", redactValue(f, val, val), fName, redactValue(f, err.Error(), val)) } return nil } @@ -690,6 +690,43 @@ func (cmd *Command) FlagNames() []string { return names } +// SensitiveValues returns the current values of all flags marked as +// sensitive (see [SensitiveFlag]) in this command and all of its parent +// commands, so that they can be removed from logs or other output. +// The value of a flag that was not set is its default value. Empty values +// are left out, and only values that are text (strings, string slices, +// string map values and [fmt.Stringer] values) are returned. The values +// are sorted longest first, so that replacing them in that order also +// works when one value contains another. +func (cmd *Command) SensitiveValues() []string { + seenFlags := map[Flag]struct{}{} + seenVals := map[string]struct{}{} + vals := []string{} + + for _, c := range cmd.Lineage() { + for _, f := range c.allFlags() { + if _, ok := seenFlags[f]; ok || !isSensitive(f) { + continue + } + seenFlags[f] = struct{}{} + + for _, val := range sensitiveStrings(f.Get()) { + if _, ok := seenVals[val]; ok || val == "" { + continue + } + seenVals[val] = struct{}{} + vals = append(vals, val) + } + } + } + + slices.SortStableFunc(vals, func(a, b string) int { + return len(b) - len(a) + }) + + return vals +} + // Lineage returns *this* command and all of its ancestor commands // in order from child to parent func (cmd *Command) Lineage() []*Command { diff --git a/command_test.go b/command_test.go index 263ad82cde..665f051a5a 100644 --- a/command_test.go +++ b/command_test.go @@ -6756,6 +6756,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -6778,6 +6779,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "some usage text", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -6823,6 +6825,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -6845,6 +6848,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "another usage text", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -6969,6 +6973,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -7037,6 +7042,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "some usage text", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -7082,6 +7088,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -7104,6 +7111,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "another usage text", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -7149,6 +7157,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "some 'usage' text", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -7170,6 +7179,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -7192,6 +7202,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "another usage text", "required": false, + "sensitive": false, "hidden": false, "deprecated": "", "hideDefault": false, @@ -7213,6 +7224,7 @@ func TestJSONExportCommand(t *testing.T) { "defaultText": "", "usage": "", "required": false, + "sensitive": false, "hidden": true, "deprecated": "", "hideDefault": false, diff --git a/docs.go b/docs.go index f74fc22bad..099ec51392 100644 --- a/docs.go +++ b/docs.go @@ -111,7 +111,7 @@ func stringifyFlag(f Flag) string { if df.IsDefaultVisible() { if s := df.GetDefaultText(); s != "" { defaultValueString = fmt.Sprintf(formatDefault("%s"), s) - } else if df.TakesValue() && df.GetValue() != "" { + } else if df.TakesValue() && df.GetValue() != "" && !isSensitive(f) { defaultValueString = fmt.Sprintf(formatDefault("%s"), df.GetValue()) } } diff --git a/flag.go b/flag.go index 7886b93a2c..b61b9e1805 100644 --- a/flag.go +++ b/flag.go @@ -128,6 +128,15 @@ type DeprecatedFlag interface { GetDeprecated() string } +// SensitiveFlag is an interface that allows us to mark flags whose values +// are secrets, such as passwords or tokens. The value of a sensitive flag +// is not shown in help output, JSON output or error messages, and is returned by +// [Command.SensitiveValues] so that it can be removed from other output. +type SensitiveFlag interface { + // IsSensitive returns true if the flag's value must be kept secret + IsSensitive() bool +} + // DocGenerationFlag is an interface that allows documentation generation for the flag type DocGenerationFlag interface { // TakesValue returns true if the flag takes a value, otherwise false @@ -218,6 +227,67 @@ type LocalFlag interface { IsLocal() bool } +// redactedText replaces the value of a sensitive flag in output +const redactedText = "REDACTED" + +func isSensitive(f Flag) bool { + sf, ok := f.(SensitiveFlag) + return ok && sf.IsSensitive() +} + +// sensitivePartser is implemented by flags that can split a raw value into +// the parts that an error message may quote, such as the items of a slice +// or the values of a map +type sensitivePartser interface { + sensitiveParts(val string) []string +} + +// redactValue replaces each occurrence of val, and of each part of val that +// an error message may quote on its own, in s if f is sensitive +func redactValue(f Flag, s, val string) string { + if !isSensitive(f) || val == "" { + return s + } + + parts := []string{val} + if p, ok := f.(sensitivePartser); ok { + parts = p.sensitiveParts(val) + } + + // Replace longer parts first, so that a part that contains another is + // replaced as a whole + parts = slices.DeleteFunc(slices.Clone(parts), func(p string) bool { return p == "" }) + slices.SortStableFunc(parts, func(a, b string) int { return len(b) - len(a) }) + parts = slices.Compact(parts) + + oldnew := make([]string, 0, 2*len(parts)) + for _, p := range parts { + oldnew = append(oldnew, p, redactedText) + } + return strings.NewReplacer(oldnew...).Replace(s) +} + +// sensitiveStrings returns the string forms of a sensitive flag's value. +// Only values that are text are returned, as replacing e.g. a number +// everywhere in a log line would hide much more than the secret. +func sensitiveStrings(v any) []string { + switch v := v.(type) { + case string: + return []string{v} + case []string: + return v + case map[string]string: + vals := make([]string, 0, len(v)) + for _, val := range v { + vals = append(vals, val) + } + return vals + case fmt.Stringer: + return []string{v.String()} + } + return nil +} + func visibleFlags(fl []Flag) []Flag { var visible []Flag for _, f := range fl { diff --git a/flag_impl.go b/flag_impl.go index b3a0d3c20e..36be84cd97 100644 --- a/flag_impl.go +++ b/flag_impl.go @@ -2,6 +2,7 @@ package cli import ( "context" + "encoding/json" "flag" "fmt" "reflect" @@ -63,6 +64,7 @@ type FlagBase[T any, C any, VC ValueCreator[T, C]] struct { Sources ValueSourceChain `json:"-"` // sources to load flag value from Required bool `json:"required"` // whether the flag is required or not Hidden bool `json:"hidden"` // whether to hide the flag in help output + Sensitive bool `json:"sensitive"` // whether the value is a secret that must not be shown in help output, JSON or errors Deprecated string `json:"deprecated"` // deprecation message, if set a warning is printed when the flag is set Local bool `json:"local"` // whether the flag is only for this command and not accepted by subcommands Value T `json:"defaultValue"` // default value for this flag if not set by from any source @@ -177,7 +179,7 @@ func (f *FlagBase[T, C, V]) PostParse() error { if err := f.Set(f.Name, val); err != nil { return fmt.Errorf( "could not parse %[1]q as %[2]T value from %[3]s for flag %[4]s: %[5]s", - val, f.Value, source, f.Name, err, + redactValue(f, val, val), f.Value, source, f.Name, redactValue(f, err.Error(), val), ) } @@ -331,6 +333,59 @@ func (f *FlagBase[T, C, V]) IsRequired() bool { return f.Required } +// IsSensitive returns whether or not the flag's value is a secret +func (f *FlagBase[T, C, V]) IsSensitive() bool { + return f.Sensitive +} + +// flagBaseJSON has the fields of FlagBase but not its methods, so that +// MarshalJSON can encode it without calling itself +type flagBaseJSON[T any, C any, VC ValueCreator[T, C]] FlagBase[T, C, VC] + +// MarshalJSON encodes the flag as JSON. The default value of a sensitive +// flag is left out, so that a secret default does not end up in exported +// help. +func (f *FlagBase[T, C, V]) MarshalJSON() ([]byte, error) { + c := *f + if c.Sensitive { + var zero T + c.Value = zero + } + return json.Marshal((*flagBaseJSON[T, C, V])(&c)) +} + +// sensitiveParts returns val and, for slice and map flags, each item of val +// and each map value, as an error message may quote any of them on its own +func (f *FlagBase[T, C, V]) sensitiveParts(val string) []string { + parts := []string{val} + + kind := reflect.TypeFor[T]().Kind() + if kind != reflect.Slice && kind != reflect.Map { + return parts + } + + var cfg multiValueParsingConfig + if f.multiValueConfig != nil { + cfg = *f.multiValueConfig + } + kvSep := cfg.MapFlagKeyValueSeparator + if kvSep == "" { + kvSep = defaultMapFlagKeyValueSeparator + } + + for _, item := range flagSplitMultiValues(val, cfg.SliceFlagSeparator, cfg.DisableSliceFlagSeparator) { + parts = append(parts, item, strings.TrimSpace(item)) + if kind != reflect.Map { + continue + } + if _, v, ok := strings.Cut(item, kvSep); ok { + parts = append(parts, v, strings.TrimSpace(v)) + } + } + + return parts +} + // IsVisible returns true if the flag is not hidden, otherwise false func (f *FlagBase[T, C, V]) IsVisible() bool { return !f.Hidden diff --git a/flag_sensitive_test.go b/flag_sensitive_test.go new file mode 100644 index 0000000000..f341fcbce3 --- /dev/null +++ b/flag_sensitive_test.go @@ -0,0 +1,142 @@ +package cli + +import ( + "context" + "encoding/json" + "fmt" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestSensitiveFlagHidesDefaultInHelp(t *testing.T) { + f := &StringFlag{Name: "token", Value: "s3cret", Sensitive: true} + assert.NotContains(t, f.String(), "s3cret") + + f = &StringFlag{Name: "token", Value: "s3cret", Sensitive: true, DefaultText: "from vault"} + assert.Contains(t, f.String(), "from vault") + + f = &StringFlag{Name: "token", Value: "s3cret"} + assert.Contains(t, f.String(), "s3cret") +} + +func TestSensitiveFlagRedactsArgError(t *testing.T) { + cmd := &Command{ + Name: "app", + Flags: []Flag{&IntFlag{Name: "pin", Sensitive: true}}, + } + + err := cmd.Run(buildTestContext(t), []string{"app", "--pin", "s3cret"}) + require.Error(t, err) + assert.NotContains(t, err.Error(), "s3cret") + assert.Contains(t, err.Error(), redactedText) +} + +func TestSensitiveFlagRedactsSourceError(t *testing.T) { + t.Setenv("APP_PIN", "s3cret") + cmd := &Command{ + Name: "app", + Flags: []Flag{&IntFlag{ + Name: "pin", + Sensitive: true, + Sources: EnvVars("APP_PIN"), + }}, + } + + err := cmd.Run(buildTestContext(t), []string{"app"}) + require.Error(t, err) + assert.NotContains(t, err.Error(), "s3cret") + assert.Contains(t, err.Error(), "APP_PIN") +} + +func TestSensitiveFlagRedactsItemsInErrors(t *testing.T) { + tests := []struct { + name string + flag Flag + arg string + }{ + { + name: "map item without separator", + flag: &StringMapFlag{Name: "f", Sensitive: true}, + arg: "a=b,s3cret", + }, + { + name: "slice item that fails to parse", + flag: &IntSliceFlag{Name: "f", Sensitive: true}, + arg: "1, s3cret", + }, + { + name: "map value that fails to parse", + flag: &StringMapFlag{Name: "f", Sensitive: true, Validator: func(m map[string]string) error { + return fmt.Errorf("bad value %q", m["k"]) + }}, + arg: "k=s3cret", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + cmd := &Command{Name: "app", Flags: []Flag{tt.flag}} + err := cmd.Run(buildTestContext(t), []string{"app", "--f", tt.arg}) + require.Error(t, err) + assert.NotContains(t, err.Error(), "s3cret") + }) + } +} + +func TestSensitiveFlagJSON(t *testing.T) { + b, err := json.Marshal(&StringFlag{Name: "token", Value: "s3cret", Sensitive: true}) + require.NoError(t, err) + assert.NotContains(t, string(b), "s3cret") + assert.Contains(t, string(b), `"sensitive":true`) + assert.Contains(t, string(b), `"name":"token"`) + + f := &StringFlag{Name: "user", Value: "bob"} + b, err = json.Marshal(f) + require.NoError(t, err) + assert.Contains(t, string(b), `"defaultValue":"bob"`) + assert.Equal(t, "bob", f.Value) +} + +func TestSensitiveValues(t *testing.T) { + t.Setenv("APP_TOKEN", "root-token") + + var got []string + cmd := &Command{ + Name: "app", + Flags: []Flag{ + &StringFlag{Name: "token", Sensitive: true, Sources: EnvVars("APP_TOKEN")}, + &StringFlag{Name: "password", Sensitive: true, Value: "default-password"}, + &StringFlag{Name: "unused", Sensitive: true}, + &StringFlag{Name: "user", Value: "bob"}, + }, + Commands: []*Command{{ + Name: "sub", + Flags: []Flag{ + &StringSliceFlag{Name: "keys", Sensitive: true}, + &StringMapFlag{Name: "headers", Sensitive: true}, + }, + Action: func(_ context.Context, cmd *Command) error { + got = cmd.SensitiveValues() + return nil + }, + }}, + } + + err := cmd.Run(buildTestContext(t), []string{ + "app", "sub", + "--keys", "k1,root-token", + "--headers", "Authorization=Bearer x", + }) + require.NoError(t, err) + assert.Equal(t, []string{"default-password", "root-token", "Bearer x", "k1"}, got) +} + +func TestSensitiveValuesNone(t *testing.T) { + cmd := &Command{ + Name: "app", + Flags: []Flag{&StringFlag{Name: "user", Value: "bob"}}, + } + assert.Empty(t, cmd.SensitiveValues()) +} diff --git a/godoc-current.txt b/godoc-current.txt index b6338ec021..b0c24f1f4d 100644 --- a/godoc-current.txt +++ b/godoc-current.txt @@ -757,6 +757,15 @@ func (cmd *Command) Run(ctx context.Context, osArgs []string) (deferErr error) parsed according to the Flag and Command definitions and the matching Action functions are run. +func (cmd *Command) SensitiveValues() []string + SensitiveValues returns the current values of all flags marked as sensitive + (see SensitiveFlag) in this command and all of its parent commands, so that + they can be removed from logs or other output. The value of a flag that was + not set is its default value. Empty values are left out, and only values + that are text (strings, string slices, string map values and fmt.Stringer + values) are returned. The values are sorted longest first, so that replacing + them in that order also works when one value contains another. + func (cmd *Command) Set(name, value string) error Set sets a context flag to a value. @@ -1032,6 +1041,7 @@ type FlagBase[T any, C any, VC ValueCreator[T, C]] struct { Sources ValueSourceChain `json:"-"` // sources to load flag value from Required bool `json:"required"` // whether the flag is required or not Hidden bool `json:"hidden"` // whether to hide the flag in help output + Sensitive bool `json:"sensitive"` // whether the value is a secret that must not be shown in help output, JSON or errors Deprecated string `json:"deprecated"` // deprecation message, if set a warning is printed when the flag is set Local bool `json:"local"` // whether the flag is only for this command and not accepted by subcommands Value T `json:"defaultValue"` // default value for this flag if not set by from any source @@ -1093,12 +1103,19 @@ func (f *FlagBase[T, C, VC]) IsMultiValueFlag() bool func (f *FlagBase[T, C, V]) IsRequired() bool IsRequired returns whether or not the flag is required +func (f *FlagBase[T, C, V]) IsSensitive() bool + IsSensitive returns whether or not the flag's value is a secret + func (f *FlagBase[T, C, V]) IsSet() bool IsSet returns whether or not the flag has been set through env or file func (f *FlagBase[T, C, V]) IsVisible() bool IsVisible returns true if the flag is not hidden, otherwise false +func (f *FlagBase[T, C, V]) MarshalJSON() ([]byte, error) + MarshalJSON encodes the flag as JSON. The default value of a sensitive flag + is left out, so that a secret default does not end up in exported help. + func (f *FlagBase[T, C, V]) Names() []string Names returns the names of the flag @@ -1413,6 +1430,15 @@ type SchemaTyper interface { SchemaTyper is an optional interface for flags that can report their JSON Schema type for programmatic introspection. +type SensitiveFlag interface { + // IsSensitive returns true if the flag's value must be kept secret + IsSensitive() bool +} + SensitiveFlag is an interface that allows us to mark flags whose values + are secrets, such as passwords or tokens. The value of a sensitive flag is + not shown in help output, JSON output or error messages, and is returned by + Command.SensitiveValues so that it can be removed from other output. + type Serializer interface { Serialize() string } diff --git a/testdata/godoc-v3.x.txt b/testdata/godoc-v3.x.txt index b6338ec021..b0c24f1f4d 100644 --- a/testdata/godoc-v3.x.txt +++ b/testdata/godoc-v3.x.txt @@ -757,6 +757,15 @@ func (cmd *Command) Run(ctx context.Context, osArgs []string) (deferErr error) parsed according to the Flag and Command definitions and the matching Action functions are run. +func (cmd *Command) SensitiveValues() []string + SensitiveValues returns the current values of all flags marked as sensitive + (see SensitiveFlag) in this command and all of its parent commands, so that + they can be removed from logs or other output. The value of a flag that was + not set is its default value. Empty values are left out, and only values + that are text (strings, string slices, string map values and fmt.Stringer + values) are returned. The values are sorted longest first, so that replacing + them in that order also works when one value contains another. + func (cmd *Command) Set(name, value string) error Set sets a context flag to a value. @@ -1032,6 +1041,7 @@ type FlagBase[T any, C any, VC ValueCreator[T, C]] struct { Sources ValueSourceChain `json:"-"` // sources to load flag value from Required bool `json:"required"` // whether the flag is required or not Hidden bool `json:"hidden"` // whether to hide the flag in help output + Sensitive bool `json:"sensitive"` // whether the value is a secret that must not be shown in help output, JSON or errors Deprecated string `json:"deprecated"` // deprecation message, if set a warning is printed when the flag is set Local bool `json:"local"` // whether the flag is only for this command and not accepted by subcommands Value T `json:"defaultValue"` // default value for this flag if not set by from any source @@ -1093,12 +1103,19 @@ func (f *FlagBase[T, C, VC]) IsMultiValueFlag() bool func (f *FlagBase[T, C, V]) IsRequired() bool IsRequired returns whether or not the flag is required +func (f *FlagBase[T, C, V]) IsSensitive() bool + IsSensitive returns whether or not the flag's value is a secret + func (f *FlagBase[T, C, V]) IsSet() bool IsSet returns whether or not the flag has been set through env or file func (f *FlagBase[T, C, V]) IsVisible() bool IsVisible returns true if the flag is not hidden, otherwise false +func (f *FlagBase[T, C, V]) MarshalJSON() ([]byte, error) + MarshalJSON encodes the flag as JSON. The default value of a sensitive flag + is left out, so that a secret default does not end up in exported help. + func (f *FlagBase[T, C, V]) Names() []string Names returns the names of the flag @@ -1413,6 +1430,15 @@ type SchemaTyper interface { SchemaTyper is an optional interface for flags that can report their JSON Schema type for programmatic introspection. +type SensitiveFlag interface { + // IsSensitive returns true if the flag's value must be kept secret + IsSensitive() bool +} + SensitiveFlag is an interface that allows us to mark flags whose values + are secrets, such as passwords or tokens. The value of a sensitive flag is + not shown in help output, JSON output or error messages, and is returned by + Command.SensitiveValues so that it can be removed from other output. + type Serializer interface { Serialize() string } From ae54583c199726d6171c432d3e433374a44b0308 Mon Sep 17 00:00:00 2001 From: Daniel Fox Date: Mon, 16 Nov 2026 13:27:57 -0700 Subject: [PATCH 2/7] Move value masking from flags to Command Co-Authored-By: Claude Opus 5.5 --- command.go | 30 ++++++++++++++++++++++++++ flag.go | 30 +++++++++++++++++++++++++- flag_impl.go | 20 ++++++------------ flag_sensitive_test.go | 47 +++++++++++++++++++++++++++++++++-------- godoc-current.txt | 20 +++++++++++------- testdata/godoc-v3.x.txt | 20 +++++++++++------- 6 files changed, 127 insertions(+), 40 deletions(-) diff --git a/command.go b/command.go index c5642e4064..6a1cc7f26c 100644 --- a/command.go +++ b/command.go @@ -2,6 +2,7 @@ package cli import ( "context" + "encoding/json" "fmt" "io" "slices" @@ -690,6 +691,35 @@ func (cmd *Command) FlagNames() []string { return names } +// commandJSON has the fields of Command but not its methods, so that +// MarshalJSON can encode it without calling itself +type commandJSON Command + +// MarshalJSON encodes the command as JSON. The default value of each flag +// marked as sensitive (see [SensitiveFlag]) is left out, so that a secret +// default does not end up in exported help. Subcommands are encoded the +// same way. Encoding a flag on its own, outside a command, does not leave +// out its default value. +func (cmd *Command) MarshalJSON() ([]byte, error) { + c := *cmd + c.Flags = redactFlagsForJSON(c.Flags) + + if len(c.MutuallyExclusiveFlags) > 0 { + groups := make([]MutuallyExclusiveFlags, len(c.MutuallyExclusiveFlags)) + for i, g := range c.MutuallyExclusiveFlags { + opts := make([][]Flag, len(g.Flags)) + for j, opt := range g.Flags { + opts[j] = redactFlagsForJSON(opt) + } + g.Flags = opts + groups[i] = g + } + c.MutuallyExclusiveFlags = groups + } + + return json.Marshal((*commandJSON)(&c)) +} + // SensitiveValues returns the current values of all flags marked as // sensitive (see [SensitiveFlag]) in this command and all of its parent // commands, so that they can be removed from logs or other output. diff --git a/flag.go b/flag.go index b61b9e1805..5f4850602d 100644 --- a/flag.go +++ b/flag.go @@ -130,7 +130,8 @@ type DeprecatedFlag interface { // SensitiveFlag is an interface that allows us to mark flags whose values // are secrets, such as passwords or tokens. The value of a sensitive flag -// is not shown in help output, JSON output or error messages, and is returned by +// is not shown in help output, a command's JSON (see [Command.MarshalJSON]) +// or error messages, and is returned by // [Command.SensitiveValues] so that it can be removed from other output. type SensitiveFlag interface { // IsSensitive returns true if the flag's value must be kept secret @@ -242,6 +243,33 @@ type sensitivePartser interface { sensitiveParts(val string) []string } +// jsonRedacter is implemented by flags that can return a copy of themselves +// without their default value, for encoding a sensitive flag as JSON +type jsonRedacter interface { + redactedForJSON() Flag +} + +// redactFlagsForJSON returns flags with each sensitive flag replaced by a +// copy without its default value. flags is returned as is if no flag +// needs replacing. +func redactFlagsForJSON(flags []Flag) []Flag { + var out []Flag + for i, f := range flags { + r, ok := f.(jsonRedacter) + if !ok || !isSensitive(f) { + continue + } + if out == nil { + out = slices.Clone(flags) + } + out[i] = r.redactedForJSON() + } + if out == nil { + return flags + } + return out +} + // redactValue replaces each occurrence of val, and of each part of val that // an error message may quote on its own, in s if f is sensitive func redactValue(f Flag, s, val string) string { diff --git a/flag_impl.go b/flag_impl.go index 36be84cd97..4f0a2ffe12 100644 --- a/flag_impl.go +++ b/flag_impl.go @@ -2,7 +2,6 @@ package cli import ( "context" - "encoding/json" "flag" "fmt" "reflect" @@ -338,20 +337,13 @@ func (f *FlagBase[T, C, V]) IsSensitive() bool { return f.Sensitive } -// flagBaseJSON has the fields of FlagBase but not its methods, so that -// MarshalJSON can encode it without calling itself -type flagBaseJSON[T any, C any, VC ValueCreator[T, C]] FlagBase[T, C, VC] - -// MarshalJSON encodes the flag as JSON. The default value of a sensitive -// flag is left out, so that a secret default does not end up in exported -// help. -func (f *FlagBase[T, C, V]) MarshalJSON() ([]byte, error) { +// redactedForJSON returns a copy of the flag without its default value, for +// Command.MarshalJSON to encode in place of a sensitive flag +func (f *FlagBase[T, C, V]) redactedForJSON() Flag { c := *f - if c.Sensitive { - var zero T - c.Value = zero - } - return json.Marshal((*flagBaseJSON[T, C, V])(&c)) + var zero T + c.Value = zero + return &c } // sensitiveParts returns val and, for slice and map flags, each item of val diff --git a/flag_sensitive_test.go b/flag_sensitive_test.go index f341fcbce3..d565630777 100644 --- a/flag_sensitive_test.go +++ b/flag_sensitive_test.go @@ -85,18 +85,47 @@ func TestSensitiveFlagRedactsItemsInErrors(t *testing.T) { } } -func TestSensitiveFlagJSON(t *testing.T) { - b, err := json.Marshal(&StringFlag{Name: "token", Value: "s3cret", Sensitive: true}) +func TestSensitiveFlagCommandJSON(t *testing.T) { + token := &StringFlag{Name: "token", Value: "s3cret-root", Sensitive: true} + user := &StringFlag{Name: "user", Value: "bob"} + cmd := &Command{ + Name: "app", + Flags: []Flag{token, user}, + Commands: []*Command{{ + Name: "sub", + Flags: []Flag{&IntFlag{Name: "pin", Value: 4242, Sensitive: true}}, + MutuallyExclusiveFlags: []MutuallyExclusiveFlags{{ + Flags: [][]Flag{{&StringFlag{Name: "key", Value: "s3cret-group", Sensitive: true}}}, + }}, + }}, + } + + b, err := json.Marshal(cmd) require.NoError(t, err) - assert.NotContains(t, string(b), "s3cret") - assert.Contains(t, string(b), `"sensitive":true`) - assert.Contains(t, string(b), `"name":"token"`) + out := string(b) + assert.NotContains(t, out, "s3cret-root") + assert.NotContains(t, out, "4242") + assert.NotContains(t, out, "s3cret-group") + assert.Contains(t, out, `"sensitive":true`) + assert.Contains(t, out, `"defaultValue":"bob"`) + + // encoding must not change the command's own flags + assert.Same(t, token, cmd.Flags[0]) + assert.Equal(t, "s3cret-root", token.Value) +} + +// A type that embeds a flag must keep its own fields when encoded, as it +// did before sensitive flags were added +func TestSensitiveFlagEmbeddedFlagJSON(t *testing.T) { + type myFlag struct { + StringFlag + Extra string `json:"extra"` + } - f := &StringFlag{Name: "user", Value: "bob"} - b, err = json.Marshal(f) + b, err := json.Marshal(&myFlag{StringFlag: StringFlag{Name: "n"}, Extra: "kept"}) require.NoError(t, err) - assert.Contains(t, string(b), `"defaultValue":"bob"`) - assert.Equal(t, "bob", f.Value) + assert.Contains(t, string(b), `"extra":"kept"`) + assert.Contains(t, string(b), `"name":"n"`) } func TestSensitiveValues(t *testing.T) { diff --git a/godoc-current.txt b/godoc-current.txt index b0c24f1f4d..f0719c880b 100644 --- a/godoc-current.txt +++ b/godoc-current.txt @@ -734,6 +734,13 @@ func (cmd *Command) Lineage() []*Command func (cmd *Command) LocalFlagNames() []string LocalFlagNames returns a slice of flag names used in this command. +func (cmd *Command) MarshalJSON() ([]byte, error) + MarshalJSON encodes the command as JSON. The default value of each flag + marked as sensitive (see SensitiveFlag) is left out, so that a secret + default does not end up in exported help. Subcommands are encoded the same + way. Encoding a flag on its own, outside a command, does not leave out its + default value. + func (cmd *Command) NArg() int NArg returns the number of the command line arguments. @@ -1112,10 +1119,6 @@ func (f *FlagBase[T, C, V]) IsSet() bool func (f *FlagBase[T, C, V]) IsVisible() bool IsVisible returns true if the flag is not hidden, otherwise false -func (f *FlagBase[T, C, V]) MarshalJSON() ([]byte, error) - MarshalJSON encodes the flag as JSON. The default value of a sensitive flag - is left out, so that a secret default does not end up in exported help. - func (f *FlagBase[T, C, V]) Names() []string Names returns the names of the flag @@ -1434,10 +1437,11 @@ type SensitiveFlag interface { // IsSensitive returns true if the flag's value must be kept secret IsSensitive() bool } - SensitiveFlag is an interface that allows us to mark flags whose values - are secrets, such as passwords or tokens. The value of a sensitive flag is - not shown in help output, JSON output or error messages, and is returned by - Command.SensitiveValues so that it can be removed from other output. + SensitiveFlag is an interface that allows us to mark flags whose values are + secrets, such as passwords or tokens. The value of a sensitive flag is not + shown in help output, a command's JSON (see Command.MarshalJSON) or error + messages, and is returned by Command.SensitiveValues so that it can be + removed from other output. type Serializer interface { Serialize() string diff --git a/testdata/godoc-v3.x.txt b/testdata/godoc-v3.x.txt index b0c24f1f4d..f0719c880b 100644 --- a/testdata/godoc-v3.x.txt +++ b/testdata/godoc-v3.x.txt @@ -734,6 +734,13 @@ func (cmd *Command) Lineage() []*Command func (cmd *Command) LocalFlagNames() []string LocalFlagNames returns a slice of flag names used in this command. +func (cmd *Command) MarshalJSON() ([]byte, error) + MarshalJSON encodes the command as JSON. The default value of each flag + marked as sensitive (see SensitiveFlag) is left out, so that a secret + default does not end up in exported help. Subcommands are encoded the same + way. Encoding a flag on its own, outside a command, does not leave out its + default value. + func (cmd *Command) NArg() int NArg returns the number of the command line arguments. @@ -1112,10 +1119,6 @@ func (f *FlagBase[T, C, V]) IsSet() bool func (f *FlagBase[T, C, V]) IsVisible() bool IsVisible returns true if the flag is not hidden, otherwise false -func (f *FlagBase[T, C, V]) MarshalJSON() ([]byte, error) - MarshalJSON encodes the flag as JSON. The default value of a sensitive flag - is left out, so that a secret default does not end up in exported help. - func (f *FlagBase[T, C, V]) Names() []string Names returns the names of the flag @@ -1434,10 +1437,11 @@ type SensitiveFlag interface { // IsSensitive returns true if the flag's value must be kept secret IsSensitive() bool } - SensitiveFlag is an interface that allows us to mark flags whose values - are secrets, such as passwords or tokens. The value of a sensitive flag is - not shown in help output, JSON output or error messages, and is returned by - Command.SensitiveValues so that it can be removed from other output. + SensitiveFlag is an interface that allows us to mark flags whose values are + secrets, such as passwords or tokens. The value of a sensitive flag is not + shown in help output, a command's JSON (see Command.MarshalJSON) or error + messages, and is returned by Command.SensitiveValues so that it can be + removed from other output. type Serializer interface { Serialize() string From c7eb7f3ff8a5694d4e5e9f02264a0d451591fcf2 Mon Sep 17 00:00:00 2001 From: Daniel Fox Date: Mon, 16 Nov 2026 13:39:52 -0700 Subject: [PATCH 3/7] Add another test for sensitive flag encoding --- flag_sensitive_test.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/flag_sensitive_test.go b/flag_sensitive_test.go index d565630777..1310f6cccd 100644 --- a/flag_sensitive_test.go +++ b/flag_sensitive_test.go @@ -114,6 +114,19 @@ func TestSensitiveFlagCommandJSON(t *testing.T) { assert.Equal(t, "s3cret-root", token.Value) } +// Masking is done by Command.MarshalJSON, so a sensitive flag encoded on its +// own still shows its default value, but never the value it was set to +func TestSensitiveFlagAloneJSON(t *testing.T) { + f := &StringFlag{Name: "token", Value: "default-s3cret", Sensitive: true} + cmd := &Command{Name: "app", Flags: []Flag{f}} + require.NoError(t, cmd.Run(buildTestContext(t), []string{"app", "--token", "arg-s3cret"})) + + b, err := json.Marshal(f) + require.NoError(t, err) + assert.Contains(t, string(b), `"defaultValue":"default-s3cret"`) + assert.NotContains(t, string(b), "arg-s3cret") +} + // A type that embeds a flag must keep its own fields when encoded, as it // did before sensitive flags were added func TestSensitiveFlagEmbeddedFlagJSON(t *testing.T) { From 11da19205c1a24faabf2198e8377f423397d4084 Mon Sep 17 00:00:00 2001 From: Daniel Fox Date: Mon, 16 Nov 2026 13:44:00 -0700 Subject: [PATCH 4/7] Test and document JSON of types that embed Command --- command.go | 4 ++++ flag_sensitive_test.go | 16 ++++++++++++++++ godoc-current.txt | 4 ++++ testdata/godoc-v3.x.txt | 4 ++++ 4 files changed, 28 insertions(+) diff --git a/command.go b/command.go index 6a1cc7f26c..137d59813a 100644 --- a/command.go +++ b/command.go @@ -700,6 +700,10 @@ type commandJSON Command // default does not end up in exported help. Subcommands are encoded the // same way. Encoding a flag on its own, outside a command, does not leave // out its default value. +// +// A type that embeds a Command gets this method too, so encoding that type +// gives only the Command's fields. Give such a type its own MarshalJSON to +// include its other fields. func (cmd *Command) MarshalJSON() ([]byte, error) { c := *cmd c.Flags = redactFlagsForJSON(c.Flags) diff --git a/flag_sensitive_test.go b/flag_sensitive_test.go index 1310f6cccd..6cb396005b 100644 --- a/flag_sensitive_test.go +++ b/flag_sensitive_test.go @@ -127,6 +127,22 @@ func TestSensitiveFlagAloneJSON(t *testing.T) { assert.NotContains(t, string(b), "arg-s3cret") } +// Known break: Command.MarshalJSON is promoted to a type that embeds a +// Command, so encoding that type leaves out its own fields. Before sensitive +// flags were added they were included. If this test fails, the break is gone +// and the note on Command.MarshalJSON should be removed. +func TestSensitiveFlagEmbeddedCommandJSON(t *testing.T) { + type myCommand struct { + Command + Extra string `json:"extra"` + } + + b, err := json.Marshal(&myCommand{Command: Command{Name: "app"}, Extra: "dropped"}) + require.NoError(t, err) + assert.Contains(t, string(b), `"name":"app"`) + assert.NotContains(t, string(b), "extra") +} + // A type that embeds a flag must keep its own fields when encoded, as it // did before sensitive flags were added func TestSensitiveFlagEmbeddedFlagJSON(t *testing.T) { diff --git a/godoc-current.txt b/godoc-current.txt index f0719c880b..e3e715d25c 100644 --- a/godoc-current.txt +++ b/godoc-current.txt @@ -741,6 +741,10 @@ func (cmd *Command) MarshalJSON() ([]byte, error) way. Encoding a flag on its own, outside a command, does not leave out its default value. + A type that embeds a Command gets this method too, so encoding that type + gives only the Command's fields. Give such a type its own MarshalJSON to + include its other fields. + func (cmd *Command) NArg() int NArg returns the number of the command line arguments. diff --git a/testdata/godoc-v3.x.txt b/testdata/godoc-v3.x.txt index f0719c880b..e3e715d25c 100644 --- a/testdata/godoc-v3.x.txt +++ b/testdata/godoc-v3.x.txt @@ -741,6 +741,10 @@ func (cmd *Command) MarshalJSON() ([]byte, error) way. Encoding a flag on its own, outside a command, does not leave out its default value. + A type that embeds a Command gets this method too, so encoding that type + gives only the Command's fields. Give such a type its own MarshalJSON to + include its other fields. + func (cmd *Command) NArg() int NArg returns the number of the command line arguments. From 17a6c64acbf3d832bf9f3de8585dde37fce4d96b Mon Sep 17 00:00:00 2001 From: Daniel Fox Date: Mon, 16 Nov 2026 14:03:18 -0700 Subject: [PATCH 5/7] Commit the example --- examples_test.go | 55 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/examples_test.go b/examples_test.go index 87fc2bef8e..f3dcff0972 100644 --- a/examples_test.go +++ b/examples_test.go @@ -3,6 +3,8 @@ package cli_test import ( "context" "fmt" + "io" + "log/slog" "net/mail" "os" "strings" @@ -490,3 +492,56 @@ func ExampleCommand_Walk_visibleTree() { // list // version } + +// redactingWriter replaces secrets in everything written to w. Any logger +// that writes to an io.Writer can use it, such as log, log/slog or zap. +type redactingWriter struct { + w io.Writer + r *strings.Replacer +} + +func newRedactingWriter(w io.Writer, cmd *cli.Command) *redactingWriter { + // SensitiveValues sorts longest first, so a secret that contains + // another is replaced as a whole + var oldnew []string + for _, v := range cmd.SensitiveValues() { + oldnew = append(oldnew, v, "[REDACTED]") + } + return &redactingWriter{w: w, r: strings.NewReplacer(oldnew...)} +} + +func (rw *redactingWriter) Write(p []byte) (int, error) { + if _, err := io.WriteString(rw.w, rw.r.Replace(string(p))); err != nil { + return 0, err + } + return len(p), nil +} + +func ExampleCommand_SensitiveValues() { + cmd := &cli.Command{ + Name: "deploy", + Flags: []cli.Flag{ + &cli.StringFlag{Name: "token", Sensitive: true}, + &cli.StringFlag{Name: "region"}, + }, + Action: func(_ context.Context, cmd *cli.Command) error { + // Build the logger after parsing, once the values are known + logger := slog.New(slog.NewTextHandler(newRedactingWriter(os.Stdout, cmd), &slog.HandlerOptions{ + // leave out the time so the output below is stable + ReplaceAttr: func(_ []string, a slog.Attr) slog.Attr { + if a.Key == slog.TimeKey { + return slog.Attr{} + } + return a + }, + })) + + logger.Info("deploying", "region", cmd.String("region"), "auth", "Bearer "+cmd.String("token")) + return nil + }, + } + + _ = cmd.Run(context.Background(), []string{"deploy", "--token", "s3cret", "--region", "eu-west-1"}) + // Output: + // level=INFO msg=deploying region=eu-west-1 auth="Bearer [REDACTED]" +} From 4f755ff527abf306ac14d8ddb31a2a47a9a458bc Mon Sep 17 00:00:00 2001 From: Daniel Fox Date: Tue, 17 Nov 2026 10:04:26 -0700 Subject: [PATCH 6/7] Copy pointer defaults of sensitive flags instead of redacting JSON Command.MarshalJSON kept encoding/json in every binary that uses help templates, as text/template makes the linker keep all exported methods. This grew the example binary from 2.3MB to 2.7MB, over the size limit. Remove it, and instead have a sensitive flag whose value is a pointer (GenericFlag, TextFlag) parse into a shallow copy of its default value. Its Value field then keeps the default, so encoding a command or a flag as JSON never shows the value the flag was set to. Co-Authored-By: Claude Opus 5.5 --- command.go | 34 ------------ flag.go | 40 ++++---------- flag_impl.go | 40 +++++++++----- flag_sensitive_test.go | 117 +++++++++++++++++++++++++++------------- godoc-current.txt | 32 ++++++----- testdata/godoc-v3.x.txt | 32 ++++++----- 6 files changed, 149 insertions(+), 146 deletions(-) diff --git a/command.go b/command.go index 137d59813a..c5642e4064 100644 --- a/command.go +++ b/command.go @@ -2,7 +2,6 @@ package cli import ( "context" - "encoding/json" "fmt" "io" "slices" @@ -691,39 +690,6 @@ func (cmd *Command) FlagNames() []string { return names } -// commandJSON has the fields of Command but not its methods, so that -// MarshalJSON can encode it without calling itself -type commandJSON Command - -// MarshalJSON encodes the command as JSON. The default value of each flag -// marked as sensitive (see [SensitiveFlag]) is left out, so that a secret -// default does not end up in exported help. Subcommands are encoded the -// same way. Encoding a flag on its own, outside a command, does not leave -// out its default value. -// -// A type that embeds a Command gets this method too, so encoding that type -// gives only the Command's fields. Give such a type its own MarshalJSON to -// include its other fields. -func (cmd *Command) MarshalJSON() ([]byte, error) { - c := *cmd - c.Flags = redactFlagsForJSON(c.Flags) - - if len(c.MutuallyExclusiveFlags) > 0 { - groups := make([]MutuallyExclusiveFlags, len(c.MutuallyExclusiveFlags)) - for i, g := range c.MutuallyExclusiveFlags { - opts := make([][]Flag, len(g.Flags)) - for j, opt := range g.Flags { - opts[j] = redactFlagsForJSON(opt) - } - g.Flags = opts - groups[i] = g - } - c.MutuallyExclusiveFlags = groups - } - - return json.Marshal((*commandJSON)(&c)) -} - // SensitiveValues returns the current values of all flags marked as // sensitive (see [SensitiveFlag]) in this command and all of its parent // commands, so that they can be removed from logs or other output. diff --git a/flag.go b/flag.go index 5f4850602d..39f8e8854c 100644 --- a/flag.go +++ b/flag.go @@ -130,9 +130,18 @@ type DeprecatedFlag interface { // SensitiveFlag is an interface that allows us to mark flags whose values // are secrets, such as passwords or tokens. The value of a sensitive flag -// is not shown in help output, a command's JSON (see [Command.MarshalJSON]) -// or error messages, and is returned by +// is not shown in help output or error messages, and is returned by // [Command.SensitiveValues] so that it can be removed from other output. +// +// Encoding a command or a flag as JSON includes the default value of a +// sensitive flag, but never the value it was set to. To keep this so for +// flag types whose value is a pointer, such as [GenericFlag] and [TextFlag], +// a sensitive flag parses into a shallow copy of its default value rather +// than into the default value itself, so the object given as the default +// value keeps its default. Read the parsed value with methods such as +// [Command.Generic] and [Command.Text], or through Destination. As the copy +// is shallow, a value whose Set method writes into a map, slice or pointer +// that it shares with the default value also changes the default value. type SensitiveFlag interface { // IsSensitive returns true if the flag's value must be kept secret IsSensitive() bool @@ -243,33 +252,6 @@ type sensitivePartser interface { sensitiveParts(val string) []string } -// jsonRedacter is implemented by flags that can return a copy of themselves -// without their default value, for encoding a sensitive flag as JSON -type jsonRedacter interface { - redactedForJSON() Flag -} - -// redactFlagsForJSON returns flags with each sensitive flag replaced by a -// copy without its default value. flags is returned as is if no flag -// needs replacing. -func redactFlagsForJSON(flags []Flag) []Flag { - var out []Flag - for i, f := range flags { - r, ok := f.(jsonRedacter) - if !ok || !isSensitive(f) { - continue - } - if out == nil { - out = slices.Clone(flags) - } - out[i] = r.redactedForJSON() - } - if out == nil { - return flags - } - return out -} - // redactValue replaces each occurrence of val, and of each part of val that // an error message may quote on its own, in s if f is sensitive func redactValue(f Flag, s, val string) string { diff --git a/flag_impl.go b/flag_impl.go index 4f0a2ffe12..991eddb99e 100644 --- a/flag_impl.go +++ b/flag_impl.go @@ -63,7 +63,7 @@ type FlagBase[T any, C any, VC ValueCreator[T, C]] struct { Sources ValueSourceChain `json:"-"` // sources to load flag value from Required bool `json:"required"` // whether the flag is required or not Hidden bool `json:"hidden"` // whether to hide the flag in help output - Sensitive bool `json:"sensitive"` // whether the value is a secret that must not be shown in help output, JSON or errors + Sensitive bool `json:"sensitive"` // whether the value is a secret that must not be shown in help output or errors Deprecated string `json:"deprecated"` // deprecation message, if set a warning is printed when the flag is set Local bool `json:"local"` // whether the flag is only for this command and not accepted by subcommands Value T `json:"defaultValue"` // default value for this flag if not set by from any source @@ -202,10 +202,35 @@ func (f *FlagBase[T, C, V]) setMultiValueParsingConfig(c multiValueParsingConfig // newValue creates the flag's value holding the default Value. func (f *FlagBase[T, C, V]) newValue() Value { + val := f.Value + if f.Sensitive { + val = cloneDefault(val) + } if f.Destination == nil { - return f.creator.Create(f.Value, new(T), f.Config) + return f.creator.Create(val, new(T), f.Config) } - return f.creator.Create(f.Value, f.Destination, f.Config) + return f.creator.Create(val, f.Destination, f.Config) +} + +// cloneDefault returns a shallow copy of v when T is an interface type +// holding a non-nil pointer, as for GenericFlag and TextFlag. Parsing writes +// through that pointer, so without a copy the flag's Value field would be +// changed to the parsed value, and encoding the flag would show it. +func cloneDefault[T any](v T) T { + if reflect.TypeFor[T]().Kind() != reflect.Interface { + return v + } + rv := reflect.ValueOf(v) + if !rv.IsValid() || rv.Kind() != reflect.Pointer || rv.IsNil() { + return v + } + c := reflect.New(rv.Type().Elem()) + c.Elem().Set(rv.Elem()) + out, ok := c.Interface().(T) + if !ok { + return v + } + return out } func (f *FlagBase[T, C, V]) getTypedValue() T { @@ -337,15 +362,6 @@ func (f *FlagBase[T, C, V]) IsSensitive() bool { return f.Sensitive } -// redactedForJSON returns a copy of the flag without its default value, for -// Command.MarshalJSON to encode in place of a sensitive flag -func (f *FlagBase[T, C, V]) redactedForJSON() Flag { - c := *f - var zero T - c.Value = zero - return &c -} - // sensitiveParts returns val and, for slice and map flags, each item of val // and each map value, as an error message may quote any of them on its own func (f *FlagBase[T, C, V]) sensitiveParts(val string) []string { diff --git a/flag_sensitive_test.go b/flag_sensitive_test.go index 6cb396005b..c29a9a1705 100644 --- a/flag_sensitive_test.go +++ b/flag_sensitive_test.go @@ -85,64 +85,107 @@ func TestSensitiveFlagRedactsItemsInErrors(t *testing.T) { } } -func TestSensitiveFlagCommandJSON(t *testing.T) { - token := &StringFlag{Name: "token", Value: "s3cret-root", Sensitive: true} - user := &StringFlag{Name: "user", Value: "bob"} +// Encoding as JSON shows the default value of a sensitive flag, which is in +// the source or binary anyway, but never the value it was set to +func TestSensitiveFlagJSONHasNoSetValue(t *testing.T) { + gen := &sensitiveGeneric{s: "default-gen"} cmd := &Command{ - Name: "app", - Flags: []Flag{token, user}, - Commands: []*Command{{ - Name: "sub", - Flags: []Flag{&IntFlag{Name: "pin", Value: 4242, Sensitive: true}}, - MutuallyExclusiveFlags: []MutuallyExclusiveFlags{{ - Flags: [][]Flag{{&StringFlag{Name: "key", Value: "s3cret-group", Sensitive: true}}}, - }}, - }}, + Name: "app", + Flags: []Flag{ + &StringFlag{Name: "str", Value: "default-str", Sensitive: true}, + &StringSliceFlag{Name: "sl", Value: []string{"default-sl"}, Sensitive: true}, + &StringMapFlag{Name: "map", Value: map[string]string{"k": "default-map"}, Sensitive: true}, + &GenericFlag{Name: "gen", Value: gen, Sensitive: true}, + &TextFlag{Name: "txt", Value: &sensitiveText{s: "default-txt"}, Sensitive: true}, + }, } + require.NoError(t, cmd.Run(buildTestContext(t), []string{ + "app", + "--str", "set-s3cret-str", + "--sl", "set-s3cret-sl", + "--map", "k=set-s3cret-map", + "--gen", "set-s3cret-gen", + "--txt", "set-s3cret-txt", + })) b, err := json.Marshal(cmd) require.NoError(t, err) out := string(b) - assert.NotContains(t, out, "s3cret-root") - assert.NotContains(t, out, "4242") - assert.NotContains(t, out, "s3cret-group") - assert.Contains(t, out, `"sensitive":true`) - assert.Contains(t, out, `"defaultValue":"bob"`) - - // encoding must not change the command's own flags - assert.Same(t, token, cmd.Flags[0]) - assert.Equal(t, "s3cret-root", token.Value) + assert.NotContains(t, out, "set-s3cret") + for _, def := range []string{"default-str", "default-sl", "default-map", "default-gen", "default-txt"} { + assert.Contains(t, out, def) + } + + for _, f := range cmd.Flags { + b, err := json.Marshal(f) + require.NoError(t, err) + assert.NotContains(t, string(b), "set-s3cret") + } } -// Masking is done by Command.MarshalJSON, so a sensitive flag encoded on its -// own still shows its default value, but never the value it was set to -func TestSensitiveFlagAloneJSON(t *testing.T) { - f := &StringFlag{Name: "token", Value: "default-s3cret", Sensitive: true} - cmd := &Command{Name: "app", Flags: []Flag{f}} - require.NoError(t, cmd.Run(buildTestContext(t), []string{"app", "--token", "arg-s3cret"})) +// A sensitive GenericFlag or TextFlag parses into a copy of its default +// value, so the parsed value is read from the command or Destination and +// the caller's default object is left as it was +func TestSensitiveFlagPointerValueIsCopied(t *testing.T) { + gen := &sensitiveGeneric{s: "default-gen"} + txt := &sensitiveText{s: "default-txt"} + var dest TextMarshalUnmarshaler - b, err := json.Marshal(f) - require.NoError(t, err) - assert.Contains(t, string(b), `"defaultValue":"default-s3cret"`) - assert.NotContains(t, string(b), "arg-s3cret") + cmd := &Command{ + Name: "app", + Flags: []Flag{ + &GenericFlag{Name: "gen", Value: gen, Sensitive: true}, + &TextFlag{Name: "txt", Value: txt, Destination: &dest, Sensitive: true}, + }, + } + require.NoError(t, cmd.Run(buildTestContext(t), []string{"app", "--gen", "set-gen", "--txt", "set-txt"})) + + assert.Equal(t, "default-gen", gen.s) + assert.Equal(t, "default-txt", txt.s) + assert.Equal(t, "set-gen", cmd.Generic("gen").String()) + assert.Equal(t, &sensitiveText{s: "set-txt"}, cmd.Text("txt")) + assert.Equal(t, &sensitiveText{s: "set-txt"}, dest) + assert.Contains(t, cmd.SensitiveValues(), "set-gen") +} + +// A flag that is not sensitive still parses into its default value object +func TestNotSensitiveFlagPointerValueIsShared(t *testing.T) { + gen := &sensitiveGeneric{s: "default-gen"} + cmd := &Command{ + Name: "app", + Flags: []Flag{&GenericFlag{Name: "gen", Value: gen}}, + } + require.NoError(t, cmd.Run(buildTestContext(t), []string{"app", "--gen", "set-gen"})) + assert.Equal(t, "set-gen", gen.s) } -// Known break: Command.MarshalJSON is promoted to a type that embeds a -// Command, so encoding that type leaves out its own fields. Before sensitive -// flags were added they were included. If this test fails, the break is gone -// and the note on Command.MarshalJSON should be removed. +// A type that embeds a Command must keep its own fields when encoded func TestSensitiveFlagEmbeddedCommandJSON(t *testing.T) { type myCommand struct { Command Extra string `json:"extra"` } - b, err := json.Marshal(&myCommand{Command: Command{Name: "app"}, Extra: "dropped"}) + b, err := json.Marshal(&myCommand{Command: Command{Name: "app"}, Extra: "kept"}) require.NoError(t, err) assert.Contains(t, string(b), `"name":"app"`) - assert.NotContains(t, string(b), "extra") + assert.Contains(t, string(b), `"extra":"kept"`) +} + +type sensitiveGeneric struct{ s string } + +func (g *sensitiveGeneric) Set(s string) error { g.s = s; return nil } +func (g *sensitiveGeneric) String() string { return g.s } +func (g *sensitiveGeneric) Get() any { return g } +func (g *sensitiveGeneric) MarshalJSON() ([]byte, error) { + return json.Marshal(g.s) } +type sensitiveText struct{ s string } + +func (x *sensitiveText) MarshalText() ([]byte, error) { return []byte(x.s), nil } +func (x *sensitiveText) UnmarshalText(b []byte) error { x.s = string(b); return nil } + // A type that embeds a flag must keep its own fields when encoded, as it // did before sensitive flags were added func TestSensitiveFlagEmbeddedFlagJSON(t *testing.T) { diff --git a/godoc-current.txt b/godoc-current.txt index e3e715d25c..62d0c9a1bc 100644 --- a/godoc-current.txt +++ b/godoc-current.txt @@ -734,17 +734,6 @@ func (cmd *Command) Lineage() []*Command func (cmd *Command) LocalFlagNames() []string LocalFlagNames returns a slice of flag names used in this command. -func (cmd *Command) MarshalJSON() ([]byte, error) - MarshalJSON encodes the command as JSON. The default value of each flag - marked as sensitive (see SensitiveFlag) is left out, so that a secret - default does not end up in exported help. Subcommands are encoded the same - way. Encoding a flag on its own, outside a command, does not leave out its - default value. - - A type that embeds a Command gets this method too, so encoding that type - gives only the Command's fields. Give such a type its own MarshalJSON to - include its other fields. - func (cmd *Command) NArg() int NArg returns the number of the command line arguments. @@ -1052,7 +1041,7 @@ type FlagBase[T any, C any, VC ValueCreator[T, C]] struct { Sources ValueSourceChain `json:"-"` // sources to load flag value from Required bool `json:"required"` // whether the flag is required or not Hidden bool `json:"hidden"` // whether to hide the flag in help output - Sensitive bool `json:"sensitive"` // whether the value is a secret that must not be shown in help output, JSON or errors + Sensitive bool `json:"sensitive"` // whether the value is a secret that must not be shown in help output or errors Deprecated string `json:"deprecated"` // deprecation message, if set a warning is printed when the flag is set Local bool `json:"local"` // whether the flag is only for this command and not accepted by subcommands Value T `json:"defaultValue"` // default value for this flag if not set by from any source @@ -1441,11 +1430,20 @@ type SensitiveFlag interface { // IsSensitive returns true if the flag's value must be kept secret IsSensitive() bool } - SensitiveFlag is an interface that allows us to mark flags whose values are - secrets, such as passwords or tokens. The value of a sensitive flag is not - shown in help output, a command's JSON (see Command.MarshalJSON) or error - messages, and is returned by Command.SensitiveValues so that it can be - removed from other output. + SensitiveFlag is an interface that allows us to mark flags whose values + are secrets, such as passwords or tokens. The value of a sensitive + flag is not shown in help output or error messages, and is returned by + Command.SensitiveValues so that it can be removed from other output. + + Encoding a command or a flag as JSON includes the default value of a + sensitive flag, but never the value it was set to. To keep this so for + flag types whose value is a pointer, such as GenericFlag and TextFlag, + a sensitive flag parses into a shallow copy of its default value rather + than into the default value itself, so the object given as the default + value keeps its default. Read the parsed value with methods such as + Command.Generic and Command.Text, or through Destination. As the copy is + shallow, a value whose Set method writes into a map, slice or pointer that + it shares with the default value also changes the default value. type Serializer interface { Serialize() string diff --git a/testdata/godoc-v3.x.txt b/testdata/godoc-v3.x.txt index e3e715d25c..62d0c9a1bc 100644 --- a/testdata/godoc-v3.x.txt +++ b/testdata/godoc-v3.x.txt @@ -734,17 +734,6 @@ func (cmd *Command) Lineage() []*Command func (cmd *Command) LocalFlagNames() []string LocalFlagNames returns a slice of flag names used in this command. -func (cmd *Command) MarshalJSON() ([]byte, error) - MarshalJSON encodes the command as JSON. The default value of each flag - marked as sensitive (see SensitiveFlag) is left out, so that a secret - default does not end up in exported help. Subcommands are encoded the same - way. Encoding a flag on its own, outside a command, does not leave out its - default value. - - A type that embeds a Command gets this method too, so encoding that type - gives only the Command's fields. Give such a type its own MarshalJSON to - include its other fields. - func (cmd *Command) NArg() int NArg returns the number of the command line arguments. @@ -1052,7 +1041,7 @@ type FlagBase[T any, C any, VC ValueCreator[T, C]] struct { Sources ValueSourceChain `json:"-"` // sources to load flag value from Required bool `json:"required"` // whether the flag is required or not Hidden bool `json:"hidden"` // whether to hide the flag in help output - Sensitive bool `json:"sensitive"` // whether the value is a secret that must not be shown in help output, JSON or errors + Sensitive bool `json:"sensitive"` // whether the value is a secret that must not be shown in help output or errors Deprecated string `json:"deprecated"` // deprecation message, if set a warning is printed when the flag is set Local bool `json:"local"` // whether the flag is only for this command and not accepted by subcommands Value T `json:"defaultValue"` // default value for this flag if not set by from any source @@ -1441,11 +1430,20 @@ type SensitiveFlag interface { // IsSensitive returns true if the flag's value must be kept secret IsSensitive() bool } - SensitiveFlag is an interface that allows us to mark flags whose values are - secrets, such as passwords or tokens. The value of a sensitive flag is not - shown in help output, a command's JSON (see Command.MarshalJSON) or error - messages, and is returned by Command.SensitiveValues so that it can be - removed from other output. + SensitiveFlag is an interface that allows us to mark flags whose values + are secrets, such as passwords or tokens. The value of a sensitive + flag is not shown in help output or error messages, and is returned by + Command.SensitiveValues so that it can be removed from other output. + + Encoding a command or a flag as JSON includes the default value of a + sensitive flag, but never the value it was set to. To keep this so for + flag types whose value is a pointer, such as GenericFlag and TextFlag, + a sensitive flag parses into a shallow copy of its default value rather + than into the default value itself, so the object given as the default + value keeps its default. Read the parsed value with methods such as + Command.Generic and Command.Text, or through Destination. As the copy is + shallow, a value whose Set method writes into a map, slice or pointer that + it shares with the default value also changes the default value. type Serializer interface { Serialize() string From 554f0267df8b3f49cfc379378311ed20ffff8e95 Mon Sep 17 00:00:00 2001 From: Daniel Fox Date: Tue, 17 Nov 2026 10:18:11 -0700 Subject: [PATCH 7/7] Copy sensitive text flag defaults through their text form A shallow copy of a sensitive flag's default shares any maps, slices or pointers inside it, so parsing could still write the set value into the default. Copy a value that implements encoding.TextMarshaler and encoding.TextUnmarshaler, as every TextFlag value does, by unmarshaling its text form into a new zero value. Fall back to a shallow copy for other values, or when the text form cannot be read back. Co-Authored-By: Claude Opus 5.5 --- flag.go | 11 ++++++--- flag_impl.go | 33 +++++++++++++++++++++---- flag_sensitive_test.go | 53 ++++++++++++++++++++++++++++++++++++++++- godoc-current.txt | 10 +++++--- testdata/godoc-v3.x.txt | 10 +++++--- 5 files changed, 102 insertions(+), 15 deletions(-) diff --git a/flag.go b/flag.go index 39f8e8854c..882ab8c368 100644 --- a/flag.go +++ b/flag.go @@ -139,9 +139,14 @@ type DeprecatedFlag interface { // a sensitive flag parses into a shallow copy of its default value rather // than into the default value itself, so the object given as the default // value keeps its default. Read the parsed value with methods such as -// [Command.Generic] and [Command.Text], or through Destination. As the copy -// is shallow, a value whose Set method writes into a map, slice or pointer -// that it shares with the default value also changes the default value. +// [Command.Generic] and [Command.Text], or through Destination. +// +// A value that implements [encoding.TextMarshaler] and +// [encoding.TextUnmarshaler], as every TextFlag value does, is copied +// deeply: its text form is unmarshaled into a new zero value. Any other +// value is copied shallowly, so a value whose Set method writes into a map, +// slice or pointer that it shares with the default value also changes the +// default value. type SensitiveFlag interface { // IsSensitive returns true if the flag's value must be kept secret IsSensitive() bool diff --git a/flag_impl.go b/flag_impl.go index 991eddb99e..8407cd9fd2 100644 --- a/flag_impl.go +++ b/flag_impl.go @@ -212,10 +212,16 @@ func (f *FlagBase[T, C, V]) newValue() Value { return f.creator.Create(val, f.Destination, f.Config) } -// cloneDefault returns a shallow copy of v when T is an interface type -// holding a non-nil pointer, as for GenericFlag and TextFlag. Parsing writes -// through that pointer, so without a copy the flag's Value field would be -// changed to the parsed value, and encoding the flag would show it. +// cloneDefault returns a copy of v when T is an interface type holding a +// non-nil pointer, as for GenericFlag and TextFlag. Parsing writes through +// that pointer, so without a copy the flag's Value field would be changed +// to the parsed value, and encoding the flag would show it. +// +// A value that can marshal itself to and from text, such as the value of a +// TextFlag, is copied deeply by unmarshaling its text form into a new zero +// value, so that the copy shares no maps, slices or pointers with v. Any +// other value, or one whose text form cannot be read back, is copied +// shallowly. func cloneDefault[T any](v T) T { if reflect.TypeFor[T]().Kind() != reflect.Interface { return v @@ -225,7 +231,9 @@ func cloneDefault[T any](v T) T { return v } c := reflect.New(rv.Type().Elem()) - c.Elem().Set(rv.Elem()) + if !copyText(rv, c) { + c.Elem().Set(rv.Elem()) + } out, ok := c.Interface().(T) if !ok { return v @@ -233,6 +241,21 @@ func cloneDefault[T any](v T) T { return out } +// copyText unmarshals the text form of src into dst, a new zero value of +// the same type, and reports whether it succeeded +func copyText(src, dst reflect.Value) bool { + m, ok := src.Interface().(TextMarshalUnmarshaler) + if !ok { + return false + } + text, err := m.MarshalText() + if err != nil { + return false + } + u, ok := dst.Interface().(TextMarshalUnmarshaler) + return ok && u.UnmarshalText(text) == nil +} + func (f *FlagBase[T, C, V]) getTypedValue() T { value := f.value.Get() if typed, ok := value.(T); ok { diff --git a/flag_sensitive_test.go b/flag_sensitive_test.go index c29a9a1705..140643e532 100644 --- a/flag_sensitive_test.go +++ b/flag_sensitive_test.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "fmt" + "strings" "testing" "github.com/stretchr/testify/assert" @@ -148,6 +149,38 @@ func TestSensitiveFlagPointerValueIsCopied(t *testing.T) { assert.Contains(t, cmd.SensitiveValues(), "set-gen") } +// A sensitive TextFlag is copied through its text form, so a value that +// keeps its state in a map does not share that map with the default value +func TestSensitiveTextFlagIsCopiedDeeply(t *testing.T) { + def := &sensitiveMapText{m: map[string]string{"v": "default-txt"}} + cmd := &Command{ + Name: "app", + Flags: []Flag{&TextFlag{Name: "txt", Value: def, Sensitive: true}}, + } + require.NoError(t, cmd.Run(buildTestContext(t), []string{"app", "--txt", "set-s3cret"})) + + assert.Equal(t, "default-txt", def.m["v"]) + assert.Equal(t, &sensitiveMapText{m: map[string]string{"v": "set-s3cret"}}, cmd.Text("txt")) + + b, err := json.Marshal(cmd) + require.NoError(t, err) + assert.NotContains(t, string(b), "set-s3cret") +} + +// A value whose text form cannot be read back is still copied, shallowly +func TestSensitiveTextFlagFallsBackToShallowCopy(t *testing.T) { + def := &sensitiveText{s: "unreadable-default"} + cmd := &Command{ + Name: "app", + Flags: []Flag{&TextFlag{Name: "txt", Value: def, Sensitive: true}}, + } + require.NoError(t, cmd.Run(buildTestContext(t), []string{"app"})) + + got := cmd.Text("txt") + assert.NotSame(t, def, got) + assert.Equal(t, "unreadable-default", got.(*sensitiveText).s) +} + // A flag that is not sensitive still parses into its default value object func TestNotSensitiveFlagPointerValueIsShared(t *testing.T) { gen := &sensitiveGeneric{s: "default-gen"} @@ -184,7 +217,25 @@ func (g *sensitiveGeneric) MarshalJSON() ([]byte, error) { type sensitiveText struct{ s string } func (x *sensitiveText) MarshalText() ([]byte, error) { return []byte(x.s), nil } -func (x *sensitiveText) UnmarshalText(b []byte) error { x.s = string(b); return nil } +func (x *sensitiveText) UnmarshalText(b []byte) error { + if strings.HasPrefix(string(b), "unreadable") { + return fmt.Errorf("cannot read %q", b) + } + x.s = string(b) + return nil +} + +// sensitiveMapText keeps its text in a map, which a shallow copy would share +type sensitiveMapText struct{ m map[string]string } + +func (x *sensitiveMapText) MarshalText() ([]byte, error) { return []byte(x.m["v"]), nil } +func (x *sensitiveMapText) UnmarshalText(b []byte) error { + if x.m == nil { + x.m = map[string]string{} + } + x.m["v"] = string(b) + return nil +} // A type that embeds a flag must keep its own fields when encoded, as it // did before sensitive flags were added diff --git a/godoc-current.txt b/godoc-current.txt index 62d0c9a1bc..0ebb99b0f4 100644 --- a/godoc-current.txt +++ b/godoc-current.txt @@ -1441,9 +1441,13 @@ type SensitiveFlag interface { a sensitive flag parses into a shallow copy of its default value rather than into the default value itself, so the object given as the default value keeps its default. Read the parsed value with methods such as - Command.Generic and Command.Text, or through Destination. As the copy is - shallow, a value whose Set method writes into a map, slice or pointer that - it shares with the default value also changes the default value. + Command.Generic and Command.Text, or through Destination. + + A value that implements encoding.TextMarshaler and encoding.TextUnmarshaler, + as every TextFlag value does, is copied deeply: its text form is unmarshaled + into a new zero value. Any other value is copied shallowly, so a value + whose Set method writes into a map, slice or pointer that it shares with the + default value also changes the default value. type Serializer interface { Serialize() string diff --git a/testdata/godoc-v3.x.txt b/testdata/godoc-v3.x.txt index 62d0c9a1bc..0ebb99b0f4 100644 --- a/testdata/godoc-v3.x.txt +++ b/testdata/godoc-v3.x.txt @@ -1441,9 +1441,13 @@ type SensitiveFlag interface { a sensitive flag parses into a shallow copy of its default value rather than into the default value itself, so the object given as the default value keeps its default. Read the parsed value with methods such as - Command.Generic and Command.Text, or through Destination. As the copy is - shallow, a value whose Set method writes into a map, slice or pointer that - it shares with the default value also changes the default value. + Command.Generic and Command.Text, or through Destination. + + A value that implements encoding.TextMarshaler and encoding.TextUnmarshaler, + as every TextFlag value does, is copied deeply: its text form is unmarshaled + into a new zero value. Any other value is copied shallowly, so a value + whose Set method writes into a map, slice or pointer that it shares with the + default value also changes the default value. type Serializer interface { Serialize() string