README
¶
SafeCLI: Secure Command Line Interface Package
SafeCLI is a specialized Go package aimed at facilitating the secure construction, redaction, and logging of command-line arguments. It's designed particularly to handle sensitive values, ensuring they are managed securely throughout the process of command-line argument preparation and execution. This package is part of the Kanister project.
Features
- Secure Argument Handling: Safely handles sensitive information in command-line arguments, ensuring that sensitive details are never exposed in logs or error messages.
- Flexible CLI Construction: Provides a builder pattern for constructing command-line arguments dynamically, allowing for clean and readable code.
- Redaction Interface: Integrates a redaction system that automatically obscures sensitive information when arguments are converted to strings for logging or debugging.
- Logging Utility: Includes a logging utility that ensures sensitive information is redacted, while still providing helpful output for debugging and monitoring.
Installation
You can install SafeCLI by running:
go get -u github.com/kanisterio/safecli
Usage
Basic CLI Construction
To construct a CLI command, you can use the NewBuilder function which initializes a new command builder. You can append arguments, both loggable and sensitive, to the builder:
package main
import "github.com/kanisterio/safecli"
func main() {
builder := safecli.NewBuilder("zip").
AppendLoggableKV("--output", "/path/to/output").
AppendRedactedKV("--password", "secretPass").
AppendLoggable("input_file1", "input_file2")
command := builder.Build()
// Use `command` as required, e.g., execute it
}
In the above example, --password is a sensitive argument, and its value will be redacted in logs.
Secure Logging
To log a CLI command securely, ensuring that sensitive information is redacted:
logger := safecli.NewLogger(builder)
logOutput := logger.Log()
// Use `logOutput` for logging
Contribution
Contributions to the SafeCLI package are welcome. Please follow the contribution guidelines of the Kanister project when submitting patches or features.
Documentation
¶
Index ¶
- func CommandArgumentFormatter(a Argument) string
- func LogArgumentFormatter(a Argument) string
- type Argument
- type ArgumentFormatter
- type Builder
- func (b *Builder) Append(command CommandArguments) *Builder
- func (b *Builder) AppendLoggable(values ...string) *Builder
- func (b *Builder) AppendLoggableKV(kvPairs ...string) *Builder
- func (b *Builder) AppendRedacted(values ...string) *Builder
- func (b *Builder) AppendRedactedKV(kvPairs ...string) *Builder
- func (b *Builder) Arguments() []Argument
- func (b *Builder) Build() []string
- func (b *Builder) String() string
- type CommandAppender
- type CommandArguments
- type CommandBuilder
- type CommandLogger
- type Logger
- type PlainValue
- type Redactor
- type SensitiveValue
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CommandArgumentFormatter ¶
CommandArgumentFormatter implements regular command formatter.
func LogArgumentFormatter ¶
LogArgumentFormatter implements log formatter.
Types ¶
type ArgumentFormatter ¶
ArgumentFormatter defines a function that formats a command argument to the string.
type Builder ¶
type Builder struct {
// Args stores the command arguments.
Args []Argument
// Formatter defines a function that formats a command argument to the string.
Formatter ArgumentFormatter
}
Builder is used for constructing CLI.
func NewBuilder ¶
NewBuilder creates a new command builder instance. It takes a slice of string values which are appended to the builder.
func (*Builder) Append ¶
func (b *Builder) Append(command CommandArguments) *Builder
Append combines the command arguments with the builder.
func (*Builder) AppendLoggable ¶
AppendLoggable adds loggable values to the builder. These values can be logged and displayed as they do not have sensitive info.
func (*Builder) AppendLoggableKV ¶
AppendLoggableKV adds key=value pairs to the builder. Key and value are loggable.
func (*Builder) AppendRedacted ¶
AppendRedacted adds redacted values to the builder. These values are sensitive and should be display in logs as <****>.
func (*Builder) AppendRedactedKV ¶
AppendRedactedKV adds key=value pairs to the builder. Key is loggable and value is sensitive. The value should be display in logs as <****>.
type CommandAppender ¶
type CommandAppender interface {
AppendLoggable(values ...string) *Builder
AppendLoggableKV(kvPairs ...string) *Builder
AppendRedacted(values ...string) *Builder
AppendRedactedKV(kvPairs ...string) *Builder
Append(command CommandArguments) *Builder
}
CommandAppender appends the command arguments to the builder.
type CommandArguments ¶
type CommandArguments interface {
Arguments() []Argument
}
CommandArguments provides an interface for accessing command arguments.
type CommandBuilder ¶
type CommandBuilder interface {
Build() []string
}
CommandBuilder builds and returns the command for execution.
type CommandLogger ¶
type CommandLogger interface {
Log() string
}
CommandLogger returns a string representation of the command for logging.
type Logger ¶
type Logger struct {
// Command stores the Command arguments.
Command CommandArguments
// Formatter defines a function that formats a command argument to the string.
Formatter ArgumentFormatter
}
Logger is used for logging command arguments.
func NewLogger ¶
func NewLogger(command CommandArguments) *Logger
NewLogger creates a new Logger instance.
type PlainValue ¶
type PlainValue struct {
// contains filtered or unexported fields
}
PlainValue implements Redactor interface for non-sensitive data.
func (PlainValue) PlainString ¶
func (l PlainValue) PlainString() string
PlainString returns a string as is.
func (PlainValue) String ¶
func (l PlainValue) String() string
String returns a string as is, without redaction.
type Redactor ¶
Redactor defines an interface for handling sensitive value in the way that it can be represented both in a plain and redacted text form.
type SensitiveValue ¶
type SensitiveValue struct {
// contains filtered or unexported fields
}
SensitiveValue implements Redactor interface for sensitive data.
func (SensitiveValue) GoString ¶
func (r SensitiveValue) GoString() string
GoString returns a redacted string, never the actual value for a %#v format too.
func (SensitiveValue) PlainString ¶
func (r SensitiveValue) PlainString() string
PlainString returns the original sensitive value.
func (SensitiveValue) String ¶
func (r SensitiveValue) String() string
String returns a redacted string, never the actual value.
Source Files
Directories