<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-ocsf-normalization
description: >-
  Implement OCSF (Open Cybersecurity Schema Framework) normalization for security
  events including category mapping, class assignment, field transformation, and
  schema validation against the OCSF 1.1 specification.
domain: cybersecurity
subdomain: security-data-engineering
tags:
  - ocsf
  - normalization
  - schema
  - taxonomy
  - vendor-neutral
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  frameworks: ["OCSF 1.1"]
  tools: ["python3", "ocsf-validator", "jq"]
  mitre-attack: []
---

# Implementing OCSF Normalization

## Overview

OCSF provides a vendor-neutral taxonomy for security events organized into
categories (System, Network, Identity, etc.) and classes (Process Activity,
Network Activity, Authentication, etc.). This skill covers mapping vendor
events to OCSF categories, assigning class and activity UIDs, transforming
fields to OCSF objects, and validating output against the schema.

## Prerequisites

| Requirement | Details |
|---|---|
| OCSF 1.1 schema reference (schema.ocsf.io) | Required |
| Sample vendor events for mapping development | Required |
| Python 3.10+ for transformation logic | Required |
| Understanding of OCSF category/class/activity hierarchy | Required |

## Key Concepts

- **Category UID**: Top-level grouping (1=System, 3=Identity, 4=Network)
- **Class UID**: Event class within category (3001=Authentication, 4001=Network Activity)
- **Activity ID**: Specific action (1=Logon, 2=Logoff for Authentication class)
- **OCSF objects**: Reusable structures (endpoint, user, process, file)
- **Observables**: Extracted indicators for correlation

## Workflow

### Step 1: Map Vendor to OCSF Category

```python
OCSF_CATEGORY_MAP = {
    "authentication": {"category_uid": 3, "class_uid": 3001, "category_name": "Identity Activity"},
    "process_creation": {"category_uid": 1, "class_uid": 1001, "category_name": "System Activity"},
    "network_connection": {"category_uid": 4, "class_uid": 4001, "category_name": "Network Activity"},
    "dns_query": {"category_uid": 4, "class_uid": 4003, "category_name": "Network Activity"},
    "file_activity": {"category_uid": 1, "class_uid": 1004, "category_name": "System Activity"},
}
```

### Step 2: Transform to OCSF Objects

```python
def to_ocsf_endpoint(vendor_event: dict) -> dict:
    """Transform vendor fields to OCSF Endpoint object."""
    return {
        "ip": vendor_event.get("src_ip") or vendor_event.get("SourceAddress"),
        "hostname": vendor_event.get("hostname") or vendor_event.get("ComputerName"),
        "os": {
            "name": vendor_event.get("os_name", ""),
            "type_id": _os_type_id(vendor_event.get("os_name", "")),
        },
        "type_id": 1,  # Server=1, Desktop=2, Laptop=3, Mobile=4
    }

def to_ocsf_event(vendor_event: dict, event_type: str) -> dict:
    """Build full OCSF event from vendor data."""
    mapping = OCSF_CATEGORY_MAP.get(event_type, {})
    return {
        "category_uid": mapping.get("category_uid", 0),
        "class_uid": mapping.get("class_uid", 0),
        "activity_id": _resolve_activity(vendor_event, event_type),
        "severity_id": _map_severity(vendor_event.get("severity", "info")),
        "time_dt": vendor_event.get("timestamp"),
        "src_endpoint": to_ocsf_endpoint(vendor_event),
        "metadata": {
            "version": "1.1.0",
            "product": {"vendor_name": "custom", "name": "normalizer"},
        },
    }
```

### Step 3: Validate Against Schema

```bash
node agent.js normalize --input vendor_events.jsonl --type authentication --output ocsf_events.jsonl
node agent.js validate --input ocsf_events.jsonl --schema-version 1.1
```

## References

- [OCSF Schema 1.1](https://schema.ocsf.io/)
- [OCSF GitHub](https://github.com/ocsf)
- [OCSF Mapping Guide](https://schema.ocsf.io/docs/)
