Initial OfficeCom Sentinel client and deployment assets

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

@@ -0,0 +1,131 @@
+# 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:
+
+```text
+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](C:/Users/Besitzer/Documents/AttackTracerNinjaVersion/samples/webhook-payload.example.json)
+
+## n8n response recommendation
+
+On success:
+
+- HTTP `200` or `202`
+- JSON body with minimal confirmation
+
+Example:
+
+```json
+{
+  "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.