redact

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 6, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package redact is the built-in, fail-closed redaction engine that runs before any text is sent to Jev.

Every rule has a stable id (for example builtin.aws-access-key) and a class. HARD rules cannot be disabled or allowlisted by anyone. SOFT rules can be disabled or given allowlist patterns through Options.

Redaction is line-preserving: newlines are never added, dropped or merged, so L000.. line tags stay aligned. After redaction a verification pass checks that no known secret value survives. If redaction errors or verification fails, Apply returns a *jev.Error with jev.CodeRejected so the caller rejects the input before touching the network.

All patterns use Go RE2, so matching is linear-time (no ReDoS). Results report which rules fired and how often, never the matched content.

Index

Constants

View Source
const (
	MaxPatternLen     = 1024
	MaxReplacementLen = 256
)

Limits on custom rules.

View Source
const (
	RuleKnownSecret   = "builtin.known-secret"
	RulePrivateKey    = "builtin.private-key-block"
	RuleAuthHeader    = "builtin.authorization-header"
	RuleBearerToken   = "builtin.bearer-token"
	RuleOpenAIKey     = "builtin.openai-key"
	RuleAWSAccessKey  = "builtin.aws-access-key"
	RuleGitHubToken   = "builtin.github-token"
	RuleSlackToken    = "builtin.slack-token"
	RuleCredentialAsg = "builtin.credential-assignment"
	RuleHomePath      = "builtin.home-path"
	RuleUserPath      = "builtin.user-path"
	RuleEmail         = "builtin.email"
	RuleIPv4          = "builtin.ipv4"
	RuleEnvDump       = "builtin.env-dump"
	RuleHighEntropy   = "builtin.high-entropy"
)

Stable rule ids.

View Source
const (
	DefaultEntropyThreshold = 4.3
	DefaultMinTokenLen      = 40

	// Strict mode redacts when in doubt: 40-character hex digests (about 3.7
	// bits/char) and shorter tokens are caught.
	StrictEntropyThreshold = 3.5
	StrictMinTokenLen      = 24
)

Defaults for the high-entropy rule. The threshold is above the 4.0 bits/char ceiling of a hex digest, so git shas and content hashes are preserved.

View Source
const Marker = "[REDACTED]"

Marker replaces redacted content unless a Placeholder is configured.

Variables

This section is empty.

Functions

func LabelPlaceholder

func LabelPlaceholder(ruleID, _ string) string

LabelPlaceholder replaces a match with [REDACTED:rule-id].

func ValidateCustomRule

func ValidateCustomRule(c CustomRule) error

ValidateCustomRule reports why c is not an acceptable custom rule.

Types

type Class

type Class int

Class says whether a rule can be tuned.

const (
	// Hard rules cannot be disabled or allowlisted.
	Hard Class = iota
	// Soft rules can be disabled or allowlisted through Options.
	Soft
)

func (Class) String

func (c Class) String() string

type CustomRule

type CustomRule struct {
	ID      string
	Pattern string
	// Flags is any of "i", "m", "s".
	Flags string
	// Replacement, when set, replaces each match verbatim; otherwise the
	// configured placeholder is used.
	Replacement string
}

CustomRule is a user-defined redaction pattern (Go RE2).

type CustomRuleError

type CustomRuleError struct {
	Field string
	Msg   string
}

CustomRuleError says which field of a CustomRule is unacceptable: "id", "pattern", "flags" or "replacement".

func (*CustomRuleError) Error

func (e *CustomRuleError) Error() string

type Hit

type Hit struct {
	RuleID string
	Count  int
}

Hit reports that a rule fired; it never carries matched content.

type Options

type Options struct {
	// Key is the live API key value; it is always redacted (HARD).
	Key string
	// Secrets are further known secret values (env-var values) that must not
	// survive redaction (HARD).
	Secrets []string
	// Home is the home directory rewritten to "~" (SOFT).
	Home string
	// DisableSoft lists SOFT rule ids to turn off.
	DisableSoft []string
	// Allow maps a SOFT rule id to RE2 patterns; a match of the rule whose text
	// matches any pattern is left in place.
	Allow map[string][]string
	// Custom are extra regexp rules. They are HARD: they cannot be disabled or
	// allowlisted.
	Custom []CustomRule
	// Placeholder overrides the "[REDACTED]" replacement; nil keeps it.
	Placeholder Placeholder
	// EntropyThreshold (bits/char) and MinTokenLen tune the SOFT high-entropy
	// rule; zero keeps DefaultEntropyThreshold and DefaultMinTokenLen.
	EntropyThreshold float64
	MinTokenLen      int
	// Strict redacts every SOFT rule and lowers the entropy threshold and
	// minimum token length to StrictEntropyThreshold and StrictMinTokenLen
	// (never raising them). It cannot be combined with DisableSoft or Allow.
	Strict bool
}

Options configures a Redactor. Only SOFT rules are tunable.

func OptionsFromEnv

func OptionsFromEnv(environ []string) Options

OptionsFromEnv builds Options from an environment (KEY=value entries): HOME, TYPESAFE_API_KEY, and the values of credential-looking variables.

type Placeholder

type Placeholder func(ruleID, matched string) string

Placeholder builds the replacement for content matched by rule ruleID. It must be deterministic, must not include matched content, and must not contain a newline.

func StablePlaceholder

func StablePlaceholder(salt []byte) Placeholder

StablePlaceholder returns a Placeholder that writes [REDACTED:rule-id:abcd], where abcd is the first two bytes of HMAC-SHA256(salt, rule-id NUL match). The same secret always maps to the same token under one salt, and the token cannot be reversed or correlated across installs without the salt.

type Redactor

type Redactor struct {
	// contains filtered or unexported fields
}

Redactor applies the built-in rules. It is safe for concurrent use.

func New

func New(opts Options) (*Redactor, error)

New builds a Redactor. It fails if Options tries to disable or allowlist a HARD rule, or names an unknown rule.

func (*Redactor) Apply

func (r *Redactor) Apply(text string) (res Result, err error)

Apply redacts text. Any failure, including a secret surviving the verification pass or a changed line count, returns a *jev.Error with jev.CodeRejected and no text.

func (*Redactor) ApplyJSON

func (r *Redactor) ApplyJSON(raw []byte) (out []byte, hits []Hit, err error)

ApplyJSON recursively redacts a JSON value: string leaves and object keys are each passed through Apply, while numbers, booleans and null are left untouched. The result is guaranteed to remain valid JSON of the same shape. Redacting two sibling object keys to the same text would silently drop one entry, changing the meaning of the value (for example a Choice or Noul criteria map); ApplyJSON instead fails closed with a *jev.Error in that case, exactly like a survived secret.

type Result

type Result struct {
	Text string
	Hits []Hit
}

Result is the redacted text and the rules that fired, in rule order.

type Rule

type Rule struct {
	ID    string
	Class Class
}

Rule describes a built-in rule for listing.

func Rules

func Rules() []Rule

Rules lists the built-in rule ids and classes, in application order.

type RuleInfo

type RuleInfo struct {
	ID      string
	Class   Class
	Pattern string
	Summary string
}

RuleInfo documents a built-in rule for `jevkit redact explain`.

func Describe

func Describe(id string) (RuleInfo, bool)

Describe returns the documentation for a built-in rule id.

Directories

Path Synopsis
Package audit is the transparency layer for what leaves the machine: an append-only audit log of counts (never content), an opt-in store of the exact redacted payloads of recent sends, and an optional confirm step.
Package audit is the transparency layer for what leaves the machine: an append-only audit log of counts (never content), an opt-in store of the exact redacted payloads of recent sends, and an optional confirm step.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL