Normalize cloud security logs with OCSF before writing detections

What OCSF gives a detection team

OCSF gives a detection team one vocabulary for events that come from different products. Every event carries a numeric class (class_uid), an activity inside that class (activity_id) and a derived type_uid, and it fills shared objects such as actor, api, src_endpoint, cloud and resources whose types and requirement levels the schema defines. A rule that asks which principal called which API from which address, and whether the call succeeded, can be written once against actor.user, api.operation, src_endpoint.ip and status_id instead of three times against userIdentity, caller and authenticationInfo. The schema server also validates an event against a named schema version. ^[1][2][17]

Control-plane audit records from AWS CloudTrail, the Azure Activity Log and Google Cloud Audit Logs land mostly in one class, API Activity (class_uid 6003), whose activities are Create, Read, Update, Delete and Other. Sign-ins and identity changes can land elsewhere, in Authentication or in the Identity and Access Management classes, depending on how the pipeline routes them. Amazon Security Lake, for example, classifies CloudTrail management events as API Activity, Authentication or Account Change. ^[1][3]

What OCSF does not give you is shared meaning. The schema says where a value goes; it does not say how a provider's value should be read. Whether an Azure write is a Create or an Update, whether a CloudTrail record without errorCode succeeded, and whether a Google record is the start or the end of an operation are mapping decisions, and every detection inherits them. The version gap matters too: Security Lake writes its native AWS sources as OCSF 1.1.0 and accepts custom sources up to 1.3, while the current schema release is 1.9.0. Normalize first, then treat the mapping and the schema version as part of the detection and test them with the same care as the rule. ^[1][3][4]

Categories, classes and profiles

OCSF arranges events in layers. A category groups classes by domain and carries category_uid. An event class defines the attributes for one kind of event and carries class_uid. Every class has an activity_id enum, and type_uid is computed as class_uid * 100 + activity_id, so an API Activity Update is 600303. Profiles are overlays that add a set of attributes to any class that supports them, and an event lists the profiles it uses in metadata.profiles. Extensions add classes, objects, attributes or profiles without changing the core schema. ^[2]

For cloud audit data the cloud profile matters most. In 1.9.0 it adds cloud as a required attribute and api as an optional one. API Activity itself requires actor, api, src_endpoint, time and metadata alongside the classification IDs, and recommends resources, status_id, http_request and observables. Source fields with no home go in unmapped, and the original record can travel unparsed in raw_data. When a source value has no matching enum entry, the mapping sets the ID to 99 (Other) and copies the source text into the sibling string, such as activity_name or status. ^[1][2]

Read through the schema server API on October 7, 2026, with platform extensions excluded, the 1.9.0 core schema defines 79 event classes in eight categories. Twenty-two of them are deprecated but still present. Fifteen of those sit in Discovery, where 1.5.0 replaced 14 single-purpose query classes with Evidence Info and Config State with Compliance Finding. Deprecated classes still validate and only draw a warning, which keeps old data usable and also lets a rule author pick a class from the browser without noticing that producers are moving away from it. ^[1][5]

Source. OCSF schema server API, version 1.9.0, classes endpoint with platform extensions excluded, read October 7, 2026. ^[1]

Method. Counted entries returned by /1.9.0/api/classes?extensions= per category, excluding base_event. A class is deprecated when it carries an @deprecated annotation. Cross-checked against event files in the ocsf-schema 1.9.0 tag after removing abstract category files. Windows extension classes are excluded.

Accessible table and figure data

Figure 1 accessible table

Category	Active	Deprecated
Discovery	8	15
Network Activity	11	3
System Activity	12	0
Identity & Access Management	6	2
Findings	7	1
Application Activity	7	1
Remediation	4	0
Unmanned Systems	2	0

Figure 1 accessible table

Category	Active	Deprecated
Discovery	8	15
Network Activity	11	3
System Activity	12	0
Identity & Access Management	6	2
Findings	7	1
Application Activity	7	1
Remediation	4	0
Unmanned Systems	2	0

Download imageDownload table CSV

Pin the schema version first

Each OCSF event declares its schema version in the required metadata.version attribute. Minor releases add classes, attributes, objects and profiles and are meant to stay backward compatible within the major version. Deprecation keeps the old names valid, but the replacements are new names, so a rule written against one minor version can quietly miss records produced under a later mapping. ^[2][5]

