Add redact CLI

The package was only usable from Go code. Add a `cmd/redact` binary that
accepts text via positional args or stdin and prints the redacted output.
Flags map to `Options` (`--mask`, `--min-entropy`, `--min-submatch`);
stdin is streamed line by line with `bufio.Scanner` so arbitrarily large
inputs do not buffer in memory.

Tests use `rogpeppe/go-internal/testscript` (the same pattern as
xk6-docs): each `testdata/scripts/*.txtar` invokes the built binary and
asserts on stdout. Also adds a minimal `.golangci.yml` so future changes
have a single, version-pinned lint command.

Author: inancgumus

.github/workflows/build.yml

@@ -0,0 +1,51 @@
+name: build
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - run: go test ./...
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - { goos: linux,   goarch: amd64 }
+          - { goos: linux,   goarch: arm64 }
+          - { goos: darwin,  goarch: amd64 }
+          - { goos: darwin,  goarch: arm64 }
+          - { goos: windows, goarch: amd64, ext: .exe }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - name: build
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: "0"
+        run: |
+          mkdir -p dist
+          go build -trimpath -ldflags='-s -w' \
+            -o "dist/redact-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.ext }}" \
+            ./cmd/redact
+      - uses: actions/upload-artifact@v4
+        with:
+          name: redact-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: dist/*
+          if-no-files-found: error

.golangci.yml

@@ -0,0 +1,15 @@
+version: "2"
+
+linters:
+  default: none
+  enable:
+    - errcheck
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+    - misspell
+    - unconvert
+    - unparam
+    - revive
+    - gocritic

README.md

@@ -1,54 +1,104 @@
 # redact
 
-Replaces secrets in text with `[REDACTED]`.
+Hide secrets in text. Keeps the same length, so logs and dumps stay readable.
+
+```
+$ redact 'curl -H "Authorization: Bearer ghp_abcdefghijklmnopqrstuvwxyz0123456789" api.github.com'
+curl -H "Authorization: Bearer ****************************************" api.github.com
+```
 
 ## Install
 
+Grab a prebuilt binary from the [Actions tab](../../actions) (latest `build` run, under "Artifacts"), or build from source:
+
+```
+go install github.com/inancgumus/redact/cmd/redact@latest
+```
+
+## Use the CLI
+
+Pass text as an argument:
+
+```
+$ redact 'user=alice token=ghp_abcdefghijklmnopqrstuvwxyz0123456789 status=ok'
+user=alice token=**************************************** status=ok
+```
+
+Or pipe a file:
+
 ```
-go get github.com/inancgumus/redact
+$ redact < ~/.aws/credentials
+[default]
+aws_access_key_id = ********************
+aws_secret_access_key = ****************************************
 ```
 
-## Use
+Database URLs keep their structure:
+
+```
+$ redact 'postgresql://app:s3cretP4ss@db.internal:5432/prod'
+postgresql://app:**********@db.internal:5432/prod
+```
+
+Run with no input to see the help.
+
+### Flags
+
+| Flag | Default | What it does |
+|------|---------|--------------|
+| `--mask` | `*` | Character used to hide each byte of a secret. |
+| `--min-entropy` | `3.5` | How random a value must look before it counts as a secret. Lower means more aggressive. |
+| `--min-submatch` | `2` | How strong a match must be before unknown secrets get hidden. Higher means more cautious. |
+
+### Examples
+
+Custom mask character:
+
+```
+$ redact --mask=# 'token: ghp_abcdefghijklmnopqrstuvwxyz0123456789'
+token: ########################################
+```
+
+Catch a wider net of unknown-looking values in a config file:
+
+```
+$ redact --min-entropy=2.0 < config.yaml
+```
+
+## Use as a Go library
 
 ```go
+import "github.com/inancgumus/redact"
+
 clean := redact.String(text, redact.DefaultOptions)
 ```
 
-Override defaults via `Options`:
+Tune the defaults:
 
 ```go
 clean := redact.String(text, redact.Options{
-    // Placeholder written in place of each detected secret.
-    // Default: "[REDACTED]".
-    Mask: "***",
-
-    // Minimum Shannon entropy (bits/char) a captured value must have
-    // to be treated as a secret by the generic detector. Lower values
-    // redact more aggressively; raise it to cut false positives on
-    // low-entropy strings. Default: 3.5.
-    MinEntropy: 4.0,
-
-    // Minimum number of regex submatches required before a generic
-    // match is considered for redaction. Default: 2.
-    MinSubmatch: 2,
+    Mask:        '#',  // Character repeated for each byte. Default '*'.
+    MinEntropy:  4.0,  // Raise to cut false positives. Default 3.5.
+    MinSubmatch: 2,    // Raise to be more cautious on unknown patterns. Default 2.
 })
 ```
 
-## Catches
+Any zero field falls back to the default.
+
+## What it catches
 
-Shape-based catches:
+### Patterns by shape
 
 - PEM private keys
 - JWTs
-- `Bearer` auth headers
-- `Basic` auth headers
+- `Bearer` and `Basic` auth headers
 - URL credentials (`user:pass@host`)
 - `btoa("user:pass")` calls
 - `password` / `secret` / `credential` assignments
-- Query-string secrets (`?token=...`, `?key=...`, etc.)
-- Generic high-entropy values near words like `key`, `secret`, `token`
+- Query-string secrets (`?token=...`, `?key=...`)
+- High-entropy values near words like `key`, `secret`, `token`
 
-Provider-token catches (prefix-anchored):
+### Provider tokens (prefix-anchored)
 
 - AWS access keys (`AKIA`, `ASIA`, `ABIA`, `ACCA`, `A3T...`)
 - AWS secret keys (keyword-anchored 40-char base64)
@@ -159,9 +209,9 @@ Provider-token catches (prefix-anchored):
 - HashiCorp Terraform (`<id>.atlasv1.<...>`)
 - Telegram bot token
 
-## Skips
+### What it skips
 
-- Variable expansions (`${...}`, `$(...)`)
+- Variable expansions like `${SECRET}` or `$(cat secret)`
 - UUIDs
-- Dotted property access (`apiClient.token`)
-- Values containing stopwords (`example`, `test`, `placeholder`, etc.)
+- Dotted property access like `apiClient.token`
+- Values containing words like `example`, `test`, `placeholder`

cmd/redact/main.go

@@ -0,0 +1,87 @@
+// Command redact reads text from positional args or stdin and writes a
+// copy with detected secrets replaced by a placeholder.
+package main
+
+import (
+	"bufio"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/inancgumus/redact"
+)
+
+func main() {
+	if err := run(os.Args[1:], os.Stdin, os.Stdout, os.Stderr); err != nil {
+		fmt.Fprintln(os.Stderr, "redact:", err)
+		os.Exit(1)
+	}
+}
+
+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.")
+		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,
+		"how random a value must look to be redacted (lower = redacts more)")
+	fs.IntVar(&opts.MinSubmatch, "min-submatch", opts.MinSubmatch,
+		"how strong a match must be to redact unknown secrets (higher = redacts less)")
+
+	if err := fs.Parse(args); err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return nil
+		}
+		return err
+	}
+
+	if rest := fs.Args(); len(rest) > 0 {
+		_, err := io.WriteString(stdout, redact.String(strings.Join(rest, " "), opts))
+		return err
+	}
+
+	// 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
+	}
+
+	buf, err := io.ReadAll(br)
+	if err != nil {
+		return fmt.Errorf("read stdin: %w", err)
+	}
+	_, err = io.WriteString(stdout, redact.String(string(buf), opts))
+	return err
+}
+
+// runeFlag adapts a *rune to the flag.Value interface so the mask flag
+// accepts exactly one character.
+type runeFlag rune
+
+func (r *runeFlag) String() string {
+	if r == nil || *r == 0 {
+		return ""
+	}
+	return string(*r)
+}
+
+func (r *runeFlag) Set(s string) error {
+	runes := []rune(s)
+	if len(runes) != 1 {
+		return fmt.Errorf("mask must be one character, got %q", s)
+	}
+	*r = runeFlag(runes[0])
+	return nil
+}

cmd/redact/main_test.go

@@ -0,0 +1,47 @@
+package main
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+
+	"github.com/rogpeppe/go-internal/testscript"
+)
+
+func buildRedactBinary(ctx context.Context, t *testing.T) string {
+	t.Helper()
+
+	cacheDir, err := os.UserCacheDir()
+	if err != nil {
+		t.Fatalf("cache dir: %v", err)
+	}
+	dir := filepath.Join(cacheDir, "redact-test")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+
+	bin := filepath.Join(dir, "redact")
+	build := exec.CommandContext(ctx, "go", "build", "-o", bin, ".")
+	out, err := build.CombinedOutput()
+	if err != nil {
+		t.Fatalf("build redact: %v\n%s", err, out)
+	}
+	return bin
+}
+
+func TestScripts(t *testing.T) {
+	t.Parallel()
+
+	ctx := t.Context()
+	bin := buildRedactBinary(ctx, t)
+
+	testscript.Run(t, testscript.Params{
+		Dir: "testdata/scripts",
+		Setup: func(env *testscript.Env) error {
+			return os.Symlink(bin, filepath.Join(env.WorkDir, "redact"))
+		},
+		UpdateScripts: os.Getenv("UPDATE_GOLDEN") != "",
+	})
+}

cmd/redact/testdata/scripts/arg.txtar

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

cmd/redact/testdata/scripts/entropy.txtar

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

cmd/redact/testdata/scripts/min_submatch.txtar

@@ -0,0 +1,8 @@
+# Default --min-submatch matches generic high-entropy values.
+exec ./redact 'api_key="aB3kPq9xZ7mNvR2tYuIo"'
+stdout '\*+'
+
+# Raising --min-submatch above the captured group count disables generic matches.
+exec ./redact --min-submatch=99 'api_key="aB3kPq9xZ7mNvR2tYuIo"'
+! stdout '\*'
+stdout 'aB3kPq9xZ7mNvR2tYuIo'

cmd/redact/testdata/scripts/multi_args.txtar

@@ -0,0 +1,4 @@
+# Multiple positional args are joined with a space.
+exec ./redact 'before' AKIAIOSFODNN7EXAMPLE 'after'
+stdout '^before \*+ after$'
+! stdout 'AKIAIOSFODNN7EXAMPLE'

cmd/redact/testdata/scripts/no_input.txtar

@@ -0,0 +1,12 @@
+# No args and empty stdin prints usage to stderr and exits 0.
+exec ./redact
+stderr 'usage: redact'
+stderr '-mask'
+stderr '-min-entropy'
+stderr '-min-submatch'
+! stdout .
+
+# Explicit -h also prints usage and exits 0.
+exec ./redact -h
+stderr 'usage: redact'
+! stdout .