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/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]" +} diff --git a/flag.go b/flag.go index 7886b93a2c..882ab8c368 100644 --- a/flag.go +++ b/flag.go @@ -128,6 +128,30 @@ 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 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. +// +// 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 +} + // 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 +242,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..8407cd9fd2 100644 --- a/flag_impl.go +++ b/flag_impl.go @@ -63,6 +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 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 +178,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), ) } @@ -201,10 +202,58 @@ 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(val, f.Destination, f.Config) +} + +// 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 + } + rv := reflect.ValueOf(v) + if !rv.IsValid() || rv.Kind() != reflect.Pointer || rv.IsNil() { + return v + } + c := reflect.New(rv.Type().Elem()) + if !copyText(rv, c) { + c.Elem().Set(rv.Elem()) + } + out, ok := c.Interface().(T) + if !ok { + return v + } + 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 } - return f.creator.Create(f.Value, f.Destination, f.Config) + u, ok := dst.Interface().(TextMarshalUnmarshaler) + return ok && u.UnmarshalText(text) == nil } func (f *FlagBase[T, C, V]) getTypedValue() T { @@ -331,6 +380,43 @@ 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 +} + +// 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..140643e532 --- /dev/null +++ b/flag_sensitive_test.go @@ -0,0 +1,294 @@ +package cli + +import ( + "context" + "encoding/json" + "fmt" + "strings" + "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") + }) + } +} + +// 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{ + &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, "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") + } +} + +// 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 + + 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 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"} + 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) +} + +// 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: "kept"}) + require.NoError(t, err) + assert.Contains(t, string(b), `"name":"app"`) + 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 { + 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 +func TestSensitiveFlagEmbeddedFlagJSON(t *testing.T) { + type myFlag struct { + StringFlag + Extra string `json:"extra"` + } + + b, err := json.Marshal(&myFlag{StringFlag: StringFlag{Name: "n"}, Extra: "kept"}) + require.NoError(t, err) + assert.Contains(t, string(b), `"extra":"kept"`) + assert.Contains(t, string(b), `"name":"n"`) +} + +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..0ebb99b0f4 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 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,6 +1103,9 @@ 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 @@ -1413,6 +1426,29 @@ 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 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. + + 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 b6338ec021..0ebb99b0f4 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 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,6 +1103,9 @@ 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 @@ -1413,6 +1426,29 @@ 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 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. + + 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 }