Redact — Credential Stripping at Boundaries¶

pkg/redact is the shared redactor for any surface in GTB — and in tools built on GTB — that writes free-form strings outside the trust boundary of the local process. It is applied automatically by the telemetry collector for TrackCommandExtended error and args fields, and by HTTP middleware for known-sensitive request headers. Callers that write their own logs or telemetry events should route untrusted strings through it too.

Local-process logs that never leave the host do not need to go through this package — those may need raw content for debugging.

Threat Model¶

Credentials reach observability surfaces by accident more often than by design:

Once that content reaches a third-party ingest it is outside the operator's control — replicated, indexed, and retained longer than intended. Redacting at the boundary is the last controllable step.

Invariants¶

1. Idempotent — String(String(s)) == String(s). Middlewares that might double-redact cannot corrupt output.
2. Never panics — any input, including zero-length or control-byte strings, is safe to pass.
3. Bounded growth — replacements are fixed-length (***, <redacted>, <redacted-token>). Output never grows the input unboundedly.
4. Pure function — same input → same output; no side effects; safe for concurrent use.
5. Original string never retained — the redactor does not log, cache, or transmit the input anywhere.

Both invariants 1 and 2 are enforced by FuzzRedactString in CI.

API¶

import "gitlab.com/phpboyscout/go-tool-base/pkg/redact"

// Clean a free-form string before shipping.
clean := redact.String(userInput)

// Convenience wrapper over err.Error() — returns "" for nil.
cleanErr := redact.Error(err)

// Decide whether a header name looks like it carries a credential.
if redact.IsSensitiveHeaderKey(name) {
    // warn the operator, redact the value, etc.
}

// The default redaction list used by HTTP middleware and telemetry.
for _, k := range redact.SensitiveHeaderKeys { /* ... */ }

What Gets Redacted¶

Known Limitations¶

• ASCII-only patterns. Virtually all provider credentials are ASCII; UTF-8 edge cases are out of scope.
• False negatives on unusual credential formats. A credential that doesn't match any catalogued pattern and is under 41 characters will slip through. Add a pattern PR if a vendor you care about has a unique shape.
• Fuzzy pattern threshold at 41 characters. Chosen to avoid false positives on UUIDs (32/36), MD5 (32), and git SHAs (40). SHA-256 hashes (64) will match — acceptable; hashes rarely appear in error strings and over-redaction is safer than under-redaction.
• Pattern order matters. Earlier-matching patterns claim spans first. A string like ?token= + long-opaque-value is redacted as token=*** (by the query-param rule), not token=<redacted-token> (the fuzzy fallback). Both outcomes are redactions; the difference is cosmetic.

Call-Site Discipline¶

pkg/redact is the entry point for untrusted-string redaction. When adding a new code path that writes to telemetry, distributed logs, or a third-party observability surface:

• Route any free-form string that may contain user- or environment-derived content through redact.String or redact.Error.
• Use redact.IsSensitiveHeaderKey when deciding whether to log a header value or emit an operator advisory.
• When in doubt, redact — the cost is negligible (a few regex passes on a bounded string); the cost of missing is a credential in a vendor log.

Failing to route through the helper reintroduces the leakage class this package exists to close.