71 lines
2.6 KiB
Markdown
71 lines
2.6 KiB
Markdown
# OfficeCom Sentinel n8n Contract
|
|
|
|
## Request
|
|
|
|
- method: `POST`
|
|
- content type: `application/json`
|
|
- example webhook: `https://n8n.example.com/webhook/ocsentinel-ingest`
|
|
|
|
## Required Payload Intent
|
|
|
|
The endpoint should send one signed JSON document per scan run containing:
|
|
|
|
- device identity
|
|
- client version
|
|
- scan metadata
|
|
- attack findings
|
|
- CVE correlation summary
|
|
- raw status fields needed for downstream NinjaOne updates
|
|
|
|
## Expected Downstream Work
|
|
|
|
n8n is responsible for:
|
|
|
|
- ingest validation
|
|
- storage in the central backend
|
|
- organization-wide aggregation
|
|
- NinjaOne organization API updates
|
|
|
|
## Required n8n Workflow
|
|
|
|
The webhook itself may be reachable only on the internal network. It does not
|
|
require public access to the n8n editor or API. Every managed device must be
|
|
able to reach the webhook URL over HTTPS.
|
|
|
|
For the isolated development environment only, HTTP is permitted at
|
|
`http://172.16.41.197:5678/webhook/ocsentinel-ingest`. Do not reuse this URL,
|
|
the development shared secret, or a disabled-TLS configuration in production.
|
|
|
|
1. `Webhook`: accept `POST` on the configured private URL.
|
|
2. `Code`: reject a request if `X-ATN-Device`, `X-ATN-Timestamp`,
|
|
`X-ATN-Nonce`, `X-ATN-Version`, `X-ATN-Payload-SHA256`, or
|
|
`X-ATN-Signature` is missing; reject timestamps outside five minutes.
|
|
3. `Code`: calculate SHA-256 over the raw request body and compare it with
|
|
`X-ATN-Payload-SHA256`. Calculate HMAC-SHA256 over the following exact
|
|
newline-separated string and compare it in constant time with
|
|
`X-ATN-Signature`:
|
|
|
|
```text
|
|
<device>\n<timestamp>\n<nonce>\n<version>\n<payload-sha256>
|
|
```
|
|
|
|
4. `Postgres`: insert the nonce into `ocsentinel.ingest_nonce` with a short
|
|
expiry. If it already exists, return `409` and do not process the report.
|
|
5. `Postgres`: upsert the device, insert a row in `ocsentinel.scan_report`,
|
|
then return `202`.
|
|
6. A separate scheduled n8n workflow reads
|
|
`ocsentinel.organization_summary` and `ocsentinel.current_device_status`
|
|
to update the NinjaOne organization fields through the API.
|
|
|
|
Use an n8n credential for the shared HMAC secret and a separate n8n credential
|
|
for PostgreSQL. Do not store either value in workflow JSON or this repository.
|
|
For the current Docker deployment, use the private hostname
|
|
`ocsentinel-postgres` and the restricted database role `ocsentinel_n8n`; see
|
|
`infra/dockge/README.md` for the remaining credential fields.
|
|
|
|
## PostgreSQL Scope
|
|
|
|
- The client only knows its outward upload destination.
|
|
- PostgreSQL connection details belong to the internal ingest or n8n side.
|
|
- If the PostgreSQL IP changes, update the internal server-side configuration and review it during the next release.
|