audit

package
v0.25.3 Latest Latest
Warning

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

Go to latest
Published: Sep 10, 2026 License: BSD-3-Clause-Clear Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// Currently setting AUDIT level to 10, a level above ERROR so it is always logged
	LevelAudit    = slog.Level(10)
	LevelAuditStr = "AUDIT"
)

From the Slog docs (https://betterstack.com/community/guides/logging/logging-in-go/#customizing-slog-levels): The log/slog package provides four log levels by default, with each one associated with an integer value: DEBUG (-4), INFO (0), WARN (4), and ERROR (8).

Variables

View Source
var (
	ErrAuditTypeRegistrationSealed = errors.New("audit type registrations are sealed")
	ErrInvalidAuditTypeName        = errors.New("audit type name must not be empty")
	ErrAuditTypeAlreadyRegistered  = errors.New("audit type is already registered")
)
View Source
var (
	// ErrReservedAuditPath indicates a claim destination targets a protected audit field.
	ErrReservedAuditPath = errors.New("reserved audit path")
	// ErrUnknownAuditPath indicates a claim destination traverses an unknown closed-schema path.
	ErrUnknownAuditPath = errors.New("unknown audit path")
	// ErrAuditContainerPath indicates a claim destination resolves to a container instead of a writable leaf.
	ErrAuditContainerPath = errors.New("audit path resolves to a container")
	// ErrOverlappingAuditPaths indicates two claim destinations conflict because one is a prefix of the other.
	ErrOverlappingAuditPaths = errors.New("overlapping audit paths")
)
View Source
var (
	TestPolicyObjectVersionEnum_name = map[int32]string{
		0: "TEST_POLICY_OBJECT_VERSION_ENUM_UNSPECIFIED",
		1: "TEST_POLICY_OBJECT_VERSION_ENUM_OLD",
		2: "TEST_POLICY_OBJECT_VERSION_ENUM_NEW",
	}
	TestPolicyObjectVersionEnum_value = map[string]int32{
		"TEST_POLICY_OBJECT_VERSION_ENUM_UNSPECIFIED": 0,
		"TEST_POLICY_OBJECT_VERSION_ENUM_OLD":         1,
		"TEST_POLICY_OBJECT_VERSION_ENUM_NEW":         2,
	}
)

Enum value maps for TestPolicyObjectVersionEnum.

View Source
var File_logger_audit_test_proto protoreflect.FileDescriptor

Functions

func ApplyTypeRegistrations added in v0.25.2

func ApplyTypeRegistrations(reg TypeRegistrations) error

func ContextServerInterceptor

func ContextServerInterceptor(logger *Logger) connect.UnaryInterceptorFunc

ContextServerInterceptor allows audit events to track request state. This is required for audit logging.

func ContextWithActorID added in v0.12.0

func ContextWithActorID(ctx context.Context, actorID string) context.Context

func LogAuditEvent added in v0.12.0

func LogAuditEvent(ctx context.Context, verb Verb, event *EventObject)

func RegisterActionResult added in v0.25.2

func RegisterActionResult(ar ActionResult, name string) error

RegisterActionResult registers the emitted name for an additional action result. It must be called before the platform seals registrations during startup, and it cannot rename an already registered result.

func RegisterActionType added in v0.25.2

func RegisterActionType(at ActionType, name string) error

RegisterActionType registers the emitted name for an additional action type. It must be called before the platform seals registrations during startup, and it cannot rename an already registered type.

func RegisterObjectType added in v0.25.2

func RegisterObjectType(ot ObjectType, name string) error

RegisterObjectType registers the emitted name for an additional object type. It must be called before the platform seals registrations during startup, and it cannot rename an already registered type.

func ReplaceAttrAuditLevel

func ReplaceAttrAuditLevel(_ []string, a slog.Attr) slog.Attr

Used to support custom log levels showing up with custom labels as well see https://betterstack.com/community/guides/logging/logging-in-go/#creating-custom-log-levels

func SealTypeRegistrations added in v0.25.2

func SealTypeRegistrations()

SealTypeRegistrations blocks any further audit type registrations. The platform calls this during startup once all registrations have been applied.

Types

type ActionResult

type ActionResult int
const (
	ActionResultSuccess ActionResult = iota
	ActionResultFailure
	ActionResultError
	ActionResultEncrypt
	ActionResultBlock
	ActionResultIgnore
	ActionResultOverride
	ActionResultCancel
)

func (ActionResult) MarshalJSON

func (ar ActionResult) MarshalJSON() ([]byte, error)

func (ActionResult) String

func (ar ActionResult) String() string

type ActionType

type ActionType int
const (
	ActionTypeCreate ActionType = iota
	ActionTypeRead
	ActionTypeUpdate
	ActionTypeDelete
	ActionTypeRewrap
	ActionTypeRotate
)

func (ActionType) MarshalJSON

func (at ActionType) MarshalJSON() ([]byte, error)

func (ActionType) String

func (at ActionType) String() string

type Config added in v0.19.0

type Config struct {
	// JWTClaimMappings writes JWT claims to configured destinations in the audit
	// log output, preserving the original JSON value types where possible.
	JWTClaimMappings []JWTClaimMapping `mapstructure:"jwt_claim_mappings" json:"jwt_claim_mappings"`
}

Config contains platform-wide audit configuration.

func (Config) Validate added in v0.19.0

func (c Config) Validate() error

type ContextData

type ContextData struct {
	RequestID uuid.UUID
	UserAgent string
	RequestIP string
	ActorID   string
}

func GetAuditDataFromContext

func GetAuditDataFromContext(ctx context.Context) ContextData

GetAuditDataFromContext gets relevant audit data from the context object

func (ContextData) LogValue added in v0.4.25

func (c ContextData) LogValue() slog.Value

type DecisionResult

type DecisionResult int
const (
	GetDecisionResultPermit DecisionResult = iota
	GetDecisionResultDeny
)

func (DecisionResult) String

func (dr DecisionResult) String() string

type EntityChainEntitlement

type EntityChainEntitlement struct {
	EntityID                 string   `json:"entityId"`
	EntityCatagory           string   `json:"entityCatagory"`
	AttributeValueReferences []string `json:"attributeValueReferences"`
}

type EntityDecision

type EntityDecision struct {
	EntityID     string   `json:"id"`
	Decision     string   `json:"decision"`
	Entitlements []string `json:"entitlements"`
}

type EventClientInfo added in v0.25.2

type EventClientInfo struct {
	UserAgent string `json:"userAgent" audit:"reserved"`
	Platform  string `json:"platform" audit:"reserved"`
	RequestIP string `json:"requestIP" audit:"reserved"`
}

type EventMetaData added in v0.25.2

type EventMetaData map[string]any

Public event DTOs are intentionally separate from internal log types. This keeps downstream consumers decoupled from internal logging behavior (e.g. LogValue), while still allowing them to construct events via NewEvent.

type EventObject

type EventObject struct {
	Object        auditEventObject   `json:"object"`
	Action        eventAction        `json:"action"`
	Actor         auditEventActor    `json:"actor"`
	EventMetaData auditEventMetadata `json:"eventMetaData" audit:"extensible"`
	ClientInfo    eventClientInfo    `json:"clientInfo"`

	Original  map[string]any `json:"original,omitempty" audit:"extensible"`
	Updated   map[string]any `json:"updated,omitempty" audit:"extensible"`
	RequestID uuid.UUID      `json:"requestID" audit:"reserved"`
	Timestamp string         `json:"timestamp" audit:"reserved"`
}

event

func CreateGetDecisionEvent

func CreateGetDecisionEvent(ctx context.Context, params GetDecisionEventParams) (*EventObject, error)

func CreatePolicyEvent

func CreatePolicyEvent(ctx context.Context, isSuccess bool, params PolicyEventParams) (*EventObject, error)
 TODO: Changes to oneOf proto properties are not yet audited correctly with the existing code.

	The Updated event object will contain both the original and updated oneOf properties due to
	the logic for merging maps within this function.  We will need to find a way to support them
	correctly in the near future.

func CreateRewrapAuditEvent

func CreateRewrapAuditEvent(ctx context.Context, params RewrapAuditEventParams) (*EventObject, error)

func CreateV2GetDecisionEvent added in v0.7.0

func CreateV2GetDecisionEvent(ctx context.Context, params GetDecisionV2EventParams) (*EventObject, error)

func NewEvent added in v0.25.2

func NewEvent(params EventObjectParams) *EventObject

NewEvent converts public DTOs into the internal log event type.

func (EventObject) LogValue added in v0.4.25

func (e EventObject) LogValue() slog.Value

type EventObjectAction added in v0.25.2

type EventObjectAction struct {
	Type   ActionType   `json:"type" audit:"reserved"`
	Result ActionResult `json:"result" audit:"reserved"`
}

type EventObjectActor added in v0.25.2

type EventObjectActor struct {
	ID         string `json:"id" audit:"reserved"`
	Attributes []any  `json:"attributes"`
}

type EventObjectAttributes added in v0.25.2

type EventObjectAttributes struct {
	Assertions  []string `json:"assertions,omitempty"`
	Attrs       []string `json:"attrs,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
}

type EventObjectInfo added in v0.25.2

type EventObjectInfo struct {
	Type       ObjectType            `json:"type"`
	ID         string                `json:"id"`
	Name       string                `json:"name,omitempty"`
	Attributes EventObjectAttributes `json:"attributes,omitempty"`
}

EventObjectInfo describes the object an audited action was performed on.

type EventObjectParams added in v0.25.2

type EventObjectParams struct {
	Object        EventObjectInfo
	Action        EventObjectAction
	Actor         EventObjectActor
	EventMetaData EventMetaData
	ClientInfo    EventClientInfo
	Original      map[string]any
	Updated       map[string]any
	RequestID     uuid.UUID
	Timestamp     string
}

type GetDecisionEventParams

type GetDecisionEventParams struct {
	Decision                DecisionResult
	EntityChainEntitlements []EntityChainEntitlement
	EntityChainID           string
	EntityDecisions         []EntityDecision
	ResourceAttributeID     string
	FQNs                    []string
}

type GetDecisionV2EventParams added in v0.7.0

type GetDecisionV2EventParams struct {
	EntityID                       string
	ActionName                     string
	Decision                       DecisionResult
	Entitlements                   subjectmappingbuiltin.AttributeValueFQNsToActions
	FulfillableObligationValueFQNs []string
	ObligationsSatisfied           bool
	// Allow ResourceDecisions to be typed by the caller as structure is in-flight
	ResourceDecisions any
}

type JWTClaimMapping added in v0.19.0

type JWTClaimMapping struct {
	Claim string `mapstructure:"claim" json:"claim"`
	Path  string `mapstructure:"path" json:"path"`
}

JWTClaimMapping maps a JWT claim to a destination in the emitted audit log. The destination path uses dot notation over the audit log output shape, e.g. `eventMetaData.requester.sub`.

type KasAttribute

type KasAttribute struct {
	URI string
}

type KasPolicy

type KasPolicy struct {
	UUID uuid.UUID
	Body KasPolicyBody
}

type KasPolicyBody

type KasPolicyBody struct {
	DataAttributes []KasAttribute
	Dissem         []string
}

type Logger

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

func CreateAuditLogger

func CreateAuditLogger(logger slog.Logger) *Logger

func (*Logger) ApplyConfig added in v0.19.0

func (a *Logger) ApplyConfig(cfg Config) error

ApplyConfig validates and stores the latest audit enrichment configuration.

func (*Logger) Detach added in v0.25.1

func (a *Logger) Detach(ctx context.Context) context.Context

Detach returns a non-canceling context with an independent copy of the current request's audit attribution. It does not copy pending audit events. Consumers can add cancellation appropriate to the detached work's lifecycle. Detached audit transactions must log policy events with LogPolicyCRUD; buffered audit methods are only valid for interceptor-owned transactions.

func (*Logger) GetDecision

func (a *Logger) GetDecision(ctx context.Context, eventParams GetDecisionEventParams)

func (*Logger) GetDecisionV2 added in v0.7.0

func (a *Logger) GetDecisionV2(ctx context.Context, eventParams GetDecisionV2EventParams)

func (*Logger) LogPolicyCRUD added in v0.25.1

func (a *Logger) LogPolicyCRUD(ctx context.Context, isSuccess bool, eventParams PolicyEventParams)

LogPolicyCRUD creates and immediately emits a policy CRUD audit event. It is intended for work whose lifetime is not owned by an RPC audit transaction. If you are within a synchronous policy operation you should use: PolicyCRUDSuccess/Failure. ! Use this carefully to avoid duplication of audit events from being recorded.

func (*Logger) PolicyCRUDFailure

func (a *Logger) PolicyCRUDFailure(ctx context.Context, eventParams PolicyEventParams)

func (*Logger) PolicyCRUDSuccess

func (a *Logger) PolicyCRUDSuccess(ctx context.Context, eventParams PolicyEventParams)

func (*Logger) RewrapFailure

func (a *Logger) RewrapFailure(ctx context.Context, eventParams RewrapAuditEventParams)

func (*Logger) RewrapSuccess

func (a *Logger) RewrapSuccess(ctx context.Context, eventParams RewrapAuditEventParams)

func (*Logger) With

func (a *Logger) With(key string, value string) *Logger

type ObjectType

type ObjectType int
const (
	ObjectTypeSubjectMapping ObjectType = iota
	ObjectTypeResourceMapping
	ObjectTypeAttributeDefinition
	ObjectTypeAttributeValue
	ObjectTypeObligationDefinition
	ObjectTypeObligationValue
	ObjectTypeObligationTrigger
	ObjectTypeNamespace
	ObjectTypeConditionSet
	ObjectTypeKasRegistry
	ObjectTypeKasAttributeNamespaceAssignment
	ObjectTypeKasAttributeDefinitionAssignment
	ObjectTypeKasAttributeValueAssignment
	ObjectTypeKeyObject
	ObjectTypeEntityObject
	ObjectTypeResourceMappingGroup
	ObjectTypePublicKey
	ObjectTypeAction
	ObjectTypeRegisteredResource
	ObjectTypeRegisteredResourceValue
	ObjectTypeKeyManagementProviderConfig
	ObjectTypeKasRegistryKeys
	ObjectTypeKasAttributeDefinitionKeyAssignment
	ObjectTypeKasAttributeValueKeyAssignment
	ObjectTypeKasAttributeNamespaceKeyAssignment
	ObjectTypeDynamicValueMapping
)

func (ObjectType) MarshalJSON

func (ot ObjectType) MarshalJSON() ([]byte, error)

func (ObjectType) String

func (ot ObjectType) String() string

type PolicyEventParams

type PolicyEventParams struct {
	ActionType ActionType
	ObjectID   string
	ObjectType ObjectType

	Original proto.Message
	Updated  proto.Message
}

type RewrapAuditEventParams

type RewrapAuditEventParams struct {
	Policy        KasPolicy
	IsSuccess     bool
	TDFFormat     string
	Algorithm     string
	PolicyBinding string
	KeyID         string
}

type TestPolicyObject added in v0.4.24

type TestPolicyObject struct {
	Id      string                      `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	Active  *wrapperspb.BoolValue       `protobuf:"bytes,2,opt,name=active,proto3" json:"active,omitempty"`
	Version TestPolicyObjectVersionEnum `protobuf:"varint,3,opt,name=version,proto3,enum=service.logger.audit.TestPolicyObjectVersionEnum" json:"version,omitempty"`
	// add array field
	Tags []string `protobuf:"bytes,5,rep,name=tags,proto3" json:"tags,omitempty"`
	// add oneOf simulated field that has either a scalar or struct value
	//
	// Types that are assignable to PolicyUser:
	//
	//	*TestPolicyObject_Username
	//	*TestPolicyObject_User
	PolicyUser isTestPolicyObject_PolicyUser `protobuf_oneof:"policy_user"`
	Metadata   *common.Metadata              `protobuf:"bytes,4,opt,name=metadata,proto3" json:"metadata,omitempty"`
	// contains filtered or unexported fields
}

func (*TestPolicyObject) Descriptor deprecated added in v0.4.24

func (*TestPolicyObject) Descriptor() ([]byte, []int)

Deprecated: Use TestPolicyObject.ProtoReflect.Descriptor instead.

func (*TestPolicyObject) GetActive added in v0.4.24

func (x *TestPolicyObject) GetActive() *wrapperspb.BoolValue

func (*TestPolicyObject) GetId added in v0.4.24

func (x *TestPolicyObject) GetId() string

func (*TestPolicyObject) GetMetadata added in v0.4.24

func (x *TestPolicyObject) GetMetadata() *common.Metadata

func (*TestPolicyObject) GetPolicyUser added in v0.4.24

func (m *TestPolicyObject) GetPolicyUser() isTestPolicyObject_PolicyUser

func (*TestPolicyObject) GetTags added in v0.4.24

func (x *TestPolicyObject) GetTags() []string

func (*TestPolicyObject) GetUser added in v0.4.24

func (x *TestPolicyObject) GetUser() *User

func (*TestPolicyObject) GetUsername added in v0.4.24

func (x *TestPolicyObject) GetUsername() string

func (*TestPolicyObject) GetVersion added in v0.4.24

func (*TestPolicyObject) ProtoMessage added in v0.4.24

func (*TestPolicyObject) ProtoMessage()

func (*TestPolicyObject) ProtoReflect added in v0.4.24

func (x *TestPolicyObject) ProtoReflect() protoreflect.Message

func (*TestPolicyObject) Reset added in v0.4.24

func (x *TestPolicyObject) Reset()

func (*TestPolicyObject) String added in v0.4.24

func (x *TestPolicyObject) String() string

type TestPolicyObjectVersionEnum added in v0.4.24

type TestPolicyObjectVersionEnum int32

buflint ENUM_VALUE_PREFIX: to make sure that C++ scoping rules aren't violated when users add new enum values to an enum in a given package

const (
	TestPolicyObjectVersionEnum_TEST_POLICY_OBJECT_VERSION_ENUM_UNSPECIFIED TestPolicyObjectVersionEnum = 0
	TestPolicyObjectVersionEnum_TEST_POLICY_OBJECT_VERSION_ENUM_OLD         TestPolicyObjectVersionEnum = 1
	TestPolicyObjectVersionEnum_TEST_POLICY_OBJECT_VERSION_ENUM_NEW         TestPolicyObjectVersionEnum = 2
)

func (TestPolicyObjectVersionEnum) Descriptor added in v0.4.24

func (TestPolicyObjectVersionEnum) Enum added in v0.4.24

func (TestPolicyObjectVersionEnum) EnumDescriptor deprecated added in v0.4.24

func (TestPolicyObjectVersionEnum) EnumDescriptor() ([]byte, []int)

Deprecated: Use TestPolicyObjectVersionEnum.Descriptor instead.

func (TestPolicyObjectVersionEnum) Number added in v0.4.24

func (TestPolicyObjectVersionEnum) String added in v0.4.24

func (TestPolicyObjectVersionEnum) Type added in v0.4.24

type TestPolicyObject_User added in v0.4.24

type TestPolicyObject_User struct {
	User *User `protobuf:"bytes,7,opt,name=user,proto3,oneof"`
}

type TestPolicyObject_Username added in v0.4.24

type TestPolicyObject_Username struct {
	Username string `protobuf:"bytes,6,opt,name=username,proto3,oneof"`
}

type TypeRegistrations added in v0.25.2

type TypeRegistrations struct {
	ObjectTypes   map[ObjectType]string
	ActionTypes   map[ActionType]string
	ActionResults map[ActionResult]string
}

type User added in v0.4.24

type User struct {
	Id   string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
	// contains filtered or unexported fields
}

func (*User) Descriptor deprecated added in v0.4.24

func (*User) Descriptor() ([]byte, []int)

Deprecated: Use User.ProtoReflect.Descriptor instead.

func (*User) GetId added in v0.4.24

func (x *User) GetId() string

func (*User) GetName added in v0.4.24

func (x *User) GetName() string

func (*User) ProtoMessage added in v0.4.24

func (*User) ProtoMessage()

func (*User) ProtoReflect added in v0.4.24

func (x *User) ProtoReflect() protoreflect.Message

func (*User) Reset added in v0.4.24

func (x *User) Reset()

func (*User) String added in v0.4.24

func (x *User) String() string

type Verb added in v0.12.0

type Verb string
const (
	VerbDecision   Verb = "decision"
	VerbPolicyCRUD Verb = "policy crud"
	VerbRewrap     Verb = "rewrap"
)

Jump to

Keyboard shortcuts

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