Security Audit Logging

Version boundary

Target Spring Boot 4 with Spring Framework 7 and Spring Security 7. Check the selected release's Actuator audit APIs before wiring listeners. The shipped Java 17 record has no Boot/Jackson dependency and is shared across both trees.

Event contract

Choose events needed for the requested security or business requirement: authentication decisions, access denial, privilege changes, sensitive exports and administrative actions. Separate attempted, denied, successful and failed operations. Do not log SUCCESS before the authoritative transaction commits.

Prefer typed fields: event ID, UTC time, verified actor ID, tenant ID, action, target ID, outcome and server-generated correlation ID. Unauthenticated events may have no actor; do not mislabel a supplied username as verified identity. Record only identifiers needed for the investigation, with controlled access and retention.

SecurityAuditRecord demonstrates bounded typed fields and a restricted correlation identifier. It intentionally has no arbitrary message, headers, token, request body or exception field. This is an event contract, not a durable audit sink. Use a structured serializer, never concatenate JSON or interpolate untrusted text into lines. The sample assumes tenant-scoped operations and UUID identities. Adapt those types and the success invariant to the application's actual identity model; do not invent tenants for a single-tenant system. Correlation IDs must be server-generated, not arbitrary caller text.

Delivery and access policy

• Keep credentials, cookies, bearer tokens, passwords, session secrets, sensitive prompts, private documents and full configuration out of audit records. Sanitize controls and bound any separately approved free-text fields. Hashing arbitrary identifiers is not automatic anonymization.
• Spring Boot's in-memory audit repository is for development, not durable evidence. Authentication events alone do not capture every business authorization decision.
• For committed mutations requiring durable audit, use an atomic outbox alongside the business transaction. Deliver idempotently by event ID; handle duplicate delivery, backpressure, retention and retries. An after-commit listener can still lose events on process failure.
• Explicitly choose failure behavior by operation. A required audit write may need to prevent a privileged mutation; optional read-event loss may instead trigger bounded buffering and alerts. Do not globally fail every request or silently drop required audit events.
• Separate application write permissions from investigator read and retention/delete permissions. Define export controls, clock synchronization, access auditing and integrity checks. Append-only configuration alone is not proof of tamper resistance.
• Do not publish Actuator auditevents, env or configprops to solve an investigation. Collection and external export require approved scope and a redacted handoff.

Verification and output

Exercise malformed/oversized correlation IDs, missing fields, all outcomes and stable event IDs. The local fixture tests record construction, not a production logging backend. Application integration tests must also prove rollback emits no committed-success event, outbox retry deduplicates, and sink failures follow the selected policy.

Provide a field inventory, access/retention policy, delivery semantics, failure matrix and tests run. Label evidence confirmed, suspected, or not verified rather than claiming compliance from the mere presence of log statements. See good design and bad design.

Gotchas

• Agent logs request headers or principal.toString - select typed non-secret identifiers.
• Agent writes SUCCESS before commit - tie success evidence to the committed operation.
• Agent uses in-memory events as a production ledger - choose durable, access-controlled storage.
• Agent swallows sink failures - implement the operation's documented audit failure policy.

Official sources

• Boot auditing
• OWASP logging guidance
• Spring transaction-bound events

# Audit anti-pattern

Log "SUCCESS" with the full request headers before persisting a role change; catch and ignore
all logging errors. Store only the last 100 events in memory.

This can expose credentials, report rolled-back actions as successful, lose records on restart,
and hide failures. A development event repository is not a production audit trail.

# Audit design example

For a privileged role change, persist the role mutation and a typed outbox event in the same
transaction. If either write fails, roll back both. The dispatcher sends the event to an
access-controlled sink with the event ID as the deduplication key.

Record verified actor/tenant IDs, target ID, ROLE_CHANGE, SUCCESS and a server correlation ID.
Do not include the authorization header or a serialized user object. Alert on delayed delivery
and test rollback, duplicates and unavailable storage. This is a design example, not a shipped outbox.

package com.example.securityaudit;

import java.time.Instant;
import java.util.Objects;
import java.util.UUID;
import java.util.regex.Pattern;

public record SecurityAuditRecord(
        UUID eventId, Instant occurredAt, UUID actorId, UUID tenantId,
        Action action, UUID targetId, Outcome outcome, String correlationId) {
    public enum Action { AUTHENTICATION, DOCUMENT_READ, ROLE_CHANGE, DATA_EXPORT }
    public enum Outcome { ATTEMPTED, DENIED, SUCCESS, FAILURE }

    private static final Pattern CORRELATION_ID = Pattern.compile("[A-Za-z0-9._-]{1,64}");

    public SecurityAuditRecord {
        Objects.requireNonNull(eventId);
        Objects.requireNonNull(occurredAt);
        Objects.requireNonNull(action);
        Objects.requireNonNull(outcome);
        if (correlationId == null || !CORRELATION_ID.matcher(correlationId).matches()) {
            throw new IllegalArgumentException("Invalid correlation ID");
        }
        // Nullable identities support unauthenticated attempts, not unverified caller claims.
        if (outcome == Outcome.SUCCESS && (actorId == null || tenantId == null)) {
            throw new IllegalArgumentException("Successful events require verified actor and tenant");
        }
    }
}

claude plugin marketplace add rrezartprebreza/spring-boot-skills
claude plugin install spring-boot-4-skills@spring-boot-skills

codex plugin marketplace add rrezartprebreza/spring-boot-skills
codex plugin add spring-boot-4-skills@spring-boot-skills