auditing

package
v0.5.2 Latest Latest
Warning

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

 Go to latest Published: May 2, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package auditing is the single source of truth for AuditEvent emission across broker, proxy, webhook, and controller. It exports a Sink interface, a KubeSink that calls client.Create, and per-kind builder functions. Callers decide fail-closed vs fail-open on a Sink.Write error; see Phase 2c spec §3.1 for the policy table.

Index

Constants

This section is empty.

Variables

View Source 
var ErrAuditWrite = errors.New("audit write failed")

ErrAuditWrite wraps every Sink.Write failure. Callers test with errors.Is so a transport switch (etcd → Loki, hypothetically) doesn't require call-site changes.

Functions

func NewBrokerCredsTampered 

func NewBrokerCredsTampered(in BrokerCredsTamperedInput) *paddockv1alpha1.AuditEvent

NewBrokerCredsTampered builds a broker-creds-tampered AuditEvent (controller detected and pruned unexpected keys on the per-run broker-creds Secret). Decision is Warned — nothing was blocked, the system auto-recovered, but operators should know tampering was attempted. F-41 residual.

func NewCAMisconfigured 

func NewCAMisconfigured(in CAMisconfiguredInput) *paddockv1alpha1.AuditEvent

NewCAMisconfigured builds a ca-misconfigured AuditEvent. Emitted when a Workspace's source CA Secret has a missing/empty key, or when cert-manager has reported a permanent issuance failure for the per-Workspace Certificate. F-51.

func NewCAProjected 

func NewCAProjected(in CAProjectionInput) *paddockv1alpha1.AuditEvent

NewCAProjected builds a ca-projected AuditEvent (controller CA Secret create — proxy-tls or broker-ca).

func NewCredentialDenied 

func NewCredentialDenied(in CredentialDeniedInput) *paddockv1alpha1.AuditEvent

NewCredentialDenied builds a credential-denied AuditEvent.

func NewCredentialIssued 

func NewCredentialIssued(in CredentialIssuedInput) *paddockv1alpha1.AuditEvent

NewCredentialIssued builds a credential-issued AuditEvent.

func NewCredentialRenewalFailed 

func NewCredentialRenewalFailed(in CredentialRenewalFailedInput) *paddockv1alpha1.AuditEvent

NewCredentialRenewalFailed builds a credential-renewal-failed AuditEvent.

func NewCredentialRenewed 

func NewCredentialRenewed(in CredentialRenewedInput) *paddockv1alpha1.AuditEvent

NewCredentialRenewed builds a credential-renewed AuditEvent. Decision is always Granted — failures use NewCredentialRenewalFailed.

func NewCredentialRevoked 

func NewCredentialRevoked(in CredentialRevokedInput) *paddockv1alpha1.AuditEvent

NewCredentialRevoked builds a credential-revoked AuditEvent. Decision is Granted (revocation is a successful action) — the action category is conveyed by Kind, not Decision.

func NewEgressAllow 

func NewEgressAllow(in EgressInput) *paddockv1alpha1.AuditEvent

NewEgressAllow builds an egress-allow AuditEvent (default kind), or emits Kind override when set (egress-discovery-allow).

func NewEgressBlock 

func NewEgressBlock(in EgressInput) *paddockv1alpha1.AuditEvent

NewEgressBlock builds an egress-block AuditEvent.

func NewEgressDiscoveryAllow 

func NewEgressDiscoveryAllow(in EgressInput) *paddockv1alpha1.AuditEvent

NewEgressDiscoveryAllow builds an egress-discovery-allow AuditEvent.

func NewInteractiveRunTerminated 

func NewInteractiveRunTerminated(in InteractiveRunTerminatedInput) *paddockv1alpha1.AuditEvent

NewInteractiveRunTerminated builds an interactive-run-terminated AuditEvent.

func NewInterceptionModeCooperativeAccepted 

func NewInterceptionModeCooperativeAccepted(in InterceptionInput) *paddockv1alpha1.AuditEvent

NewInterceptionModeCooperativeAccepted builds an interception-mode-cooperative-accepted AuditEvent. Emitted once at proxy startup when --mode=cooperative; carries the BrokerPolicy cooperativeAccepted.reason for the audit trail (F-19 residual).

func NewNetworkPolicyEnforcementWithdrawn 

func NewNetworkPolicyEnforcementWithdrawn(in NetworkPolicyEnforcementWithdrawnInput) *paddockv1alpha1.AuditEvent

