Redesign CLI around -string and -detect

Positional args mixed secret bodies with stray tokens and forced users
to remember an implicit join. Stdin is now the default (cat-like),
-string passes inline text, and -detect runs HasSecrets and exits 1 on
a hit. Renamed -min-entropy and -min-submatch to shorter -entropy and
-strength.

Author: inancgumus

README.md

@@ -4,14 +4,7 @@ Hide secrets in text.
 
 ## Usage
 
-Pass text as an argument:
-
-```
-$ redact 'user=alice token=ghp_abcdefghijklmnopqrstuvwxyz0123456789 status=ok'
-user=alice token=**************************************** status=ok
-```
-
-Or pipe a file:
+Pipe a file:
 
 ```
 $ redact < ~/.aws/credentials
@@ -20,17 +13,34 @@ aws_access_key_id = ********************
 aws_secret_access_key = ****************************************
 ```
 
+Pass text inline with `-string`:
+
+```
+$ redact -string 'user=alice token=ghp_abcdefghijklmnopqrstuvwxyz0123456789 status=ok'
+user=alice token=**************************************** status=ok
+```
+
 Custom mask character:
 
 ```
-$ redact --mask=# 'token: ghp_abcdefghijklmnopqrstuvwxyz0123456789'
+$ redact -mask=# -string 'token: ghp_abcdefghijklmnopqrstuvwxyz0123456789'
 token: ########################################
 ```
 
 Catch a wider net of unknown-looking values in a config file:
 
 ```
-$ redact --min-entropy=2.0 < config.yaml
+$ redact -entropy=2.0 < config.yaml
+```
+
+Check for secrets without printing anything. Exits 1 if found, 0 if not:
+
+```
+$ redact -detect -string 'token=ghp_abcdefghijklmnopqrstuvwxyz0123456789' && echo clean || echo dirty
+dirty
+
+$ redact -detect -string 'log_level=debug' && echo clean || echo dirty
+clean
 ```
 
 ## Use as a package
@@ -39,6 +49,10 @@ $ redact --min-entropy=2.0 < config.yaml
 import "github.com/inancgumus/redact"
 
 clean := redact.String(text, redact.DefaultOptions)
