Audit & SIEM

Configure access

In the organization Audit workspace, an authorized administrator creates an inbound source and retains its source key and one-time signing secret. Configure outbound SIEM destinations separately, using the workspace’s destination test and activation flow. Inbound event credentials do not authorize administrative queries.

Cabinet route: /organizations/:organizationId/audit → Controls → Inbound sources or SIEM destinations. Required permission: organization.audit.siem.manage; viewing requires organization.audit.siem.view.

• Open Hallify

First successful workflow

Follow these steps in order. Open each method for its exact body, required headers and response schema.

1. Build 1–500 OCSF JSON events as UTF-8 NDJSON, one object per line, within 2 MB.
2. Sign Unix seconds + "." + the exact raw body with the decoded 32-byte source secret.
3. POST to the organization/source events endpoint and retain the accepted batch identifier and counts.

• Ingest a signed external audit event batch

State, retries and recovery

Do not parse and reserialize the body after signing. A repeated signature returns 409 AUDIT_INGRESS_REPLAY. Events are validated before persistence; an unavailable source or undecryptable signing secret blocks ingestion. SIEM delivery uses its separately configured transport; it does not share the inbound signing protocol.

• Errors and limits
• Access and authentication

Receive outbound SIEM batches

After creating a destination, test connectivity and activate the tested revision. The receiver accepts gzip-compressed OCSF 1.8.0 NDJSON: Content-Type application/x-ndjson and Content-Encoding gzip. X-Hallify-Batch-Id and Idempotency-Key carry the batch identity; X-Hallify-OCSF-Version is 1.8.0.

Verify X-Hallify-Content-SHA256 and HMAC-SHA256 X-Hallify-Signature against the exact compressed bytes before decompression. Both are hexadecimal; decode the issued base64url secret to 32 bytes. This protocol has no timestamp prefix. Accept the batch durably and idempotently by its identity before acknowledging success.

Retryable HTTP statuses are 408, 429 and 5xx. Numeric Retry-After is capped at one hour; otherwise exponential jitter is capped at 15 minutes. Inspect destination and delivery status in Audit for diagnosis. This outbound protocol differs from inbound event signing.

import { createHash, createHmac, timingSafeEqual } from 'node:crypto';

export function verifySiemBatch(compressedBytes, contentHash, signature) {
  const validMetadata = /^[0-9a-f]{64}$/.test(contentHash)
    && /^[0-9a-f]{64}$/.test(signature);
  if (!validMetadata) return false;
  const secret = Buffer.from(process.env.HALLIFY_SIEM_SECRET, 'base64url');
  if (secret.length !== 32) return false;
  const expectedHash = createHash('sha256').update(compressedBytes).digest();
  const expectedSignature = createHmac('sha256', secret).update(compressedBytes).digest();
  return timingSafeEqual(Buffer.from(contentHash, 'hex'), expectedHash)
    && timingSafeEqual(Buffer.from(signature, 'hex'), expectedSignature);
}