Create security logs someone can investigate

Choose the decisions responders need to reconstruct: who changed a role, why an authorization check failed, which session was revoked, or whether an export completed. Infrastructure access logs rarely explain all of these application decisions. Assign each event a clear meaning before adding more fields.

Use a consistent event vocabulary across services. Record an event type, timestamp, service/version, actor reference where appropriate, operation, target reference, outcome, reason category, and correlation identifier. Distinguish an attempted action from its successful completion so a request log is not mistaken for proof of a business effect.

Logs your customers cannot get do not help them. In the 2023 Storm-0558 intrusion, the only victim to detect it did so with a mailbox access log that required a premium licence, and other victims could not see past activity at all: /domains/identity-crypto/authentication/case-study-storm-0558/.

An incident responder asks whether a support operator changed a customer’s role. An access log contains POST /roles with status 200. That line establishes an HTTP response, not the resulting authorization state: the handler may return before a worker commits, or the response may describe an accepted request. Define separate events for the request, policy decision and committed effect, and connect them with an operation identifier.

Use a stable actor reference from verified identity, a target reference, tenant, action, outcome and reason category. Add service revision and policy version so the responder can reconstruct which rule ran. In the example, operation op-41 was denied by tenant-policy-v8; op-42 was allowed and later committed. request_id changes on retries, while operation_id identifies one logical action. Neither identifier should be a bearer token or raw session cookie.

The record below intentionally avoids free-form request bodies. A malicious display name containing a newline remains data inside a JSON string rather than a forged second log entry; the fix card at /fix/crlf-log-injection/ covers plain-text logs. Even a structured logger needs bounded fields and safe downstream rendering: a spreadsheet export can interpret formula prefixes, and a web console can render HTML unsafely. The logging transport should preserve event boundaries and authenticity, not simply concatenate user input with text.

A durable audit event can be coordinated with a business transaction through an outbox: commit the role change and its pending audit record together, then deliver the audit record asynchronously with deduplication. This closes a particular gap between committed changes and lost logs. It does not prove the collector is immutable or that the actor was legitimate. Decide which operations must refuse to proceed when their required evidence cannot be persisted, rather than making every logging outage either fail-open or a site-wide denial of service.

{"event":"role_change.denied","operation_id":"op-41","actor":"support-7","tenant":"north","target":"south:user-9","reason":"tenant_boundary","policy":"tenant-policy-v8","service_revision":"r52"}
{"event":"role_change.accepted","operation_id":"op-42","actor":"support-7","tenant":"north","target":"north:user-3"}
{"event":"role_change.committed","operation_id":"op-42","actor":"support-7","tenant":"north","target":"north:user-3","old_role":"reader","new_role":"editor","audit_sequence":918}

The module below configures pino 10 for security events: one JSON object per line, UTC timestamps, service fields on every event, a fixed message per event name and redaction of the Authorization header, cookies, passwords and tokens. Logging the denied and committed role changes from the example produced exactly two lines, even though the display name contained a newline followed by a forged role_change.committed event: the newline was written as \n inside the JSON string. The bearer token and the nested token were replaced by [REDACTED].

Redaction is path-based. In the same test *.token matched credentials.token but not a top-level token or session.auth.token, both of which were logged in clear text. List every path, keep secrets out of event objects in the first place, and test with canary values at several depths.

// Structured security events with pino 10: JSON lines, UTC timestamps and redaction of credentials.
import pino from 'pino';

export const audit = pino({
  base: {service: 'accounts', service_version: 'r52'},
  timestamp: pino.stdTimeFunctions.isoTime, // "time":"2026-10-10T09:00:00.000Z"
  redact: {
    paths: ['req.headers.authorization', 'req.headers.cookie', '*.password', '*.token'],
    censor: '[REDACTED]',
  },
});

// One event per decision; the message is a fixed event name, never user input.
export function roleChange(stage, fields) {
  audit.info({event: `role_change.${stage}`, ...fields}, `role_change.${stage}`);
}

• Exclude passwords, bearer tokens, raw session identifiers, unnecessary personal data, and full sensitive request or response bodies.
• Use structured logging and safely encode untrusted field values. Bound field lengths and prevent line breaks or delimiters from forging additional events.
• Protect transport and storage, restrict access, monitor changes to collection, and define retention and disposal for the actual investigation need.
• Maintain time synchronization and record collection delays. Do not silently sample away events essential to an audit or incident sequence.
• Choose severity from context. A single rejected request is not automatically a critical incident; repeated or consequential patterns may deserve escalation.

A common schema lets the SIEM correlate your security events with audit logs from other systems and the rest of your observability data. The Elastic Common Schema is being merged into the OpenTelemetry semantic conventions; OCSF is used by Amazon Security Lake and other security data platforms. The table maps the vocabulary of the worked example; in OCSF 1.9 a role change belongs to the User Management class, with activity 16, Assign Roles; the older User Access Management class is deprecated.

Generate synthetic authentication, authorization, administrative-change, and revocation events in a test environment. Verify that each arrives with the correct meaning and can be correlated without exposing a secret. Include malicious-looking names, very long values, and unavailable log storage.

Confirm that logging failures have a deliberate service behavior and raise an operational signal without recursively flooding logs. Exercise one alert through acknowledgment and investigation, as the runtime detection and response guide at /domains/runtime/detection/runtime-detection-response/ describes. Preserve event definitions, example records, retention settings, and owners. A dashboard of collected bytes demonstrates ingestion; a responder answering the original investigation question demonstrates usefulness.

Ordering solely by collector timestamps can reverse a real sequence when events are delayed or clocks disagree. Preserve event time and ingestion time, use operation IDs and supported sequence/transaction identifiers, and record clock uncertainty where it affects conclusions. Do not invent a precise order from timestamps with overlapping uncertainty.

High log volume is not the same as good detection. A denied request may be routine; a rare allowed privilege change may deserve stronger attention. Define which events must not be sampled, then test that a responder can answer one concrete question using retained records. Review who can delete, modify or disable collection and alert on changes to that path.

These outcomes belong to the worked example; the logger test above covers the encoding and redaction rows, and the delivery rows need a test of your own collector.

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. OWASP Logging
2. OWASP Logging Vocabulary
3. OWASP ASVS 5.0 V16 Security Logging and Error Handling. Version 5.0.0.
4. OWASP Top 10:2025 A09 Security Logging and Alerting Failures
5. CWE-117: improper output neutralization for logs. CWE version 4.20.
6. pino: redaction
7. Elastic Common Schema: event fields
8. OCSF schema 1.9.0: User Management

Reference information

Tags

InjectionError handling and information disclosureLogging and detectionIncident response

SDLC phase

Maintenance

Role

DevelopersAppSec engineersPlatform engineers and SREs

ASVS 5.0.0 requirements

v5.0.0-16.2.1 · v5.0.0-16.2.5 · v5.0.0-16.3.2 · v5.0.0-16.4.1 · v5.0.0-16.4.3

Download this guide as Markdown

Continue exploring