Issue 01 — Foundations, Threat Model & OCSF

This issue sets the threat model, five-layer architecture, and OCSF-mapped TelemetryEvent wire contract used for every later module. No host agent runs here. Issue 02 introduces the first executable binary.

Scope and terms

Antivirus evaluates files against signatures and heuristics at write or execution time.

EDR (Endpoint Detection and Response) evaluates sequences of behavior: process trees, command lines, file and network activity, plus response actions such as process kill, host isolation, and file quarantine. Living-off-the-land activity (certutil, PowerShell, rundll32) often never drops a distinct malware file, so file-only detection is incomplete. Phases A and B of this course build the OS telemetry EDR requires.

SIEM aggregates logs from multiple point products (firewalls, EDR, identity providers) into a shared query surface.

XDR extends detection and correlation beyond endpoints to network, identity, and container sources so related alerts form one incident. Module 9 implements that layer. Earlier modules produce the telemetry it joins.

MITRE ATT&CK is a public catalog of adversary techniques (for example T1105, Ingress Tool Transfer). From Module 7 onward, detection rules are tagged with the technique they target so Module 14 can report coverage against exercised techniques rather than untested rule tags alone.

The EDR agent itself is part of the threat model. It typically runs with elevated privileges and is a high-value target for disablement or tampering. Tamper resistance is deferred to Module 13; the design implication starts now: assume an attacker who knows the agent is present.

Telemetry, detection, and response

Keep these layers separate while building:

LayerResponsibilityPrimary failure modeTelemetryCollect host and cloud eventsSilence: missing fields make activity invisible downstreamDetectionScore telemetry and raise alertsNoise or blindness: excessive false positives, or missed true positivesResponseChange host state (kill, isolate, quarantine)Unsafe control: a remote action path without sufficient authorization and audit

A missing telemetry field often looks like a detection bug. Confirm collection before tuning rules.

System architecture

The platform data plane has five layers: agents, ingestion, storage, detection and correlation, and dashboard / copilot. Response commands return to agents on a separate control-plane path. Do not model response as only a dashboard button.

Events move down the data plane; response commands return to agents on a separate path.

The same spine applies to a Linux host, a Kubernetes node, or identity-provider audit logs. Modules 1–6.5 align each source to one vocabulary before deeper detection work.

OCSF as the storage and query model

Custom JSON field names (for example parentProcId) are inexpensive in early modules and costly later. Public Sigma rules still use classic fields such as Image and CommandLine. OCSF does not eliminate conversion; it provides one storage vocabulary for Sigma pipelines, correlation joins, and later investigation tools.

This course normalizes to the Open Cybersecurity Schema Framework (Linux Foundation project since November 2024). Confirm the current release at schema.ocsf.io. This issue was verified against 1.8.0 (March 2026). AWS Security Lake is a clear OCSF-native lake example. Elastic’s primary gravity remains ECS. Vendor agent wire formats are not uniformly OCSF. The project adopts OCSF as the greenfield storage and query model.

Protobuf is the wire format. OCSF is the data model. Classification fields (class_uid, category_uid, activity_id, type_uid, severity_id) belong on the Base Event. The metadata object carries product identity and the OCSF schema version string.

Selected wire fields map to OCSF process_activity paths, including type_uid, process.uid, and actor.process.

Maintain docs/ocsf-mapping.md as the source of truth. Update that document before extending proto/telemetry.proto when new event classes are added.

Wire contract decisions

Place classification fields at the top level of TelemetryEvent so conversion and query code share one convention.

Model Actor with both process and user. For process Launch, the actor process is typically the parent. A user-only actor object does not match OCSF process activity semantics.

Include process.uid as durable process identity. Operating systems reuse PIDs; lineage and process-tree views require a stable id. Agents populate process.uid beginning in Issue 02.

Start oneof activity at field number 10 so later file and network arms can be added without renumbering. Assigned field numbers are part of the wire contract.

Compute type_uid as class_uid * 100 + activity_id (process Launch → 100701). Downstream tables and rules key on this value.

Store file hashes as a single sha256 string until Module 6 (TIER 2). Leaving process.uid empty while claiming OCSF alignment produces incorrect lineage later; populate the field when agents ship.

Deliverable

Produce the repository scaffold, proto/telemetry.proto mapped to OCSF process_activity, docs/ocsf-mapping.md, and the architecture and mapping diagrams. No host agent executes in this issue.

Completion criteria:

1. protoc --proto_path=proto --python_out=/tmp proto/telemetry.proto completes without errors.

2. You can locate top-level type_uid, severity_id, and Actor.process in the proto without referring to this article.

3. You can redraw the five-layer architecture and state the primary failure mode of each layer.

Labs

1. Install Sysmon on a Windows VM and osquery on any OS. Generate ordinary activity (browser, terminal). Inspect raw event schemas. Do not write project code yet.

