oc-sentinel/docs/attacktracer-ninja-v2-n8n-contract.md

AttackTracer Ninja V2 n8n Contract

Purpose

This document defines the concrete webhook contract between the endpoint client and n8n.

Request

Method:

• POST

Content type:

• application/json

Webhook URL:

• example: https://n8n.example.com/webhook/attacktracer-ingest

Required headers

• X-ATN-Device
• X-ATN-Timestamp
• X-ATN-Nonce
• X-ATN-Version
• X-ATN-Payload-SHA256
• X-ATN-Signature

Header semantics

• X-ATN-Device
  • endpoint machine name used for attribution
• X-ATN-Timestamp
  • UTC timestamp in ISO 8601 format
• X-ATN-Nonce
  • unique per request, used for replay protection
• X-ATN-Version
  • client version string
• X-ATN-Payload-SHA256
  • SHA-256 over the JSON body, lowercase hex
• X-ATN-Signature
  • HMAC-SHA256 over the canonical signing string, lowercase hex

Canonical signing string

The client signs this exact string:

device + "\n" + timestamp + "\n" + nonce + "\n" + version + "\n" + payloadSha256

Signature algorithm

• HMAC-SHA256

Recommended n8n validation

1. Reject when a required header is missing.
2. Reject when timestamp skew exceeds allowed tolerance.
3. Reject when nonce was already seen.
4. Recompute payload hash and compare to X-ATN-Payload-SHA256.
5. Recompute HMAC and compare to X-ATN-Signature.
6. Parse JSON only after headers and signature validation pass.

Suggested timestamp tolerance

• 5 minutes

Suggested replay protection persistence

Persist nonce records in Postgres with:

• nonce
• device
• timestamp
• first_seen_utc

JSON body schema

The body is a ScanResult JSON document with schema version 2.0.

Key fields:

• schemaVersion
• machineName
• generatedAtUtc
• clientVersion
• lookbackDays
• alertState
• baseAlertState
• totalEvents
• uniqueIpCount
• errors
• vulnerabilityCorrelation
• runtime

Example body

See:

• webhook-payload.example.json

n8n response recommendation

On success:

• HTTP 200 or 202
• JSON body with minimal confirmation

Example:

{
  "accepted": true,
  "device": "WSUS",
  "nonce": "f53a3f0b0c2c466ea1717d88d55fd393"
}

On failure:

• HTTP 4xx for validation/signature problems
• HTTP 5xx for processing/storage problems

Device identity guidance

The webhook should not trust machineName alone for authorization.

For initial rollout, use the shared secret as the trust anchor. For later hardening, add a per-device secret or enrollment identity.