diff --git a/docs/spec/trace/events.md b/docs/spec/trace/events.md index 0894b20b..63187613 100644 --- a/docs/spec/trace/events.md +++ b/docs/spec/trace/events.md @@ -45,23 +45,23 @@ When Provenance is attached to a hook payload, the resulting span MUST carry `ac ## OCSF event classes -Each ACS step is representable as an OCSF event in the class shown below (OCSF 1.5+). Required class-specific attributes are populated from the ACS payload. +Each ACS step is representable as an OCSF event in the class shown below (OCSF 1.9.0). Required class-specific attributes are populated from the ACS payload. The full mapping lives in [`trace/ocsf-mapping.json`](https://genai-security-project.github.io/agent-control-standard/schema/v0.1.0/trace/ocsf-mapping.json). See [Extending OCSF](./extend_ocsf.md) for the deeper integration guide. | ACS step | OCSF class | Class UID | |---|---|---| | `steps/sessionStart` | Authentication | 3002 | -| `steps/agentTrigger`, `steps/userMessage`, `steps/agentResponse` | Application Activity | 6002 | +| `steps/agentTrigger`, `steps/userMessage`, `steps/agentResponse` | Application Lifecycle | 6002 | | `steps/toolCallRequest`, `steps/toolCallResult` | Process Activity | 1007 | | `steps/skillLoad`, `steps/skillUnload` | Module Activity | 1005 (`activity_id` 1 load, 2 unload) | | `steps/knowledgeRetrieval`, `steps/memoryStore`, `steps/memoryContextRetrieval` | Datastore Activity | 6005 | | `steps/preCompact`, `steps/postCompact` | Datastore Activity | 6005 (compaction subtype) | | `steps/subagentStart`, `steps/subagentStop` | Authentication | 3002 (logon/logoff for the subagent's session) | -| `steps/turnStart`, `steps/turnEnd` | Application Activity | 6002 | +| `steps/turnStart`, `steps/turnEnd` | Application Lifecycle | 6002 | | Decision (deny/modify/ask/defer) | Detection Finding | 2004 | -| `agbom/snapshot`, `agbom/changed` | Inventory Info | 5001 | -| `steps/skillRegister` | Device Inventory Info | 5001 (skill enters the component set) | +| `agbom/snapshot`, `agbom/changed` | Device Inventory Info | 5001 (`activity_id` 2, Collect) | +| `steps/skillRegister` | Device Inventory Info | 5001 (`activity_id` 2, Collect: skill enters the component set) | | `steps/sessionEnd` | Authentication | 3002 (logoff) | OCSF `severity_id` for decision events is set from the disposition: diff --git a/docs/spec/trace/extend_ocsf.md b/docs/spec/trace/extend_ocsf.md index 34464fc6..1086c186 100644 --- a/docs/spec/trace/extend_ocsf.md +++ b/docs/spec/trace/extend_ocsf.md @@ -2,20 +2,20 @@ The Open Cybersecurity Schema Framework (OCSF) integration enables standardized security-event logging for AI agent activity. ACS-shaped events drop directly into existing SIEM pipelines without bespoke parsers. -ACS events map to OCSF 1.5+ event classes. The normative class assignments and the disposition → `severity_id` mapping live on the [Trace Events](./events.md) page; the machine-readable mapping is at [`trace/ocsf-mapping.json`](https://genai-security-project.github.io/agent-control-standard/schema/v0.1.0/trace/ocsf-mapping.json). This page describes how to assemble the events themselves and provides representative wire examples. +ACS events map to OCSF 1.9.0 event classes. The normative class assignments and the disposition → `severity_id` mapping live on the [Trace Events](./events.md) page; the machine-readable mapping is at [`trace/ocsf-mapping.json`](https://genai-security-project.github.io/agent-control-standard/schema/v0.1.0/trace/ocsf-mapping.json). This page describes how to assemble the events themselves and provides representative wire examples. ## Class assignments at a glance | ACS step | OCSF class | Class UID | |---|---|---| | `steps/sessionStart`, `steps/sessionEnd`, `steps/subagentStart`, `steps/subagentStop` | Authentication | 3002 | -| `steps/agentTrigger`, `steps/userMessage`, `steps/agentResponse`, `steps/turnStart`, `steps/turnEnd` | Application Activity | 6002 | +| `steps/agentTrigger`, `steps/userMessage`, `steps/agentResponse`, `steps/turnStart`, `steps/turnEnd` | Application Lifecycle | 6002 | | `steps/toolCallRequest`, `steps/toolCallResult` | Process Activity | 1007 | | `steps/skillLoad`, `steps/skillUnload` | Module Activity | 1005 (`activity_id` 1 load, 2 unload) | | `steps/knowledgeRetrieval`, `steps/memoryStore`, `steps/memoryContextRetrieval`, `steps/preCompact`, `steps/postCompact` | Datastore Activity | 6005 | | Decision (deny/modify/ask/defer) | Detection Finding | 2004 | -| `agbom/snapshot`, `agbom/changed` | Inventory Info | 5001 | -| `steps/skillRegister` | Device Inventory Info | 5001 | +| `agbom/snapshot`, `agbom/changed` | Device Inventory Info | 5001 (`activity_id` 2, Collect) | +| `steps/skillRegister` | Device Inventory Info | 5001 (`activity_id` 2, Collect) | ## Severity mapping @@ -41,7 +41,7 @@ ACS events map to OCSF 1.5+ event classes. The normative class assignments and t "type_uid": 100701, "severity_id": 1, "metadata": { - "version": "1.5.0", + "version": "1.9.0", "product": { "name": "ACS Guardian", "vendor_name": "ACS" } }, "actor": { @@ -81,9 +81,10 @@ ACS events map to OCSF 1.5+ event classes. The normative class assignments and t "activity_id": 1, "activity_name": "Create", "time": 1706550000050, + "type_uid": 200401, "severity_id": 4, "status_id": 1, - "metadata": { "version": "1.5.0", "product": { "name": "ACS Guardian", "vendor_name": "ACS" } }, + "metadata": { "version": "1.9.0", "product": { "name": "ACS Guardian", "vendor_name": "ACS" } }, "finding_info": { "uid": "decision-001", "title": "Tool call denied: outside committed Intent", @@ -105,22 +106,24 @@ ACS events map to OCSF 1.5+ event classes. The normative class assignments and t } ``` -## Example: AgBOM snapshot as Inventory Info (5001) +## Example: AgBOM snapshot as Device Inventory Info (5001) ```json { "category_uid": 5, "category_name": "Discovery", "class_uid": 5001, - "class_name": "Inventory Info", - "activity_id": 1, - "activity_name": "Log", + "class_name": "Device Inventory Info", + "activity_id": 2, + "activity_name": "Collect", "time": 1706549900000, + "type_uid": 500102, "severity_id": 1, - "metadata": { "version": "1.5.0" }, + "metadata": { "version": "1.9.0", "product": { "name": "ACS Guardian", "vendor_name": "ACS" } }, "device": { "uid": "agent-123", "name": "CustomerServiceAgent", + "type_id": 99, "type": "AI Agent" }, "unmapped": { @@ -142,7 +145,7 @@ ACS events map to OCSF 1.5+ event classes. The normative class assignments and t ## Implementation notes - **`actor.user.type_id: 99`** is the OCSF "Other" sentinel; pair with `actor.user.type: "AI Agent"` so SIEM filters can distinguish agent identities from human ones. -- **`unmapped.acs`** carries ACS-specific facts that don't have direct OCSF equivalents in v1.5. The structure mirrors the request envelope's `payload` plus the decision envelope's `policy_data` / `reason_codes`. Backends that index `unmapped` keep this fully searchable. +- **`unmapped.acs`** carries ACS-specific facts that don't have direct OCSF equivalents in OCSF 1.9.0. The structure mirrors the request envelope's `payload` plus the decision envelope's `policy_data` / `reason_codes`. Backends that index `unmapped` keep this fully searchable. - **Provenance** flows onto OCSF events under `unmapped.acs.provenance`. Trust classification is omitted on the wire for v0.1; backends that compute trust apply it as an enrichment step. For more worked examples — including A2A and MCP wrapped events — see [Implementation examples](./OCSF/implementation_examples.md). diff --git a/specification/v0.1.0/trace/ocsf-mapping.json b/specification/v0.1.0/trace/ocsf-mapping.json index 47e3957e..675206d4 100644 --- a/specification/v0.1.0/trace/ocsf-mapping.json +++ b/specification/v0.1.0/trace/ocsf-mapping.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://genai-security-project.github.io/agent-control-standard/schema/v0.1.0/trace/ocsf-mapping.json", "title": "ACS Trace → OCSF event-class mapping", - "description": "Normative mapping from ACS hooks and decisions to OCSF (Open Cybersecurity Schema Framework) event classes. v0.1.0 conformance requires that a deployment emitting OCSF for the Trace pillar uses these class UIDs and severity rules verbatim. OCSF classes are referenced by their stable class_uid as of OCSF 1.5+.", + "description": "Normative mapping from ACS hooks and decisions to OCSF (Open Cybersecurity Schema Framework) event classes. v0.1.0 conformance requires that a deployment emitting OCSF for the Trace pillar uses these class UIDs and severity rules verbatim. Class UIDs, class names and activity IDs are those of OCSF 1.9.0.", "type": "object", "properties": { "step_to_class": { @@ -20,11 +20,11 @@ "default": { "steps/sessionStart": { "class_uid": 3002, "class_name": "Authentication", "activity_id": 1 }, "steps/sessionEnd": { "class_uid": 3002, "class_name": "Authentication", "activity_id": 2 }, - "steps/userMessage": { "class_uid": 6002, "class_name": "Application Activity" }, - "steps/agentResponse": { "class_uid": 6002, "class_name": "Application Activity" }, - "steps/agentTrigger": { "class_uid": 6002, "class_name": "Application Activity" }, - "steps/turnStart": { "class_uid": 6002, "class_name": "Application Activity" }, - "steps/turnEnd": { "class_uid": 6002, "class_name": "Application Activity" }, + "steps/userMessage": { "class_uid": 6002, "class_name": "Application Lifecycle" }, + "steps/agentResponse": { "class_uid": 6002, "class_name": "Application Lifecycle" }, + "steps/agentTrigger": { "class_uid": 6002, "class_name": "Application Lifecycle" }, + "steps/turnStart": { "class_uid": 6002, "class_name": "Application Lifecycle" }, + "steps/turnEnd": { "class_uid": 6002, "class_name": "Application Lifecycle" }, "steps/toolCallRequest": { "class_uid": 1007, "class_name": "Process Activity" }, "steps/toolCallResult": { "class_uid": 1007, "class_name": "Process Activity" }, "steps/knowledgeRetrieval": { "class_uid": 6005, "class_name": "Datastore Activity" }, @@ -34,11 +34,11 @@ "steps/postCompact": { "class_uid": 6005, "class_name": "Datastore Activity", "activity_id": 99 }, "steps/subagentStart": { "class_uid": 3002, "class_name": "Authentication", "activity_id": 1, "_note": "Subagent spawn opens a new session — modeled as Authentication/Logon for OCSF symmetry with sessionStart." }, "steps/subagentStop": { "class_uid": 3002, "class_name": "Authentication", "activity_id": 2 }, - "steps/skillRegister": { "class_uid": 5001, "class_name": "Device Inventory Info", "_note": "Registration admits a skill to the component set and persists its definition ref and digest to the AgBOM — modeled as Inventory Info, the class agbom/* already uses." }, + "steps/skillRegister": { "class_uid": 5001, "class_name": "Device Inventory Info", "activity_id": 2, "_note": "Registration admits a skill to the component set and persists its definition ref and digest to the AgBOM. It is modeled as Device Inventory Info, the class agbom/* uses, with activity_id 2 (Collect)." }, "steps/skillLoad": { "class_uid": 1005, "class_name": "Module Activity", "activity_id": 1, "_note": "OCSF defines Module Activity as a process loading or unloading a module, and its required module object is the skill itself — not Process Activity, which needs a launched or terminated process that a skill load does not have; keeping loads off 1007 lets a reader tell a skill loading from the tool calls its actions raise." }, "steps/skillUnload": { "class_uid": 1005, "class_name": "Module Activity", "activity_id": 2 }, - "agbom/snapshot": { "class_uid": 5001, "class_name": "Inventory Info" }, - "agbom/changed": { "class_uid": 5001, "class_name": "Inventory Info" } + "agbom/snapshot": { "class_uid": 5001, "class_name": "Device Inventory Info", "activity_id": 2 }, + "agbom/changed": { "class_uid": 5001, "class_name": "Device Inventory Info", "activity_id": 2 } } }, "decision_class": { @@ -50,7 +50,7 @@ "required_fields": { "type": "array", "items": { "type": "string" }, - "default": ["finding.title", "finding.uid", "evidences", "verdict_id"] + "default": ["finding_info", "finding_info.title", "evidences", "verdict_id"] } } },