Documentation
¶
Overview ¶
Package audit owns Harbor's deep-redaction pass. Every emit path (event bus, logger, future Governance LLM-boundary hook) MUST run payloads through Redactor.Redact before persistence or transmission.
The contract is fail-loudly: a Rule that returns an error means "do not emit." Callers that get an error from Redact must NOT fall back to the original payload. Tests pin this behaviour.
The Redactor is a canonical reusable artifact (D-025): one instance is opened at boot via Open and shared across every emit path. It is safe to call Redact concurrently from N goroutines on the same instance. No per-run state lives on the Redactor itself.
Index ¶
Constants ¶
const DefaultDriver = "patterns"
DefaultDriver is the production driver name. Phase 03 ships only `patterns`; later phases may register additional drivers (PII tokenizer, semantic redactor) and Open will switch on a `cfg.Driver` field once AuditConfig grows one.
const MaxDepth = 64
MaxDepth caps the deep-walk recursion to defend against pathologically nested or cyclic payloads. A payload that exceeds it produces ErrRedactionDepthExceeded — the contract says callers must NOT emit on error, so this fails closed.
const Placeholder = "***"
Placeholder is the value substituted in for any redacted field.
Variables ¶
var ( // ErrRedactionFailed wraps any failure from a Rule.Apply. It is // the contract surface for "do not emit": when Redact returns an // error wrapping this sentinel, the caller MUST NOT persist or // transmit the original payload. ErrRedactionFailed = errors.New("audit: redaction failed") // ErrRedactorMissing — the context carries no Redactor. Returned // (or panicked, via MustFrom) when an emit path is reached // without a runtime-attached Redactor. ErrRedactorMissing = errors.New("audit: no Redactor in context") // ErrRedactionDepthExceeded — the deep-walk hit the depth cap. // Defended against pathologically nested or cyclic payloads. ErrRedactionDepthExceeded = errors.New("audit: redaction depth exceeded") // ErrUnknownDriver — Open was asked for a driver name that no // registered factory handles. The error text lists the names // currently registered so misconfigurations are obvious. ErrUnknownDriver = errors.New("audit: unknown driver") )
Sentinel errors. Callers compare via errors.Is.
Functions ¶
func Register ¶
Register installs a driver factory under name. Drivers self-register from their package init(); cmd/harbor blank-imports the production driver to trigger registration. Per AGENTS.md §4.4.
Re-registering the same name panics — the registration model is write-once-at-init and a duplicate signals a build mis-configuration.
func RegisteredDrivers ¶
func RegisteredDrivers() []string
RegisteredDrivers returns a sorted list of driver names. Useful for boot-log output ("audit drivers available: patterns") and for surfacing in error messages.
Types ¶
type ArtifactRef ¶
type ArtifactRef struct {
Ref string `json:"artifact_ref" yaml:"artifact_ref"`
MIME string `json:"mime,omitempty" yaml:"mime,omitempty"`
SizeBytes int64 `json:"size_bytes,omitempty" yaml:"size_bytes,omitempty"`
Hash string `json:"hash,omitempty" yaml:"hash,omitempty"`
}
ArtifactRef is the canonical reference-shaped form of binary content per RFC §6.5 / D-021. Phase 03 ships only the type so the redactor can recognise refs and pass them through; the artifact store + materializer phases own the resolver. The type lives in this package to avoid a circular import — `internal/audit` is upstream of `internal/artifacts`.
type Factory ¶
type Factory func(config.AuditConfig) (Redactor, error)
Factory builds a Redactor from an AuditConfig slice. Drivers expose one Factory each via init() → Register.
type Redactor ¶
Redactor produces a deep-redacted copy of payload.
Contract:
- Redact MUST NOT mutate its input.
- On nil error, the returned value is safe to persist or transmit.
- On non-nil error, the caller MUST treat the error as "do not emit" — never persist or transmit the original payload as a fallback. The returned value is undefined and may be nil.
- Implementations must be safe for concurrent use by N goroutines against a single shared instance (D-025 concurrent reuse).
func MustFrom ¶
MustFrom returns the Redactor in ctx. Panics with ErrRedactorMissing when none is present. Use in handler / event-emit paths where a Redactor is mandatory.
func Open ¶
Open returns a Redactor built by the default driver factory. Phase 03 always picks DefaultDriver; later phases will read a `cfg.Driver` field once AuditConfig grows one. The error wraps ErrUnknownDriver when no factory matches and lists registered drivers.
func OpenDriver ¶
func OpenDriver(name string, cfg config.AuditConfig) (Redactor, error)
OpenDriver builds a Redactor from a specific driver name. Useful for tests that want to exercise the registry against a non-default driver without round-tripping through config.
type Rule ¶
Rule is one redaction step. Drivers compose rules and apply them in deterministic order; on the first error the driver returns (nil, wrapped error) — the fail-loudly contract from the package godoc.
Apply MUST return a deep-copied payload; mutating the input is a bug. Rule.Name() is exposed via the patterns driver's Names() method so an operator can confirm which rules ran.
func CanonicalRules ¶
func CanonicalRules() []Rule
CanonicalRules returns the V1 default rule set. Order is deterministic so golden-file tests are stable across runs.
Rules in order:
- api_key, password, secret, token, cookie, authorization, bearer (key-based redaction).
- bearer_in_value (regex over string values for embedded `Bearer xxx` credentials).
- multimodal (inline DataURL / base64 image|audio|file content).
Each rule's Name() is enumerable via patterns.Driver.Names() (the production driver shipped in this phase).
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
drivers
|
|
|
noop
Package noop is a pass-through audit redactor for tests that want to bypass redaction.
|
Package noop is a pass-through audit redactor for tests that want to bypass redaction. |
|
patterns
Package patterns is Harbor's V1 audit redactor driver.
|
Package patterns is Harbor's V1 audit redactor driver. |