132 lines
2.5 KiB
Markdown
132 lines
2.5 KiB
Markdown
# 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.
|