Amazon Security Lake shows how wide the spread can be. AWS source version 1 writes CloudTrail management and data events with metadata.version 1.0.0-rc.2, and source version 2 writes them as 1.1.0. Custom sources must arrive as Parquet with one OCSF class per object, and Security Lake supports OCSF 1.3 and earlier for them. A team that normalizes Azure and Google logs into Security Lake today writes to a schema six minor releases behind the current one, next to native AWS data that is eight behind. ^[3][4]

Three changes between 1.1.0 and 1.9.0 touch cloud audit rules directly. Account Change (3001) is deprecated in 1.9.0 in favor of the new User Management class (3007), and Role Management (3008) arrived in the same release. actor.user.credential_uid, the attribute a CloudTrail mapping uses for the access key ID, has been deprecated since 1.6.0 in favor of the programmatic_credentials array. And api is now a required attribute of API Activity; in 1.1.0 and 1.3.0 it came only through the cloud profile. ^[1][5]

Pick one target version per table, record it next to the mapping code, and reject or quarantine events whose metadata.version differs. If one store must hold two versions, such as native Security Lake data at 1.1.0 and custom data at 1.3, make the version an explicit predicate or a view boundary in every rule rather than assuming the shapes match.

Source. OCSF schema server API for each release, read October 7, 2026; release roles from Amazon Security Lake documentation. ^[1][3][4]

Method. Counted entries returned by /<version>/api/classes?extensions= excluding base_event; deprecated means an @deprecated annotation in that release. Only the three releases Security Lake documents and the current release are shown.

Accessible table and figure data

Figure 2 accessible table

OCSF release	Active	Deprecated
1.0.0-rc.2, Security Lake source v1	28	0
1.1.0, Security Lake source v2	40	3
1.3.0, custom source limit	61	3
1.9.0, current release	57	22

Figure 2 accessible table

OCSF release	Active	Deprecated
1.0.0-rc.2, Security Lake source v1	28	0
1.1.0, Security Lake source v2	40	3
1.3.0, custom source limit	61	3
1.9.0, current release	57	22

Download imageDownload table CSV

Map the three audit logs into API Activity

CloudTrail is the closest fit; the API Activity class description names CloudTrail as its example. The OCSF project's example mapping for 1.1.0 sets api.operation from eventName, api.service.name from eventSource, actor.user.uid from userIdentity.arn, actor.user.uid_alt from principalId, api.response.error from errorCode, api.request.data from requestParameters and http_request.user_agent from userAgent. Fill cloud.account.uid from recipientAccountId and actor.user.account.uid from userIdentity.accountId, because CloudTrail documents that the two differ in cross-account access. ^{[1][6][9][10]}

The Azure Activity Log's Administrative category maps operationName.value to api.operation, resourceProviderName.value to api.service.name, resourceId to resources[].uid, httpRequest.clientIpAddress to src_endpoint.ip and subscriptionId to cloud.account.uid. The caller needs two fields: caller holds an email address, UPN or SPN, and the object identifier claim inside claims gives a stable actor.user.uid. Keep operationId in metadata.correlation_uid, since it ties together the events of one operation. Microsoft notes that the documented schema is not strictly enforced across data sources, and the storage and Event Hubs export renames fields (callerIpAddress, resultType, identity), so write one parser per transport. ^[7]

For Google, protoPayload.methodName becomes api.operation, serviceName becomes api.service.name, resourceName becomes resources[].name, requestMetadata.callerIp becomes src_endpoint.ip and callerSuppliedUserAgent becomes http_request.user_agent, which Google warns is unauthenticated. The project identifier from the entry's monitored resource fills cloud.account.uid; the 1.9.0 schema describes the account object as the project for Google Cloud. authenticationInfo.principalEmail fits actor.user.email_addr, and third-party identities populate principalSubject instead. The log name identifies which of the four audit logs produced the entry; keep it in metadata.log_name so a rule can tell Admin Activity from Data Access. ^[1][8][11]

The example below is a hypothetical CloudTrail StopLogging call after normalization. Submitted to the OCSF 1.9.0 validator on October 7, 2026, it returned no errors and no warnings. An earlier draft that used actor.user.credential_uid drew a deprecation warning, which is the kind of drift the version pin is meant to catch. ^[17]