2. Open the process_activity class on schema.ocsf.io. Compare fields to Sysmon and osquery output. Note gaps in both directions; do not resolve them yet.

3. Redraw the architecture diagram from memory. Write one sentence per layer describing its role. If any layer is unclear, reread the architecture section before starting Issue 02.

Implementation guide: Foundations, Threat Model & OCSF

Github Link:

https://github.com/sysdr/production-xdr-edr/tree/main/v01-foundations-ocsf

Keep this guide open while building. Design rationale is in the issue article; this document is the step sequence only.

Prerequisites

• git

• protoc (protobuf compiler), v3.21+ recommended

  • macOS: brew install protobuf

  • Linux: apt install -y protobuf-compiler (or distro equivalent)

  • Windows: install from protobuf releases and add to PATH

• A text editor

• No OS-native agent tooling in this issue (starts Issue 02)

Verify:

protoc --version
# libprotoc 3.21.0 or higher

Step 1 — Scaffold the repository

mkdir edr-xdr-from-scratch && cd edr-xdr-from-scratch
git init

mkdir -p agent-windows agent-macos agent-linux agent-k8s \
         backend dashboard detections copilot proto \
         docs/issue-notes docs/implementation-guides docs/diagrams

Verify: tree -L 2 (or ls -R) shows the nine top-level module directories plus docs/ and proto/.

Step 2 — Add the protobuf schema

Create proto/telemetry.proto with TelemetryEvent and related messages. Read every OCSF mapping comment while writing. Field comments are the contract later modules assume.

Requirements:

1. Classification fields are top-level on TelemetryEvent: class_uid (1007), category_uid (1), activity_id, type_uid (class_uid * 100 + activity_id), severity_id. Do not place these only inside metadata.

2. Metadata holds product identity and OCSF schema version (ocsf_version → metadata.version).

3. Actor includes user and process. For Launch, actor process is typically the parent.

4. ProcessActivity.uid provides durable process identity. PID alone is insufficient for lineage.

5. oneof activity currently contains only process_activity at field 10. Later modules add arms without renumbering existing fields.

Verify:

protoc --proto_path=proto --python_out=/tmp proto/telemetry.proto

--python_out is a syntax check only. Module 1 onward uses Rust. No compiler output means success.

Step 3 — Write the OCSF mapping document

Create docs/ocsf-mapping.md before treating the proto as finished. Later modules that add event types edit this file first, then the proto.

Include at minimum:

• Rationale for OCSF (Sigma conversion target, lake/interchange where OCSF is used, shared tool vocabulary)

• Top-level classification and type_uid / severity_id / proper metadata

• Full field mapping table including process.uid and actor.process

• Explicit list of deliberate non-exact mappings (for example flattened sha256)

• Short detection field contract preview for Module 7

Sandbox / CI / Reader VM

StepSandbox / CIReader machineRepo scaffold + markdownFullFullprotoc compileNeeds protobuf in the environmentRequired — Step 2SVG render checkOptional XML well-formednessOpen in browserLive OS agentsN/A this issueStarts Issue 02

Step 4— README and changelog

Write top-level README.md covering repository layout, navigation of docs/issue-notes/, and the honesty label (demoable vertical slice).

Start CHANGELOG.md with one section per issue tag:

## v01-foundations-ocsf
- Repo scaffold
- TelemetryEvent protobuf schema, mapped to OCSF process_activity (class_uid 1007)
- System architecture + OCSF mapping diagrams

Step 6 — Verify the deliverable

Curriculum deliverable: architecture diagram + README + protobuf schema stub with an explicit field-to-OCSF mapping table.

Checklist:

• proto/telemetry.proto compiles with protoc

• Top-level type_uid, severity_id, class_uid, category_uid, activity_id exist on TelemetryEvent

• Metadata carries product + OCSF version; Actor has user + process

• ProcessActivity.uid and ProcessRef.uid exist

• Mapped fields have OCSF attribute comments

• docs/ocsf-mapping.md is complete and uses Sigma-as-conversion wording

• README.md explains repository structure

• You can state the role and primary failure mode of each architecture layer

Common errors

protoc: command not found — install the compiler and restart the shell so PATH updates apply (especially on Windows).

Unexpected field numbers after edits — protobuf field numbers are part of the wire format. Do not renumber existing fields; later issues assume stability.

Nothing runs yet — expected. Issue 01 is architecture and schema only. The first runnable binary is linux-agent in Issue 02.

Next issue

Tag this checkpoint before Issue 02:

git add -A
git commit -m "Issue 01: foundations, threat model, OCSF schema"
git tag v01-foundations-ocsf

Validation note

proto/telemetry.proto should be checked for brace balance and field uniqueness. Full protoc compilation requires a local protobuf install. If compilation fails on a correct install, treat it as a bug report against this issue package.