# 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.