{
  "class_uid": 6003,
  "category_uid": 6,
  "activity_id": 3,
  "activity_name": "Update",
  "type_uid": 600303,
  "severity_id": 1,
  "time": 1791374400000,
  "status_id": 1,
  "metadata": {
    "version": "1.9.0",
    "product": { "name": "CloudTrail", "vendor_name": "AWS" },
    "uid": "EXAMPLE-event-id-0001",
    "profiles": ["cloud"]
  },
  "cloud": {
    "provider": "AWS",
    "region": "us-east-1",
    "account": { "uid": "111122223333" }
  },
  "api": {
    "operation": "StopLogging",
    "service": { "name": "cloudtrail.amazonaws.com" },
    "request": { "uid": "EXAMPLE-request-id-0001" }
  },
  "actor": {
    "user": {
      "uid": "arn:aws:sts::111122223333:assumed-role/ExampleAdmin/session-1",
      "uid_alt": "AROAEXAMPLEEXAMPLE01:session-1",
      "type": "AssumedRole",
      "account": { "uid": "111122223333" },
      "programmatic_credentials": [{ "uid": "ASIAEXAMPLEEXAMPLE01" }]
    },
    "session": {
      "issuer": "arn:aws:iam::111122223333:role/ExampleAdmin",
      "is_mfa": false
    }
  },
  "src_endpoint": { "ip": "198.51.100.10" },
  "http_request": { "user_agent": "aws-cli/2.17.0" },
  "resources": [
    { "uid": "arn:aws:cloudtrail:us-east-1:111122223333:trail/example-trail" }
  ],
  "unmapped": { "readOnly": "false", "eventCategory": "Management" }
}

Source. Conceptual mapping. CloudTrail column follows the OCSF project's 1.1.0 example mapping and AWS field definitions; Azure and Google columns are editorial, built from Microsoft and Google schema references reviewed October 7, 2026. ^{[6][7][8][9][10][11]}

Method. Conceptual. No official OCSF mapping exists for the Azure Activity Log or Google Cloud Audit Logs in the OCSF examples repository; each cell names the documented source field that fits the OCSF 1.9.0 attribute definition. Google fields sit under protoPayload except timestamp, operation.id and the resource labels; callerIp sits in requestMetadata.

Accessible table and figure data

Figure 3 accessible table

OCSF attribute	CloudTrail	Azure Activity Log	Google Cloud Audit Logs
time	eventTime	eventTimestamp	timestamp
api.operation	eventName	operationName.value	methodName
api.service.name	eventSource	Resource provider name value	serviceName
actor.user	userIdentity.arn and type	caller and object ID claim	principalEmail or principalSubject
src_endpoint.ip	sourceIPAddress when an IP	clientIpAddress in httpRequest	callerIp when an IP
user_agent in http_request	userAgent	Not in the documented schema	Caller-supplied user agent, unauthenticated
resources	resources ARNs	resourceId	resourceName
status_id	errorCode or responseElements	status.value	status.code
cloud.account.uid	recipientAccountId	subscriptionId	Project ID in resource labels
correlation_uid in metadata	None, one record per call	operationId	operation.id

Figure 3 accessible table

OCSF attribute	CloudTrail	Azure Activity Log	Google Cloud Audit Logs
time	eventTime	eventTimestamp	timestamp
api.operation	eventName	operationName.value	methodName
api.service.name	eventSource	Resource provider name value	serviceName
actor.user	userIdentity.arn and type	caller and object ID claim	principalEmail or principalSubject
src_endpoint.ip	sourceIPAddress when an IP	clientIpAddress in httpRequest	callerIp when an IP
user_agent in http_request	userAgent	Not in the documented schema	Caller-supplied user agent, unauthenticated
resources	resources ARNs	resourceId	resourceName
status_id	errorCode or responseElements	status.value	status.code
cloud.account.uid	recipientAccountId	subscriptionId	Project ID in resource labels
correlation_uid in metadata	None, one record per call	operationId	operation.id

Download imageDownload table CSV

Where provider semantics diverge

Putting each field in the right attribute is the easy part. The table lists the differences that change detection results even when every field lands correctly.

Records per operation is the difference that breaks counting rules. An Azure write, delete or action produces a start record and then a success or failure record that share operationId. A Google long-running operation produces two entries linked by operation.id, flagged operation.first and operation.last; an operation that completes immediately or fails produces one entry with both flags set, and some services omit operation on failure. Map Started and in-progress states to status_id 99 with the provider text in status, never to Success, and deduplicate on metadata.correlation_uid before counting. ^[7][8]

