Skip to content

feat: add 'sensitive' flags implementation - #2546

Open
danudey wants to merge 7 commits into
urfave:mainfrom
danudey:sensitive-flags
Open

danudey wants to merge 7 commits into
urfave:mainfrom
danudey:sensitive-flags

Conversation

@danudey

@danudey danudey commented Nov 16, 2026 •

Copy link
Copy Markdown

What type of PR is this?

  • feature

What this PR does / why we need it:

This PR adds the ability to mark a flag as 'sensitive' to prevent its value from being printed or returned by any function.

The idea for the feature came from my interest in developing a separate feature, which would allow a program to print a "canonical" command; since cli supports reading values from --cli-flags and ENV_VARS, I wanted to be able to have
debug builds print out a full CLI (progname --foo bar --baz bonk) by combining together all of the provided values from all provided sources into one version so that an identical command could be run e.g. outside of CI, or so that CI runs
could print all the (raw) parameters they're using for debugging purposes.

This necessitated determining which values were secret or sensitive, which I implemented before realizing that the same feature is described in the v4 design doc

We also add one function of note: (*Command).SensitiveValues; this function returns the current value of all Sensitive flags from this command and all subcommands; this is counterintuitive, but the goal is to provide a way for programs to know what values are sensitive and should be excluded from printing.

A new example ExampleCommand_SensitiveValues in examples_test.go implements an example RedactingWriter which can be used to filter secrets out of log lines automatically before they are printed.

It was considered to add this functionality directly (i.e. add (*Command).ReplaceSensitive or (*Command).RedactingWriter utility functions) but that feels like scope creep and might not cover common use cases; providing access to SensitiveValues directly allows for anyone to implement redaction as they wish, or to implement any other functionality (e.g. matching
against a list of known-bad tokens, hashing the output instead, replacing the values with ***** of the same length, etc).

Which issue(s) this PR fixes:

N/A (I can't find any for this feature)

Special notes for your reviewer:

The main thing to be aware of is that we were not able to mask values in all circumstances, but the exception is pretty niche: when encoding a Flag directly to JSON rather than encoding Command, the Flag's default value is leaked in the resulting JSON.

In other words, if a developer chooses to encode a sensitive Flag as JSON directly, the default value of a that flag can be leaked. It's my opinion that the default value of a flag, even one marked as 'sensitive', should probably not be considered sensitive in most cases; the value will appear if strings is run on the binary, and will also appear in the source code or linker flags of the binary as well.

Testing

There are 10 test functions, one of which has three sub-cases, for a total of 12 tests for this functionality. The existing unit tests all pass unchaged as well.

I also ran apidiff between this branch and current master and it reports no incompatible changes.

apidiff analysis from d5c06cb..11da192
apidiff report: github.com/urfave/cli/v3
base: d5c06cb (Merge pull request #2536 from urfave/dependabot/pip/python-packages-1e57fd124c)
head: 11da192 (Test and document JSON of types that embed Command)
tool: golang.org/x/exp v0.0.0-20261113113407-e3970619a1a4

Commands:
  git worktree add base d5c06cb
  (cd base && apidiff -m -w old.export github.com/urfave/cli/v3)
  apidiff -m -w new.export github.com/urfave/cli/v3
  apidiff -m -incompatible old.export new.export
  apidiff -m old.export new.export

== Incompatible changes (apidiff -m -incompatible) ==
(none)

== All changes (apidiff -m) ==
Compatible changes:
- (*Command).MarshalJSON: added
- (*Command).SensitiveValues: added
- (*FlagBase[T, C, V]).IsSensitive: added
- (*FlagBase[TextMarshalUnmarshaler, StringConfig, textValue]).IsSensitive: added
- (*FlagBase[Value, NoConfig, genericValue]).IsSensitive: added
- (*FlagBase[[]float32, NoConfig, Float32Slice]).IsSensitive: added
- (*FlagBase[[]float64, NoConfig, Float64Slice]).IsSensitive: added
- (*FlagBase[[]int, IntegerConfig, IntSlice]).IsSensitive: added
- (*FlagBase[[]int16, IntegerConfig, Int16Slice]).IsSensitive: added
- (*FlagBase[[]int32, IntegerConfig, Int32Slice]).IsSensitive: added
- (*FlagBase[[]int64, IntegerConfig, Int64Slice]).IsSensitive: added
- (*FlagBase[[]int8, IntegerConfig, Int8Slice]).IsSensitive: added
- (*FlagBase[[]string, StringConfig, StringSlice]).IsSensitive: added
- (*FlagBase[[]uint, IntegerConfig, UintSlice]).IsSensitive: added
- (*FlagBase[[]uint16, IntegerConfig, Uint16Slice]).IsSensitive: added
- (*FlagBase[[]uint32, IntegerConfig, Uint32Slice]).IsSensitive: added
- (*FlagBase[[]uint64, IntegerConfig, Uint64Slice]).IsSensitive: added
- (*FlagBase[[]uint8, IntegerConfig, Uint8Slice]).IsSensitive: added
- (*FlagBase[bool, BoolConfig, boolValue]).IsSensitive: added
- (*FlagBase[float32, NoConfig, floatValue[float32]]).IsSensitive: added
- (*FlagBase[float64, NoConfig, floatValue[float64]]).IsSensitive: added
- (*FlagBase[int, IntegerConfig, intValue[int]]).IsSensitive: added
- (*FlagBase[int16, IntegerConfig, intValue[int16]]).IsSensitive: added
- (*FlagBase[int32, IntegerConfig, intValue[int32]]).IsSensitive: added
- (*FlagBase[int64, IntegerConfig, intValue[int64]]).IsSensitive: added
- (*FlagBase[int8, IntegerConfig, intValue[int8]]).IsSensitive: added
- (*FlagBase[map[string]string, StringConfig, StringMap]).IsSensitive: added
- (*FlagBase[string, StringConfig, stringValue]).IsSensitive: added
- (*FlagBase[time.Duration, NoConfig, durationValue]).IsSensitive: added
- (*FlagBase[time.Time, TimestampConfig, timestampValue]).IsSensitive: added
- (*FlagBase[uint, IntegerConfig, uintValue[uint]]).IsSensitive: added
- (*FlagBase[uint16, IntegerConfig, uintValue[uint16]]).IsSensitive: added
- (*FlagBase[uint32, IntegerConfig, uintValue[uint32]]).IsSensitive: added
- (*FlagBase[uint64, IntegerConfig, uintValue[uint64]]).IsSensitive: added
- (*FlagBase[uint8, IntegerConfig, uintValue[uint8]]).IsSensitive: added
- FlagBase.Sensitive: added
- SensitiveFlag: added

Release Notes

Add Sensitive field to flags to mask secret values

@danudey
danudey requested a review from a team as a code owner November 16, 2026 21:01
@danudey

danudey commented Nov 17, 2026

Copy link
Copy Markdown
Author

The binary size has increased significantly due to (*Command).MarshalJSON importing encoding/json and text/template requiring all of its exported methods to stay in the binary.

Working on options:

  1. Remove the custom JSON marshalling (this would leak defaults in most sensitive fields and actual values for GenericFlag and TextFlag
  2. Move JSON marshalling into a separate package which users would have to opt-in to use
  3. Allow the leak and document it
  4. Modify GenericFlag and TextFlag in a way as to marshal a default clone of the flag rather than the live object. This would be a shallow clone so there's still complexities and gotchas
  5. Throw an error if someone tries to marshal a sensitive (Generic|Text)Flag (and optionally tell them to use the opt-in package to do so safely)

danudey and others added 2 commits November 17, 2026 10:04
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant