Telemetry Schema

Purpose

This specification defines the telemetry schema: event types, PII classification per field, redaction rules, retention defaults, and export pathways.

Audience: Backend/security engineers, SIEM integrators.

---

In-Scope / Out-of-Scope

In-Scope	Out-of-Scope
Telemetry event types and their schemas	Detection logic
Field-level PII classification	Policy evaluation
Redaction and hashing rules	Cloud infrastructure security
Export pathways (API, webhooks)	Dashboard UI

---

Telemetry Event Types

1. Detection Events

Emitted by the Policy Engine for every detection decision.

{
  "event_id": "evt_7f2a9c",
  "type": "risk.event.created",
  "timestamp": "2026-03-14T14:32:08Z",
  "tenant_id": "tenant-acme",
  "device_id": "dev_3c8a1f",
  "threat_category": "phishing",
  "confidence": 0.94,
  "action_taken": "block",
  "policy_id": "pol_default",
  "severity": "high",
  "description": "Gefälschte Login-Seite erkannt und blockiert.",
  "indicators": ["sha256:a1b2c3d4e5f6..."],
  "metadata": {
    "agent_version": "0.1.0",
    "model_version": "detect-v3.2",
    "device_platform": "android"
  }
}

Current workspace note: the running prototype uses top-level type and top-level tenant_id for detection events. The broader event taxonomy described below remains a target-state specification.

2. User Action Events

Emitted when a user takes a security-relevant action.

{
  "event_id": "evt_8a3b2c",
  "event_type": "user_action",
  "timestamp": "2026-03-14T14:33:00Z",
  "device_id": "dev_3c8a1f",
  "action": "dismiss_warning",
  "related_event_id": "evt_7f2a9c",
  "metadata": {
    "agent_version": "0.1.0",
    "device_platform": "android",
    "tenant_id": "org_5e9d2a"
  }
}

User action types:

Action	Description
dismiss_warning	User dismissed a warn-level alert
unblock_url	User overrode a URL block
ignore_threat	User dismissed a threat notification
manual_scan	User initiated a manual scan
approve_app	Guardian approved an app installation
deny_app	Guardian denied an app installation

3. Policy Change Events (Audit)

Emitted when configuration is modified.

{
  "event_id": "evt_9c4d3e",
  "event_type": "policy_change",
  "timestamp": "2026-03-14T15:00:00Z",
  "actor": "user:admin@example.com",
  "action": "update_policy",
  "target": "pol_family_child",
  "old_state": { "action": "warn", "confidence_threshold": 0.5 },
  "new_state": { "action": "block", "confidence_threshold": 0.3 },
  "metadata": {
    "tenant_id": "org_5e9d2a"
  }
}

Audit action types:

Action	Description
update_policy	Policy modified
create_policy	New policy created
delete_policy	Policy removed
rotate_api_key	API key rotated
revoke_api_key	API key revoked
add_team_member	Team member added
remove_team_member	Team member removed
change_role	User role changed
register_device	New device registered
update_alert_rule	Alert rule modified

---

Field-Level PII Classification

Detection Event Fields

Field	PII?	Category	External Delivery
event_id	No	Operational	Transmitted
timestamp	No	Operational	Transmitted
device_id	Pseudonymous	Device identifier	Transmitted (opaque ID)
threat_category	No	Operational	Transmitted
confidence	No	Operational	Transmitted
action_taken	No	Operational	Transmitted
policy_id	No	Operational	Transmitted
severity	No	Operational	Transmitted
description	Potentially	May contain redacted context	Transmitted (redacted)
indicators	No	SHA-256 hashes only	Transmitted
metadata.agent_version	No	Operational	Transmitted
metadata.model_version	No	Operational	Transmitted
metadata.device_platform	No	Operational	Transmitted
tenant_id	Pseudonymous	Organization identifier	Transmitted (opaque ID)

Data NOT in Telemetry (Never Transmitted)

Data Type	Reason
Message content (email, chat)	Privacy: never leaves device
Audio content	Privacy: processed in RAM only
Phone numbers (plaintext)	Privacy: only SHA-256 hashes
URLs (full)	Privacy: only SHA-256 hashes
IP addresses (full)	Privacy: truncated to /24 or /48
File contents	Privacy: never leaves device
Contact information	Privacy: not accessed by agent

---

Redaction Rules

Applied before any data leaves the device for cloud transmission or external delivery.

Data Type	Redaction Method	Example
PII (email)	Replaced with [REDACTED]	admin@example.com → [REDACTED]
PII (name)	Replaced with [REDACTED]	Max Mustermann → [REDACTED]
PII (phone number)	SHA-256 hash	+49 30 123456 → sha256:a1b2c3...
URLs	SHA-256 hash	https://evil.com/login → sha256:d4e5f6...
IP addresses (IPv4)	Truncated to /24	192.168.1.42 → 192.168.1.0/24
IP addresses (IPv6)	Truncated to /48	Full → /48 prefix
Message content	Not included	Never present in telemetry

Scope: Cloud transmission and external delivery only. Local Event Store (AES-256 encrypted) retains full unredacted data.

---

Retention

Event Type	Local Retention	Cloud Retention	Status
Detection events	Target: 90 days	Target: 180 days	Not confirmed by current workspace
User action events	Target: 90 days	Target: 180 days	Not confirmed by current workspace
Policy change events (audit)	Target: 90 days	Target: 12 months	Not confirmed by current workspace
Aggregated metrics	N/A	Target: 24 months (then anonymized)	Not confirmed by current workspace

Deletion: Irreversible. Early deletion requestable via dashboard or API.

---

Export Pathways

Push: Webhooks

• Endpoint: Configurable HTTPS URL
• Format: JSON (canonical event schema)
• Signing: HMAC-SHA256 (X-Superheld-Signature)
• Delivery: At-least-once with exponential backoff
• Filtering: By severity, threat category

Pull: REST API

• Endpoint: GET /events
• Pagination: Cursor-based (cursor + limit)
• Filtering: since (ISO 8601), severity, threat_category
• Format: JSON array with has_more and cursor

SIEM Mapping

Superheld Field	Common SIEM Field	CEF Field
event_id	Event ID	externalId
timestamp	Event Time	rt
device_id	Source Host	shost
threat_category	Category	cat
severity	Severity	severity
action_taken	Action	act
confidence	Confidence	cfp1

Documented export target: CEF mapping as shown below. The current workspace does not yet expose a dedicated CEF/syslog delivery path.

CEF:0|Superheld|CloudRelay|1.0|detection|Threat Detected|8|externalId=evt_7f2a9c rt=2026-03-14T14:32:08Z shost=dev_3c8a1f cat=phishing severity=high act=block cfp1=0.94

Syslog (RFC 5424) example:

<134>1 2026-03-14T14:32:08Z superheld-cloud - evt_7f2a9c - - CEF:0|Superheld|CloudRelay|1.0|detection|Threat Detected|8|cat=phishing act=block cfp1=0.94

---

Related Specifications

• Event Pipeline — Event lifecycle and immutability
• Privacy Model — Data inventory and retention
• SIEM Integration — Public SIEM integration guide
• Webhooks — Public webhook guide