Failure needs its own test per provider. CloudTrail documents that some services put error information inside responseElements rather than in errorCode, so a missing errorCode is a weak success signal for those services. Google's status is a google.rpc.Status; map any nonzero code to Failure and keep the number in status_code, where 7 means PERMISSION_DENIED and 16 means UNAUTHENTICATED. Keep the provider's error text in status_detail either way. ^[6][11][13]

Source addresses need a guard. For calls made by AWS services, CloudTrail records a DNS name, and for AWS-originated events usually AWS Internal/ followed by a number. Google records "private" for calls inside its production network, including service agents acting on a user's request, and "gce-internal-ip" for VMs without external addresses outside the resource's organization or project. None of these is an IP address, and the OCSF validator treats "private" in src_endpoint.ip as a warning, so the value would pass a schema check. Put only parseable addresses in ip, service DNS names in src_endpoint.domain, and labels such as "private" in unmapped. ^[6][12][17]

Identity is the hardest field to make comparable. An IAM role session ARN, an Entra object ID and a Google email are all valid actor.user values, but they identify different kinds of principal, and Google may redact principalEmail for read-only calls that fail with permission denied unless the caller is a service account. A rule that follows one person across providers needs an identity map maintained outside the log pipeline. OCSF supplies the slot, not the join. ^[10][12]

Class routing changes what a rule matches

Before any field is mapped, a pipeline decides which class a record becomes, and for identity changes that choice is not obvious. The OCSF project's example CloudTrail pipeline for 1.1.0 routes nine sign-in and role-assumption event names, including ConsoleLogin and AssumeRole, to Authentication; 64 IAM event names, including CreateUser, AttachRolePolicy and CreateAccessKey, to Account Change; and every other event to API Activity. ^[9]

Under that mapping AttachRolePolicy becomes Account Change with activity 7, Attach Policy, so type_uid is 300107. Account Change is deprecated in 1.9.0, and its replacements separate users from roles: User Management covers user lifecycle and account tasks, and Role Management covers a role's privileges, policies, credentials and resources. Read against those definitions, the same call in a 1.9.0 mapping belongs in Role Management with activity 8, Attach Policies, giving type_uid 300808. That placement is this guide's reading of the class descriptions, not a published mapping. The numbering moved as well: Delete is 6 in Account Change and 3 in both new classes. ^[1][5][9]

A rule keyed on type_uid = 300107 keeps validating and keeps running after a mapping upgrade; it simply stops matching. Rules on API Activity are less exposed but not immune, because the same router decides which IAM calls never reach API Activity at all. Write privileged-change rules with an explicit list of every class the mapping may use, and add a pipeline test that fails when a known event name lands in an unexpected class.

Activity IDs inside API Activity are coarser than they look. The example mapping derives activity_id from substrings of eventName checked in a fixed order: RunInstances becomes Create, StopLogging becomes Update, and because the Tag test runs before the Delete test, DeleteTags resolves to Update. Azure's write operations cover both creating and updating a resource, so a mapper must choose one or use Other. Use activity_id as a cheap prefilter at most; the security meaning lives in api.operation. ^[7][9]

Write detections against normalized data

Disabling audit export makes a good cross-provider test case: StopLogging or DeleteTrail in CloudTrail, deleting a diagnostic setting in Azure, and deleting or updating a log sink in Google Cloud. The normalized rule is shorter than three provider rules, but its operation lists stay provider-specific, because OCSF standardizes where the operation name lives, not what each provider calls it. ^[14][15][16]

The hypothetical query below filters on class, version, outcome and provider-qualified operations, and never on activity_id. Under the example verb heuristic StopLogging is an Update and DeleteTrail a Delete, so an activity filter would either miss one of them or match thousands of unrelated calls. The Azure comparison is case-insensitive because Microsoft's own operation reference prints both DiagnosticSettings/Delete and diagnosticSettings/Write. ^[9][15]

The rule still rests on mapping decisions it cannot see: that Azure start records carry status_id 99 rather than 1, that cloud.provider uses exactly one spelling per provider (the schema leaves it a free string and only gives AWS, Azure and GCP as examples), and that Google sink changes arrive through the Admin Activity log. Write those preconditions next to the rule so that a pipeline change triggers a rule review. ^[1][7]

