Ingest a sensor scan report

POST

/v1/sensors/ingest

curl --request POST \
  --url https://api.nextpki.com/v1/sensors/ingest \
  --header 'Content-Type: application/json' \
  --data '{ "machine_id": "example", "primary_ip": "example", "results": [ { "ip": "10.20.4.10", "port": 443, "hostname": "example", "sni": "example", "protocol": "PROTOCOL_HTTPS", "certificates": [ "example" ] } ] }'

Receives one scan report from a registered sensor and returns the configuration the control plane wants that sensor to run.

This endpoint is not called directly by API clients. A sensor reports over HTTPS through the edge, which terminates TLS, verifies the sensor’s client certificate against the internal sensor CA, and forwards the verified identity as headers. The API trusts those headers only from the loopback edge peer and only when X-Client-Cert-Verified: SUCCESS is set; the tenant is resolved from the SPIFFE ID in X-Client-Cert-San-Uri. A direct external call has neither and is rejected. See the sensor network requirements.

Request Body^required

Media typeapplication/json

object

machine_id

required

Stable machine identifier

string

primary_ip

Optional: the sensor’s own primary address

string

results

required

Array<object>

object

ip

required

string

Example

10.20.4.10

port

required

integer

Example

443

hostname

string

sni

string

protocol

string

Example

PROTOCOL_HTTPS

certificates

required

The presented chain as base64-DER strings, leaf first

Array<string>

Responses

200

Accepted - the response carries the config to apply

Media typeapplication/json

object

ingest_id

required

string format: uuid

accepted

required

integer

rejected

integer

warnings

Array<string>

config_version

required

0 when the control plane has no config for this sensor yet

integer

config

The scan configuration the control plane wants this sensor to run.

object

targets

Array<string>

ports

Array<integer>

include

Array<string>

exclude

Array<string>

scan_profile

string

scan_interval_secs

integer

probe_timeout_ms

integer

paused

boolean

Example^generated

{
  "ingest_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "accepted": 1,
  "rejected": 1,
  "warnings": [
    "example"
  ],
  "config_version": 1,
  "config": {
    "targets": [
      "example"
    ],
    "ports": [
      1
    ],
    "include": [
      "example"
    ],
    "exclude": [
      "example"
    ],
    "scan_profile": "example",
    "scan_interval_secs": 1,
    "probe_timeout_ms": 1,
    "paused": true
  }
}

400

Malformed body, missing machine_id, unknown field, undecodable certificate, or a body over the size limit. The reason is in error.

Media typeapplication/json

object

error

string

Example^generated

{
  "error": "example"
}

401

No verified client-certificate identity: client_cert_required (the edge did not set X-Client-Cert-Verified: SUCCESS) or bad_identity (the forwarded SPIFFE ID was unusable).

Media typeapplication/json

object

error

string

Example^generated

{
  "error": "example"
}

403

not_via_edge - the request did not come from the loopback edge peer, so its client-certificate headers cannot be trusted.

Media typeapplication/json

object

error

string

Example^generated

{
  "error": "example"
}