+
+if redact.HasSecrets(text, redact.DefaultOptions) {
+    // text contains at least one detected secret
+}
 ```
 
 Tune the defaults:

cmd/redact/main.go

@@ -1,15 +1,13 @@
-// Command redact reads text from positional args or stdin and writes a
-// copy with detected secrets replaced by a placeholder.
+// Command redact reads text from -string or stdin and writes a copy with
+// detected secrets replaced by a mask character.
 package main
 
 import (
-	"bufio"
 	"errors"
 	"flag"
 	"fmt"
 	"io"
 	"os"
-	"strings"
 
 	"github.com/inancgumus/redact"
 )
@@ -25,18 +23,22 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) error {
 	fs := flag.NewFlagSet("redact", flag.ContinueOnError)
 	fs.SetOutput(stderr)
 	fs.Usage = func() {
-		_, _ = fmt.Fprintln(stderr, "usage: redact [flags] [text...]")
-		_, _ = fmt.Fprintln(stderr, "reads text from args; if none, reads from stdin.")
+		_, _ = fmt.Fprintln(stderr, "usage: redact [flags]")
+		_, _ = fmt.Fprintln(stderr, "reads -string if set, otherwise stdin.")
 		fs.PrintDefaults()
 	}
 
 	opts := redact.DefaultOptions
 	fs.Var((*runeFlag)(&opts.Mask), "mask",
 		"character repeated for each byte of a secret")
-	fs.Float64Var(&opts.MinEntropy, "min-entropy", opts.MinEntropy,
+	fs.Float64Var(&opts.MinEntropy, "entropy", opts.MinEntropy,
 		"how random a value must look to be redacted (lower = redacts more)")
-	fs.IntVar(&opts.MinSubmatch, "min-submatch", opts.MinSubmatch,
+	fs.IntVar(&opts.MinSubmatch, "strength", opts.MinSubmatch,
 		"how strong a match must be to redact unknown secrets (higher = redacts less)")
+	detect := fs.Bool("detect", false,
+		"exit 1 if input contains secrets, 0 otherwise; no output")
+	var input string
+	fs.StringVar(&input, "string", "", "redact this text instead of reading stdin")
 
 	if err := fs.Parse(args); err != nil {
 		if errors.Is(err, flag.ErrHelp) {
@@ -45,27 +47,40 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) error {
 		return err
 	}
 
-	if rest := fs.Args(); len(rest) > 0 {
-		_, err := io.WriteString(stdout, redact.String(strings.Join(rest, " "), opts))
-		return err
+	if fs.NArg() > 0 {
+		return fmt.Errorf("unexpected positional args; use -string for inline text")
 	}
 
-	// Peek so empty stdin prints usage instead of silently exiting.
-	// The peeked byte stays buffered for ReadAll.
-	br := bufio.NewReader(stdin)
-	if _, err := br.Peek(1); err != nil {
-		fs.Usage()
-		return nil
+	text := input
+	if !isStringFlagSet(fs) {
+		buf, err := io.ReadAll(stdin)
+		if err != nil {
+			return fmt.Errorf("read stdin: %w", err)
+		}
+		text = string(buf)
 	}
 
-	buf, err := io.ReadAll(br)
-	if err != nil {
-		return fmt.Errorf("read stdin: %w", err)
+	if *detect {
+		if redact.HasSecrets(text, opts) {
+			os.Exit(1)
+		}
+		return nil
 	}
-	_, err = io.WriteString(stdout, redact.String(string(buf), opts))
+
+	_, err := io.WriteString(stdout, redact.String(text, opts))
 	return err
 }
 
+func isStringFlagSet(fs *flag.FlagSet) bool {
+	var set bool
+	fs.Visit(func(f *flag.Flag) {
+		if f.Name == "string" {
+			set = true
+		}
+	})
+	return set
+}
+
 // runeFlag adapts a *rune to the flag.Value interface so the mask flag
 // accepts exactly one character.
 type runeFlag rune

cmd/redact/testdata/scripts/arg.txtar

@@ -1,4 +1,4 @@
-# Redacts a secret passed as a positional arg.
-exec ./redact AKIAIOSFODNN7EXAMPLE
+# Redacts a secret passed via -string.
+exec ./redact -string AKIAIOSFODNN7EXAMPLE
 ! stdout 'AKIAIOSFODNN7EXAMPLE'
 stdout '\*+'

cmd/redact/testdata/scripts/detect.txtar

@@ -0,0 +1,26 @@
+# -detect exits 1 when -string contains a secret.
+! exec ./redact -detect -string AKIAIOSFODNN7EXAMPLE
+! stdout .
+
+# -detect exits 0 on plain prose.
+exec ./redact -detect -string 'the quick brown fox'
+! stdout .
+
+# -detect reads stdin and exits 1 when a secret is found.
+stdin secret.txt
+! exec ./redact -detect
+! stdout .
+
+# -detect reads stdin and exits 0 when no secret is found.
+stdin clean.txt
+exec ./redact -detect
+! stdout .
+
+# Options propagate: raising --entropy hides generic matches.
+exec ./redact -detect --entropy=10.0 -string 'api_key="aB3kPq9xZ7mNvR2tYuIo"'
+! stdout .
+
+-- secret.txt --
+ghp_abcdefghijklmnopqrstuvwxyz0123456789
+-- clean.txt --
+log_level=debug

cmd/redact/testdata/scripts/entropy.txtar

@@ -1,9 +1,9 @@
 # High --min-entropy suppresses the generic detector.
-exec ./redact --min-entropy=10 'api_key="abcdefghij1234567890"'
+exec ./redact --entropy=10 -string 'api_key="abcdefghij1234567890"'
 ! stdout '\*'
 stdout 'abcdefghij1234567890'
 
 # Low --min-entropy redacts aggressively.
-exec ./redact --min-entropy=1 'api_key="abcdefghij1234567890"'
+exec ./redact --entropy=1 -string 'api_key="abcdefghij1234567890"'
 stdout '\*+'
 ! stdout 'abcdefghij1234567890'

cmd/redact/testdata/scripts/min_submatch.txtar

@@ -1,12 +1,17 @@
-# No args and empty stdin prints usage to stderr and exits 0.
+# Empty stdin produces empty output, exits 0 (cat-like).
 exec ./redact
-stderr 'usage: redact'
-stderr '-mask'
-stderr '-min-entropy'
-stderr '-min-submatch'
 ! stdout .
+! stderr .
 
-# Explicit -h also prints usage and exits 0.
+# Explicit -h prints usage and exits 0.
 exec ./redact -h
 stderr 'usage: redact'
 ! stdout .
+
+# Positional args are rejected.
+! exec ./redact some-text
+stderr 'unexpected positional args'
+
+# Empty -string yields empty output.
+exec ./redact -string ''
+! stdout .

cmd/redact/testdata/scripts/multi_args.txtar

@@ -1,9 +1,9 @@
 # Custom mask character via --mask.
-exec ./redact '--mask=#' AKIAIOSFODNN7EXAMPLE
+exec ./redact '--mask=#' -string AKIAIOSFODNN7EXAMPLE
 stdout '^####################$'
 ! stdout 'AKIAIOSFODNN7EXAMPLE'
 ! stdout '\*'
 
 # Rejects multi-character mask.
-! exec ./redact '--mask=ab' AKIAIOSFODNN7EXAMPLE
+! exec ./redact '--mask=ab' -string AKIAIOSFODNN7EXAMPLE
 stderr 'mask must be one character'

cmd/redact/testdata/scripts/no_input.txtar

@@ -1,5 +1,5 @@
 # Plain prose passes through unchanged.
-exec ./redact 'the quick brown fox'
+exec ./redact -string 'the quick brown fox'
 stdout '^the quick brown fox$'
 ! stdout '\*'