diff --git a/README.md b/README.md new file mode 100644 index 0000000..e0a202b --- /dev/null +++ b/README.md @@ -0,0 +1,54 @@ +# 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: + +```bash +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: + +```go +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: + +```go +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. diff --git a/doc.go b/doc.go index 99378e7..7bf8a1a 100644 --- a/doc.go +++ b/doc.go @@ -4,30 +4,30 @@ // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // -// http://www.apache.org/licenses/LICENSE-2.0 +// http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. +package safecli // Package safecli provides functionality for building, redacting, and logging command-line arguments. // It is designed to handle sensitive values securely // while also providing utility for CLI construction and logging. -package safecli - +// // The package offers two concrete builder functions: // - NewBuilder: Creates a new CLI builder, allowing for flexible CLI creation. // - NewLogger: Creates a new CLI logger for safely CLI logging. - +// // Usage example: // // package main // // import ( // "fmt" -// "safecli" +// "github.com/kanisterio/safecli" // ) // // func main() {