journal

Documentation

Overview

Package journal provides audit logging for SPIKE components.

This package records security-relevant events as structured JSON entries, enabling compliance tracking and forensic analysis. Each audit entry captures the actor (SPIFFE ID), action, resource, timing, and outcome.

Key types:

• AuditEntry: Represents a single audit event with fields for component, user ID, action, resource path, state, and duration.
• AuditAction: Defines the type of operation (enter, exit, create, read, list, delete, undelete, blocked).
• AuditState: Indicates the outcome (audit-entry-created, audit-success, audit-errored).

Key functions:

• Audit: Writes an AuditEntry as a JSON log line to stdout.
• AuditRequest: Convenience function to log HTTP request details.

Output format:

Audit entries are written as JSON objects with a timestamp and nested audit data:

{"time":"2024-01-15T10:30:00Z","audit":{"component":"...","action":"..."}}

If JSON marshaling fails, the package calls log.FatalLn to terminate, as audit failures are considered critical in a security context.

Index

• func Audit(entry AuditEntry)
• func AuditRequest(fName string, r *http.Request, audit *AuditEntry, action AuditAction)
• type AuditAction
• type AuditEntry
• type AuditLogLine
• type AuditState

Functions

func Audit

func Audit(entry AuditEntry)

Audit logs an audit entry as JSON to the standard log output. If JSON marshaling fails, it logs an error using the structured logger but continues execution.

func AuditRequest

func AuditRequest(fName string,
	r *http.Request, audit *AuditEntry, action AuditAction)

AuditRequest logs the details of an HTTP request and updates the audit entry with the specified action. It captures the HTTP method, path, and query parameters of the request for audit logging purposes.

Parameters:

• fName: The name of the function or component making the request
• r: The HTTP request being audited
• audit: A pointer to the AuditEntry to be updated
• action: The AuditAction to be recorded in the audit entry

Types

type AuditAction

type AuditAction string

const AuditBlocked AuditAction = "blocked"

const AuditCreate AuditAction = "create"

const AuditDelete AuditAction = "delete"

const AuditEnter AuditAction = "enter"

const AuditExit AuditAction = "exit"

const AuditFallback AuditAction = "fallback"

const AuditList AuditAction = "list"

const AuditRead AuditAction = "read"

const AuditUndelete AuditAction = "undelete"

type AuditEntry

type AuditEntry struct {
	// Component is the name of the component that performed the action.
	Component string

	// TrailID is a unique identifier for the audit trail
	TrailID string

	// Timestamp indicates when the audited action occurred
	Timestamp time.Time

	// UserID identifies the user who performed the action
	UserID string

	// Action describes what operation was performed
	Action AuditAction

	// Path is the URL path of the request
	Path string

	// Resource identifies the object or entity acted upon
	Resource string

	// SessionID links the action to a specific user session
	SessionID string

	// State represents the state of the resource after the action
	State AuditState

	// Err contains an error message if the action failed
	Err string

	// Duration is the time taken to process the action
	Duration time.Duration
}

AuditEntry represents a single audit log entry containing information about user actions within the system.

type AuditLogLine

type AuditLogLine struct {
	Timestamp  time.Time  `json:"time"`
	AuditEntry AuditEntry `json:"audit"`
}

type AuditState

type AuditState string

const AuditEntryCreated AuditState = "audit-entry-created"

const AuditErrored AuditState = "audit-errored"

const AuditSuccess AuditState = "audit-success"