Map ActionTrace to OCSF / OWASP Agent Observability Standard for SIEM export

[dgenio]

Summary

Provide a documented, tested mapping from ActionTrace (and the denial/expansion
records of ISSUE 7) to OCSF API Activity events as extended by the OWASP Agent
Observability Standard (AOS), plus a small exporter producing OCSF-shaped JSON.

Why this matters

Security teams consume agent activity through SIEMs, and OCSF is the cross-vendor
schema those pipelines speak. The planned OTel export (#125) serves the
observability pipeline; OCSF/AOS serves the security operations pipeline — a
different consumer with different tooling. For a kernel whose differentiator is the
tamper-evident audit trail, "your agent audit events land in your SIEM in a standard
shape" is a high-credibility enterprise adoption story that costs only a mapping
module.

Current evidence

• trace.py ActionTrace carries principal, capability, timestamps, outcome, error — the core fields OCSF API Activity (class 6003) expects.
• otel.py exists for spans (extra-gated), establishing the exporter pattern to follow; no OCSF/SIEM-shaped output exists.
• Open issue Export ActionTrace to OpenTelemetry / LangWatch-compatible trace format #125 covers OTel/LangWatch; this issue targets the OCSF/AOS schema family and references Export ActionTrace to OpenTelemetry / LangWatch-compatible trace format #125 as complementary.

External context

• OWASP AOS extends OCSF for agent traces (https://aos.owasp.org/spec/trace/extend_ocsf/).
• OCSF as SIEM lingua franca (https://blog.fleak.ai/blog/ocsf-an-introduction-to-the-open-cybersecurity-schema-framework).

Proposed implementation

1. export/ocsf.py (or extend a future exporters package): pure function
   trace_to_ocsf(trace) -> dict with explicit field mapping table; no new
   dependencies (plain dict construction).
2. Map: invoke success/failure → API Activity with agent extensions; denials
   (ISSUE 7) → denied activity; include stable reason codes as enrichment.
3. Validate output against the published AOS/OCSF JSON schema in tests (vendored
   schema fixture or schema-validation in a dev-only test).
4. Document a JSONL export recipe (pairs with [Feature] Pluggable persistence for TraceStore, HandleStore, and token revocation (SQLite + JSONL backends) #126/[Feature] Hash-chained, verifiable audit log with retention and export controls #127 persistence/export work).

AI-agent execution notes

• Inspect first: trace.py, otel.py (pattern), policy_reasons.py, AOS spec pages.
• Determinism: mapping is pure; timestamps formatted per OCSF expectations.
• Edge cases: traces with redacted args (ISSUE 6) — map sentinel cleanly; missing optional fields; long error strings.
• Keep it dependency-free; schema validation only in tests.

Acceptance criteria

• Every ActionTrace variant maps to schema-valid OCSF/AOS JSON (validated in tests).
• The field-mapping table is documented.
• Round-trip example included in docs and runnable.

Test plan

Schema-validation tests over representative traces; golden-file mapping tests.
Run make ci.

Documentation plan

New docs/integrations.md SIEM/OCSF section with the mapping table; CHANGELOG
Added; cross-reference #125/#127.

Migration and compatibility notes

Additive; not expected to require migration.

Risks and tradeoffs

AOS is young — version the mapping and isolate it in one module so spec movement is
contained. Low maintenance otherwise.

Suggested labels

ecosystem, security, integrations, reliability

[dgenio]

Closing as completed — this landed on main.

The OCSF / OWASP-AOS SIEM export shipped in the "audit-trail observability" work (commit 37391e1, merged via #233). src/weaver_kernel/ocsf.py now provides trace_to_ocsf() / traces_to_ocsf() mapping any ActionTrace (invoke/expand/deny) to OCSF API Activity (class 6003) events, AOS-enriched, as a pure dependency-free dict construction. A runnable recipe (examples/ocsf_export_demo.py) and the field-mapping table in docs/integrations.md accompany it. See the CHANGELOG [Unreleased] "OCSF / OWASP-AOS SIEM export (#176)" entry.

If the delivered mapping misses a field you need, please open a focused follow-up.

---

Generated by Claude Code