NewNetworkPolicyEnforcementWithdrawn builds a network-policy-enforcement-withdrawn AuditEvent. Emitted by the controller when the per-run NetworkPolicy was re-created in response to an operator-side deletion (caught by F-41's Owns() watch). The decision is warned because nothing was blocked — the system auto-recovered, but operators should know the deletion happened.

func NewPolicyApplied 

func NewPolicyApplied(in AdmissionInput) *paddockv1alpha1.AuditEvent

NewPolicyApplied builds a policy-applied AuditEvent (admission admit).

func NewPolicyRejected 

func NewPolicyRejected(in AdmissionInput) *paddockv1alpha1.AuditEvent

NewPolicyRejected builds a policy-rejected AuditEvent (admission reject).

func NewPromptCompleted 

func NewPromptCompleted(in PromptCompletedInput) *paddockv1alpha1.AuditEvent

NewPromptCompleted builds a prompt-completed AuditEvent.

func NewPromptSubmitted 

func NewPromptSubmitted(in PromptAuditInput) *paddockv1alpha1.AuditEvent

NewPromptSubmitted builds a prompt-submitted AuditEvent.

func NewRunCompleted 

func NewRunCompleted(in RunDecisionInput) *paddockv1alpha1.AuditEvent

NewRunCompleted builds a run-completed AuditEvent (controller terminal-phase commit).

func NewRunFailed 

func NewRunFailed(in RunDecisionInput) *paddockv1alpha1.AuditEvent

NewRunFailed builds a run-failed AuditEvent (controller fail() path).

func NewShellSessionClosed 

func NewShellSessionClosed(in ShellClosedInput) *paddockv1alpha1.AuditEvent

NewShellSessionClosed builds a shell-session-closed AuditEvent.

func NewShellSessionOpened 

func NewShellSessionOpened(in ShellOpenedInput) *paddockv1alpha1.AuditEvent

NewShellSessionOpened builds a shell-session-opened AuditEvent.

Types

type AdmissionInput 

type AdmissionInput struct {
	RunName     string
	Namespace   string
	TemplateRef string
	Reason      string
	When        time.Time
	// OwnerRef, when non-nil, is set on the AuditEvent's
	// metadata.ownerReferences. Use for ValidateUpdate (where the run
	// already exists) or ValidateCreate's admit path once the apiserver
	// assigns a UID. Leave nil for ValidateCreate.
	OwnerRef *metav1.OwnerReference
}

AdmissionInput is the flat input shape for NewPolicyApplied / NewPolicyRejected.

type BrokerCredsTamperedInput 

type BrokerCredsTamperedInput struct {
	RunName    string
	Namespace  string
	PrunedKeys []string
	When       time.Time
}

BrokerCredsTamperedInput is the flat input shape for NewBrokerCredsTampered. PrunedKeys is the sorted list of unexpected keys the controller removed from the broker-creds Secret on tamper-detect.

type CAMisconfiguredInput 

type CAMisconfiguredInput struct {
	Name      string // Workspace name (will be prefixed seed- by the caller per F-52).
	Namespace string
	Reason    string
	When      time.Time
}

CAMisconfiguredInput is the flat input shape for NewCAMisconfigured.

type CAProjectionInput 

type CAProjectionInput struct {
	RunName    string
	Namespace  string
	SecretName string
	Reason     string
	When       time.Time
}

CAProjectionInput is the flat input shape for NewCAProjected.

type CredentialDeniedInput 

type CredentialDeniedInput struct {
	RunName        string
	Namespace      string
	CredentialName string
	Provider       string
	MatchedPolicy  string
	Reason         string
	When           time.Time
}

CredentialDeniedInput is the flat input shape for NewCredentialDenied.

type CredentialIssuedInput 

type CredentialIssuedInput struct {
	RunName        string
	Namespace      string
	CredentialName string
	Provider       string
	MatchedPolicy  string
	Reason         string
	When           time.Time
	// Count, when > 0, is set on Spec.Count and signals a summary
	// (controller's "credentials projected to this run" rollup).
	Count int32
}

CredentialIssuedInput is the flat input shape for NewCredentialIssued.

type CredentialRenewalFailedInput 

type CredentialRenewalFailedInput struct {
	RunName   string
	Namespace string
	Provider  string
	LeaseID   string
	Error     string
	When      time.Time
}

CredentialRenewalFailedInput is the input shape for NewCredentialRenewalFailed.

type CredentialRenewedInput 

type CredentialRenewedInput struct {
	RunName   string
	Namespace string
	Provider  string
	LeaseID   string
	ExpiresAt time.Time // RFC3339 in Detail; zero means "no expiry"
	When      time.Time // for nowOr; tests inject deterministic time
}

CredentialRenewedInput is the input shape for NewCredentialRenewed.

type CredentialRevokedInput 

type CredentialRevokedInput struct {
	RunName        string
	Namespace      string
	CredentialName string
	Provider       string
	MatchedPolicy  string
	Reason         string
	When           time.Time
}

CredentialRevokedInput is the flat input shape for NewCredentialRevoked.

type EgressInput 

type EgressInput struct {
	RunName       string
	Namespace     string
	Host          string
	Port          int
	Decision      paddockv1alpha1.AuditDecision
	MatchedPolicy string
	Reason        string
	When          time.Time
	// Kind, when set, overrides the kind that NewEgress* would otherwise
	// pick. Used by callers that need to emit egress-discovery-allow on
	// the allow path.
	Kind paddockv1alpha1.AuditKind
}

EgressInput is the flat input shape for NewEgressAllow / NewEgressBlock / NewEgressDiscoveryAllow.

type InteractiveRunTerminatedInput 

type InteractiveRunTerminatedInput struct {
	RunName   string
	Namespace string
	Reason    string
	Decision  paddockv1alpha1.AuditDecision
	When      time.Time
}

InteractiveRunTerminatedInput is the input for NewInteractiveRunTerminated. Reason is one of: idle, detach, max-lifetime, explicit, error. Decision must be set by the caller: AuditDecisionGranted for planned terminations (idle/detach/max-lifetime/explicit) and AuditDecisionWarned for error-triggered terminations.

type InterceptionInput 

type InterceptionInput struct {
	RunName       string
	Namespace     string
	MatchedPolicy string
	Reason        string
	When          time.Time
}

InterceptionInput is the flat input shape for NewInterceptionModeCooperativeAccepted. Populated at proxy startup from the controller-passed --interception-acceptance-reason flag.

type KubeSink 

type KubeSink struct {
	Client    client.Client
	Component string
}

KubeSink is the production implementation. Component is one of "broker" | "proxy" | "webhook" | "controller" and is stamped on every emitted AuditEvent's paddock.dev/component label so consumers can disambiguate identical kinds emitted from different components (e.g., the controller's credential-issued summary vs. the broker's per-credential events).

func (*KubeSink) Write 

func (s *KubeSink) Write(ctx context.Context, ae *paddockv1alpha1.AuditEvent) error

Write stamps the component label and calls client.Create. On error it increments the paddock_audit_write_failures_total counter and returns the error wrapped in ErrAuditWrite.

type NetworkPolicyEnforcementWithdrawnInput 

type NetworkPolicyEnforcementWithdrawnInput struct {
	RunName   string
	Namespace string
	Reason    string
	When      time.Time
}

NetworkPolicyEnforcementWithdrawnInput is the flat input shape for NewNetworkPolicyEnforcementWithdrawn.

type NoopSink 

type NoopSink struct{}

NoopSink drops every event silently. Used in tests that don't care about audit emission and in local-dev binaries that have no cluster client.

func (NoopSink) Write 

func (NoopSink) Write(_ context.Context, _ *paddockv1alpha1.AuditEvent) error

Write implements Sink. Always returns nil and leaves the AuditEvent untouched.

type PromptAuditInput 

type PromptAuditInput struct {
	RunName      string
	Namespace    string
	SubmitterSA  string
	PromptHash   string
	PromptLength int
	TurnSeq      int32
	When         time.Time
}

PromptAuditInput is the input shape for NewPromptSubmitted.

type PromptCompletedInput 

type PromptCompletedInput struct {
	RunName    string
	Namespace  string
	TurnSeq    int32
	DurationMs int64
	EventCount int32
	Outcome    string // "ok" | "error" | "interrupted"
	When       time.Time
}

PromptCompletedInput is the input shape for NewPromptCompleted.

type RunDecisionInput 

type RunDecisionInput struct {
	RunName   string
	Namespace string
	Reason    string
	Decision  paddockv1alpha1.AuditDecision
	When      time.Time
}

RunDecisionInput is the flat input shape for NewRunFailed / NewRunCompleted.

type ShellClosedInput 

type ShellClosedInput struct {
	RunName    string
	Namespace  string
	SessionID  string
	DurationMs int64
	ByteCount  int64
	When       time.Time
}

ShellClosedInput is the input shape for NewShellSessionClosed.

type ShellOpenedInput 

type ShellOpenedInput struct {
	RunName     string
	Namespace   string
	SessionID   string
	SubmitterSA string
	Target      string
	Command     []string
	When        time.Time
}

ShellOpenedInput is the input shape for NewShellSessionOpened.

type Sink 

type Sink interface {
	Write(ctx context.Context, ae *paddockv1alpha1.AuditEvent) error
}

Sink writes a single AuditEvent. Implementations decide where the event lands (apiserver via KubeSink, /dev/null via NoopSink). On failure the Sink returns an error wrapping ErrAuditWrite; the caller decides whether to surface the failure or log+counter and continue.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.