Chapter 9 — Forensics, SIEM & Security Telemetry

Tamper-Evident Audit Logs, SIEM & Analytics

Every administrative configuration change, role assignment, signing key rotation, and authentication event in SSO.ID v2 is recorded in a cryptographically verifiable SHA-256 Hash-Chained Audit Ledger ( /audit-logs, /user-activity, and /overview) with one-click export to Splunk HEC, Datadog, AWS CloudWatch, and Generic JSON SIEMs.

The SOC 2 Audit Story 1. Tamper-Evident Hash Chain 2. Before / After JSON Diffs 3. SIEM Export & Webhooks 4. User Activity & Analytics 5. Audit & Analytics APIs & AI Prompt

Compliance Story: Proving Zero Log Tampering to External SOC 2 & ISO 27001 Auditors

How CloudPulse Answered "How Do We Know a Rogue Admin Didn't Edit the Database Logs?"

During CloudPulse's SOC 2 Type II examination, the lead auditor asked two tough forensic questions:

"Show me the exact JSON field that changed when your Application's token lifetime was modified on October 14th, and who approved it."
"Prove mathematically that no database administrator altered or deleted any rows from your audit table before our audit."

CloudPulse's security lead opened /audit-logs, clicked Verify Chain Integrity (GET /api/audit-logs/verify-integrity) — which cryptographically validated the SHA-256 hash links across all stored records — and opened the October 14th event to display the side-by-side Before vs. After JSON State Diff. The auditor signed off on the control in 3 minutes.

1. Cryptographic Tamper-Evident Audit Hash Chain

In /audit-logs, every audit record is linked to its predecessor using an immutable SHA-256 cryptographic digest (previousHash + eventPayload → currentHash):

1-Click Integrity Verification (`GET /api/audit-logs/verify-integrity`)

Clicking Verify Chain Integrity in the Audit Logs toolbar recomputes the SHA-256 hash chain across your tenant's audit ledger and confirms whether 100% of records are intact or highlights the exact block index if tampering ever occurred.

Multi-Dimensional Forensic Filtering

Filter millions of events in milliseconds by Entity Type (GET /api/audit-logs/entities — Application, Connection, User, Role, Organization, TenantSettings, SigningKey), Action Type (GET /api/audit-logs/actions — Create, Update, Delete, Rotate, Login), Actor, IP Address, Status (Success / Failure), and Date Range.

Flow Diagram Cryptographic SHA-256 Audit Trail & SIEM Streaming Flow

flowchart LR EV["Admin Action or Auth Event"] --> DIFF["Generate JSON Before / After Diff"] DIFF --> HASH["Compute SHA-256 (PrevHash + Timestamp + Payload)"] HASH --> DB["Append to Immutable Audit Ledger (/audit-logs)"] DB --> VER["1-Click Verification (GET /verify-integrity)"] DB --> WH["Stream via Webhook / SIEM Exporter (Splunk / Datadog)"]

Every administrative change and login event computes a SHA-256 hash chaining to the previous block, verified via /verify-integrity and streamed to external SIEMs.

Tamper-Evident Audit Logs console at /audit-logs with SHA-256 chain integrity verification and SIEM export.

User Activity & Authentication Telemetry log at /user-activity.

2. Side-by-Side Before & After JSON State Diffs

Clicking any row in /audit-logs (GET /api/audit-logs/{id}) opens the Forensic Event Inspector displaying:

Actor & Request Context: Actor User ID & Email, Tenant ID, Correlation ID, Source IP Address, User-Agent, and UTC Timestamp.
Old Values vs. New Values Diff: Side-by-side JSON comparison highlighting every added, modified, or removed configuration property (with sensitive secrets automatically redacted).

3. SIEM Export (`Splunk`, `Datadog`, `CloudWatch`) & CSV/JSON Reports

Export or stream your audit ledger directly into your Security Operations Center (SOC) pipeline:

Formatted SIEM Export (GET /api/audit-logs/export-siem?format=...): Supports native schemas for:
- splunk_hec — Splunk HTTP Event Collector envelope format
- datadog — Datadog Logs & Cloud SIEM JSON format
- aws_cloudwatch — AWS CloudWatch Logs event batch format
- generic_json — Standard NDJSON / JSON array for Elastic, Sumo Logic, or QRadar
Auditor CSV / JSON Download (GET /api/audit-logs/export): Instant spreadsheet/JSON download of filtered events for compliance evidence packages.

4. User Login Activity (/user-activity) & Executive Analytics (/overview)

Live Authentication Stream (/user-activity)

Powered by GET /api/users/activity and GET /api/security/alerts. Tracks every interactive login, OAuth token grant, SAML assertion, MFA challenge, and failed login attempt with browser, OS, IP, and latency telemetry.

Executive Security Analytics (/overview)

Visualizes login volume trends (/api/analytics/login-trends), MFA adoption breakdown (/api/analytics/mfa-statistics), user growth (/api/analytics/user-growth), top applications (/api/analytics/top-applications), and compliance posture (/api/analytics/compliance-metrics).

5. Audit Logs, Security & Analytics API Reference

Method	Endpoint	Description
GET	`https://{your-tenant}.sso.id/api/audit-logs`	Queries paginated audit log entries (`GET /api/audit-logs/{id}` returns full JSON diff).
GET	`https://{your-tenant}.sso.id/api/audit-logs/verify-integrity`	Cryptographically verifies the SHA-256 tamper-evident hash chain across all audit logs.
GET	`https://{your-tenant}.sso.id/api/audit-logs/export-siem`	Exports logs in `splunk_hec`, `datadog`, `aws_cloudwatch`, or `generic_json` format (`GET /api/audit-logs/export` downloads CSV/JSON).
GET	`https://{your-tenant}.sso.id/api/users/activity`	Returns tenant-wide authentication telemetry (`GET /api/users/{userId}/activity` scopes to one user).
GET	`https://{your-tenant}.sso.id/api/security/alerts`	Returns active threat detection & anomaly alerts (`GET /api/security/session-status` checks session validity).
GET	`https://{your-tenant}.sso.id/api/analytics/dashboard-stats`	Returns executive KPIs (`login-trends`, `mfa-statistics`, `user-growth`, `authentication-stats`, `compliance-metrics`, `top-applications`).

AI Agent Prompt Build an Automated SIEM Forwarder & Daily Audit Hash-Chain Verifier

You are a SecOps and compliance automation engineer. Build a background worker service that integrates with **SSO.ID v2** (`https://{your-tenant}.sso.id/api`) to:
1. Run an hourly SIEM sync job that calls `GET https://{your-tenant}.sso.id/api/audit-logs/export-siem?format=splunk_hec` (or `datadog` / `aws_cloudwatch`) with `Authorization: Bearer ` and `X-Tenant-Id: `, and forwards new audit events to our SIEM collector.
2. Run a daily SOC 2 compliance verification check that calls `GET https://{your-tenant}.sso.id/api/audit-logs/verify-integrity` and `GET https://{your-tenant}.sso.id/api/security/alerts`, posting a summary report (and alerting on any hash-chain discrepancy or high-severity security alert) to our SecOps Slack/PagerDuty webhook.