This is the second article in our series on the Open Cybersecurity Schema Framework (OCSF). In our previous article, we introduced OCSF and why it matters for security teams facing significant data translation challenges. This article examines the core components of OCSF: event classes, categories, and profiles. By the end of this piece, you'll understand exactly how to map your security logs to OCSF's structure.

———

Remember that authentication log translation problem we talked about? The one where "user_name" becomes "userid" becomes "account_identifier" depending on which tool you're looking at? Let's see how OCSF actually solves this.

OCSF's documentation can be intimidating at first. Event classes, category UIDs, object types—it feels overwhelming. After spending time mapping production logs to OCSF, the structure makes sense. The framework's structure is designed for organization, and understanding its logic makes it easier to navigate—everything has a place, and once you understand the system, finding what you need becomes straightforward.

OCSF's Hierarchical Structure

OCSF organizes security data using a hierarchy that will feel familiar to anyone who's ever organized a large dataset. At the top, you have eight primary categories. These are essentially the main sections of your security data warehouse:

1. System Activity - Everything happening on your endpoints

2. Findings - The bad stuff your tools discovered

3. Identity & Access Management - Who's logging in, who's getting blocked

4. Network Activity - Packets flying across your network

5. Discovery - What assets exist in your environment

6. Application Activity - What your apps are up to

7. Audit Activity - Administrative and compliance events

8. Unmanned Systems - Drone and aviation security data (added in 1.4.0)

Each category contains multiple event classes where the detailed mapping occurs. An event class is essentially a template that says, "If you're going to log this type of activity, here's exactly what fields you need and what to call them."

Take authentication events as an example. In OCSF, these live in event class 3002 (Authentication) within the Identity & Access Management category. Every authentication event—whether from Active Directory, Okta, or AWS IAM—uses the same field names: user.name for the account, activity_id to indicate logon (1) or logout (2), auth_protocol for the method. No more translation tables or wondering if "failed_login" equals "authentication_failure" equals "ACCESS_DENIED."

How Events Actually Get Classified

This firewall log mapping example shows how it works. A typical firewall log entry might look something like this (simplified for clarity):

src_ip=192.168.1.100,dst_ip=10.0.0.50,dst_port=443,action=allow,proto=tcp

In OCSF, this becomes a Network Activity event (class_uid: 4001) with standardized fields:

• time: 1736939025000 (Unix timestamp)

• src_endpoint.ip: "192.168.1.100"

• dst_endpoint.ip: "10.0.0.50"

• dst_endpoint.port: 443

• action: "Allowed"

• connection.protocol: "TCP"

The key point is: the exact same structure works for AWS Security Group logs, Azure NSG logs, and any other firewall you can name. This enables portable detection rules that can be applied across different data sources.

But OCSF goes deeper than simple field mapping. Each event class includes an activity_id that captures what actually happened. A Network Activity event (4001) isn't just "something happened on the network." Activity_id 1 means connection opened, 2 means connection closed, 3 means connection reset. For DNS Activity (4003), activity_id 1 is a query, 2 is a response. This granularity means you can write precise detection logic without memorizing vendor-specific status codes.

The framework also mandates certain fields for every event. No matter what type of security event you're dealing with, it must include certain fields such as:

• category_uid and class_uid (what type of event)

• activity_id (what happened)

• time (when it happened)

• severity_id (how bad is it)

These required fields ensure you can always perform basic analysis, even on event types you've never seen before.

Profiles: Using Profiles to Handle Complex, Real-World Data

The OCSF designers made a practical choice with profiles. They recognized that a one-size-fits-all schema wasn't going to work; it would either be too simple for real-world needs or too complicated for anyone to actually implement. Using profiles was their way of solving that problem.

Profiles act as overlays, allowing you to add specific context to your data without altering the base schema. For instance, if you use AWS, the Cloud Profile brings in fields for things like account IDs, regions, and VPCs. And if you work with containers, the Container Profile adds details like image names and container IDs.

An important feature of profiles is that they are composable, meaning you can apply several to a single event. For example, an event for a process running in a container on AWS can be enriched with fields from both the Cloud and Container profiles. This design is inherently backward-compatible: tools that recognize the profiles can use the extra context, while those that don't will simply ignore the additional fields without issue.

Mapping Your Logs: A Practical Walkthrough

Every log entry records an event with semantic meaning—a user logged in, a file was deleted, a connection was blocked. The initial goal of mapping is not just to match field names, but to understand the event the log is describing. This understanding helps you find the correct OCSF event class.

Let's work through a common, real-world example. Consider this log entry:

2025-01-15T14:23:45.123Z auth-server: Authentication failure for user john.doe@company.com from IP 203.0.113.45, invalid password, MFA not attempted

1. Identify the Semantic Event and Find the Class The log describes a failed login attempt. You can then browse the OCSF categories to find the best fit. This event clearly belongs to the Identity & Access Management category and, more specifically, the Authentication (3002) event class.