-- Example detection fragment (Athena-style SQL). Hypothetical table of
-- OCSF 1.9.0 API Activity events from AWS, Azure and Google Cloud.
-- Preconditions: Azure Started events carry status_id 99, and
-- cloud.provider is normalized to exactly 'AWS', 'Azure' or 'GCP'.
SELECT time, cloud.provider, cloud.account.uid, api.operation,
       actor.user.uid, actor.user.email_addr, src_endpoint.ip
FROM ocsf_api_activity
WHERE class_uid = 6003
  AND metadata.version = '1.9.0'
  AND status_id = 1
  AND (
    (cloud.provider = 'AWS'
      AND api.service.name = 'cloudtrail.amazonaws.com'
      AND api.operation IN ('StopLogging', 'DeleteTrail'))
    OR (cloud.provider = 'Azure'
      AND lower(api.operation) = 'microsoft.insights/diagnosticsettings/delete')
    OR (cloud.provider = 'GCP'
      AND api.service.name = 'logging.googleapis.com'
      AND api.operation IN ('google.logging.v2.ConfigServiceV2.DeleteSink',
                            'google.logging.v2.ConfigServiceV2.UpdateSink'))
  )

Source. Conceptual comparison based on CloudTrail, Azure Activity Log and Google audit log documentation and the OCSF example mapping. ^[6][7][8][9]

Method. Conceptual. Describes the hypothetical rule shown in this section; it is not a measurement of detection performance.

Accessible table and figure data

Figure 4 accessible table

Aspect	Before	After
Tables queried	Three tables, three schemas	One API Activity table
Operation field	eventName, operationName.value, methodName	api.operation
Success test	No errorCode; Succeeded; status code	status_id equals 1
Actor field	userIdentity, caller, authenticationInfo	actor.user
Operation lists	Provider names per rule	Still provider names per rule
What can break it	Provider field changes	Mapping, routing or version changes

Figure 4 accessible table

Aspect	Before	After
Tables queried	Three tables, three schemas	One API Activity table
Operation field	eventName, operationName.value, methodName	api.operation
Success test	No errorCode; Succeeded; status code	status_id equals 1
Actor field	userIdentity, caller, authenticationInfo	actor.user
Operation lists	Provider names per rule	Still provider names per rule
What can break it	Provider field changes	Mapping, routing or version changes

Download imageDownload table CSV

Validate a mapping before promoting it

The OCSF schema server exposes POST /api/v2/validate and a bundle variant. They check required attributes, types, enum values and constraints for a schema version and report deprecated classes and attributes as warnings. A 1.1.0 Account Change event submitted to the 1.9.0 validator on October 7, 2026 returned no errors and two warnings, one for the deprecated class and one because the event's version was earlier than the schema's. For Security Lake custom sources, AWS points to its own OCSF validation tool. Schema validity is the floor, not the test. ^[4][17]

Semantic checks have to come from your own fixtures. A short list that catches the failures described above:

• Keep golden records per provider and transport: a raw event and its expected OCSF output for a success, a failure, a two-record operation, a service-originated call and a redacted caller.
• Fail the build on validator errors, and on class_deprecated or attribute_deprecated warnings for the target version.
• Compare volumes: raw records per hour against normalized records per class. A gap means routing dropped, split or duplicated data.
• Watch unmapped for fields that used to be mapped. CloudTrail adds fields in minor eventVersion increments, currently 1.11, and a renamed source field shows up first as unmapped data. ^[6]
• Run every detection's fixtures against a new mapping before it ships, and keep the previous mapping deployable until they pass.

Settling the pieces in sequence

Normalization pays off only when the pieces are settled in the right order, because each later step depends on decisions made earlier:

• Choose the target OCSF version for each destination and write it down. In Security Lake that means 1.1.0 for native AWS data and at most 1.3 for custom sources.
• Decide class routing for sign-ins and identity changes before mapping fields, and list the classes each privileged-change rule must cover.
• Map fields per provider and per transport, keep operation names verbatim in api.operation, and keep leftover provider fields in unmapped.
• Normalize outcomes and multi-record operations: start states to 99, failures from every documented error location, and a correlation ID for deduplication.
• Validate against the schema server, then against golden records, then run detection fixtures.
• Key rules on class, provider, operation and status. Use activity_id and type_uid only within one pinned version.