2. Fulfill All Required Fields Next is the systematic part: mapping the data. It is critical to start with OCSF's required fields. The schema browser at schema.ocsf.io is the definitive source. The base event class alone has 8-10 required fields, including activity_id, category_uid, class_uid, metadata, severity_id, status_id, time, and type_uid. Furthermore, specific event classes like Authentication (3002) have their own additional required attributes, such as the user object. Some of these, like metadata, are complex objects with their own required subfields.

3. Map the Source Data and Confront Ambiguity With requirements identified, you can map the information from the source log:

• "john.doe@company.com" → user.email_addr and user.name

• "203.0.113.45" → src_endpoint.ip

• "invalid password" → status_detail

• "failure" → status_id: 2 (Failure)

• "MFA not attempted" → This is where a practical challenge arises. There is no standard OCSF field for this specific detail.

4. Make and Document Mapping Decisions This MFA information is useful for security analysis, so it cannot be discarded. This leads to a judgment call, a common occurrence in mapping projects. You have several options:

• Use the unmapped object: Place the raw string "MFA not attempted" in the unmapped field. This is a safe choice that preserves the data, but it can be difficult for analysts to query consistently.

• Append to an existing field: You could add it to the status_detail field alongside "invalid password", but this complicates automated parsing.

• Create an extension: If tracking MFA status is a critical, long-term requirement for your organization, the most robust solution is to create an organization extension with a dedicated mfa_status attribute.

Finally, document your decisions so everyone—data engineers, analysts, and detection engineers—knows how the data is mapped, preventing confusion. When you encounter information that does not have a clear destination, resist the urge to force it into an inappropriate field. It is better to use unmapped or evaluate if the detail is truly necessary for detection and analysis rather than compromise the schema's integrity.

When Standards Aren't Enough: Extending OCSF

OCSF's extension mechanism lets you expand the schema without breaking compatibility. Extensions aren't just a way to add custom fields—they're a formal framework that keeps everything compatible while meeting your specific needs.

An extension can add three types of content to OCSF:

• New attributes to existing event classes or objects

• New objects that group related attributes

• New event classes for activities not covered by the core schema

Each extension requires registration to receive a unique identifier range. This prevents situations where two organizations create conflicting extensions that break each other's implementations. When you register an extension, you get reserved ranges for class_uid values that guarantee your custom event classes won't collide with anyone else's.

The architecture supports different extension types. Platform extensions, like those for Linux or Windows, are considered part of the standardized schema. These add OS-specific attributes that many organizations need. Vendor extensions let security product companies add their proprietary fields without breaking core compatibility. Organization extensions—what most of us create—add company-specific requirements.

Common uses for extensions in production environments include:

• Compliance metadata: Framework-specific fields for SOC2 and PCI requirements

• Business context: Department codes, cost centers, and data classification levels

• Custom risk scoring: ML-generated risk scores that don't fit standard severity fields

• Integration metadata: Tracking which pipeline or system processed each event

Extensions prove useful when the OCSF schema evolves. When OCSF releases a new version, extensions remain compatible. If OCSF later adds a feature that was previously handled by an extension, organizations can migrate from the extension to the core field while keeping data valid.

For example, an organization might need to track whether events came from production or development environments—critical for compliance but not in core OCSF. They could create an extension with an environment_type attribute. When multiple organizations express the same need to the OCSF community, such extensions often inspire additions to the core schema.

The key to successful extensions is restraint. Before creating an extension, check if:

• The data truly doesn't fit existing structures

• Multiple systems need to understand this data

• The information is essential for security operations

If you're adding fields just one tool uses, or data that's nice-to-have but not essential, reconsider. Every extension adds complexity. Extend only where necessary while keeping the schema as clean as possible.

The Operational Impact of OCSF's Structure

OCSF implementation changes how teams work with security data. Detection engineers can write a single rule for suspicious PowerShell commands that applies to any EDR tool mapping to the same event class. Data engineers build one parsing pipeline per event class rather than maintaining vendor-specific parsers. During incident investigations, analysts query across systems using the same field names, reducing the time needed to correlate events from different sources.

The learning curve for OCSF requires dedicated time. Teams typically need several days to understand the schema structure before attempting large-scale implementations. The schema browser at schema.ocsf.io is your main reference, and the OCSF Slack community is where you can ask implementation questions.

Start with your highest-volume log sources—typically authentication, network, and endpoint events. These provide a foundation for understanding OCSF's structure in practice. Then expand to other log types based on your security priorities.

Looking Forward

Understanding OCSF's categories, event classes, and profiles is the first step in leveraging the framework. The framework continues evolving based on real-world usage. Recent additions include better IoT device modeling, enhanced cloud service mappings, and new categories like Unmanned Systems. This fundamental knowledge allows teams to more effectively adopt new enhancements to the framework as it evolves.

Have questions about OCSF event classes or mapping strategies? find us in the OCSF Slack community. Your experiences and questions help improve these articles.