CPS / IoT device attestation

When you'd use this

The dashboard's CPS Device Fleet panel surfaces device-level attestation status alongside a risk score. This runbook explains what the columns mean, when to investigate a device, and how to escalate.

Columns

• Device ID, the deterministic identifier the device presented at enrollment.
• Type, PLC, RTU, HMI, IP-Cam, Gateway, etc. Determines which policy bundle applies.
• Attestation,
  • verified: the device's last attestation report matched the expected hash, certificate chain, and firmware version.
  • pending: a report has been issued but not yet reviewed (the attestation worker is behind, or the device is in burn-in).
  • revoked: the device's cert was revoked; it cannot re-attest until re-enrolled.
• Risk, a 0–100% score combining firmware version drift, observed telemetry anomalies, and known IOC hits. Bar colour is red above 70%, yellow above 30%, green below.
• Location, the physical site reading from the site controller.

What to investigate

• Risk above 70%, review the device detail. The detail page shows the trail of telemetry that drove the score and any related cases. Decide whether to dispatch the CPS Security agent, isolate the device on the OT segment, or escalate to facilities.
• Pending attestation, usually transient. If a device sits in pending for more than 24 hours, the attestation worker is behind or the device is silent. Check the observability page for attestation_pending_total.
• Revoked attestation, the device is locked out of the OT bus. Re-enrollment requires a facilities sign-off and a fresh OTT (one-time token).

Escalation

• Network anomaly on an OT device, pair with the Network Attack triage runbook. OT segments produce false positives easily; the correlator's confidence number is your filter.
• Firmware drift, open a case linked to the device and attach the firmware inventory snapshot. The firmware workflow is owned by the platform team; your job is to observe and document, not to update firmware from the operator console.

What goes wrong

• The risk score does not match what you see in the field, the policy bundle that drives the score may be stale; check the page footer for the bundle version. The bundle refresh is owned by the platform team.
• A device disappears from the list, either the device went offline (lost telemetry) or the site controller for that location is down. The Sites page shows controller liveness.
• The CPS Security agent dispatch times out, the underlying MCP server may be down. Check the observability dashboard for the cps MCP server status.

Key provisioning

CPS devices use the DICE (Device Identifier Composition Engine) Layering Architecture for cryptographic identity. The key hierarchy starts with a device-unique hardware secret and derives upward.

Step 1: Generate device-unique seed

The device reads its UDS (Unique Device Secret) from a one-time- programmable fuse or secure element. This value is never readable outside the secure boot path.

UDS = read_fuse(FUSE_UDS)

Step 2: Derive the CDI

The Compound Device Identifier is computed by hashing the UDS with the hash of the first mutable code (Layer 0 firmware):

CDI = HMAC-SHA256(UDS, SHA256(Layer0_Firmware))

If firmware changes, the CDI changes. This is intentional: a compromised firmware image produces a different CDI that cannot impersonate the authorised device.

Step 3: Request an enrollment token

The device sends its CDI (as a public commitment, never the raw UDS) to the OTT (One-Time Token) service:

POST /api/v1/cps/ott/request
{
  "device_id": "PLC-BAY7-03",
  "cdi_commitment": "sha256:ab12...ef34",
  "device_type": "PLC",
  "firmware_version": "v2.4.1"
}

The OTT service returns a single-use enrollment token valid for 60 seconds:

{
  "ott": "eyJhbGciOi...",
  "expires_at": "2026-06-14T12:01:00Z"
}

Step 4: Enroll x.509 certificate via EST

The device uses the OTT to authenticate against the EST (Enrollment over Secure Transport) endpoint:

POST /api/v1/cps/est/enroll
Authorization: Bearer {ott}
Content-Type: application/pkcs10

-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----

AuroraSOC signs the CSR and returns the device certificate. The device stores it in its secure element alongside the private key.

Step 5: Confirm enrollment

GET /api/v1/cps/devices/PLC-BAY7-03

The device should now appear in the CPS Device Fleet dashboard with attestation status pending. Proceed to operator approval.

Device enrollment workflow

1. Device boots with DICE-validated firmware. The secure boot path computes the CDI from UDS + Layer 0 hash. If the hash mismatches the golden image, the device halts and surfaces a tamper event.

2. Device connects to the AuroraSOC MQTT broker on the OT segment (port 8883 with mutual TLS). It presents its CDI commitment in the enrollment topic:

   Topic: cps/enroll/PLC-BAY7-03
   Payload: {"cdi_commitment": "sha256:ab12...", "model": "S7-1200", "fw": "v2.4.1"}

3. The OTT (One-Time Token) service validates the commitment against the site controller's device inventory. If the device is expected (pre-registered by facilities), an OTT is issued.

4. The device calls the EST endpoint with the OTT to obtain its x.509 certificate. The certificate is signed by the AuroraSOC internal CA with the device's CDI commitment as a SAN extension.

5. The device appears in the CPS Device Fleet dashboard with status pending. An operator reviews the device entry and clicks Approve. This moves the device to verified and enables periodic attestation challenges.

6. If the operator clicks Reject, the certificate is revoked and the device is removed from the fleet view. A case is auto-created with the rejection reason for audit trail.

Challenge-response configuration

Periodic attestation proves the device still runs the authorised firmware and holds the original key. The parameters are tuned per device criticality.

Challenge parameters

Parameter	Critical devices	Standard devices
Nonce size	32 bytes	32 bytes
Challenge interval	5 minutes	30 minutes
Allowed clock skew	2 seconds	2 seconds
Attestation timeout	10 seconds	10 seconds
Failure threshold	3 consecutive failures	3 consecutive failures

Configure from the dashboard under Settings > CPS > Attestation, or via the API:

PATCH /api/v1/settings/runtime
{
  "cps_attestation": {
    "nonce_size": 32,
    "challenge_interval_critical_s": 300,
    "challenge_interval_standard_s": 1800,
    "allowed_clock_skew_s": 2,
    "attestation_timeout_s": 10,
    "failure_threshold": 3
  }
}

Challenge message

AuroraSOC publishes a challenge to the device's MQTT topic:

{
  "type": "attestation_challenge",
  "device_id": "PLC-BAY7-03",
  "nonce": "8f3a91bc02d7e4c5a1b6f8093d2e7c1a",
  "timestamp": "2026-06-14T12:00:00Z",
  "challenge_id": "ch-9a2b"
}

Expected response

The device must respond within the timeout with a signed response on the topic cps/attest/response:

{
  "type": "attestation_response",
  "challenge_id": "ch-9a2b",
  "device_id": "PLC-BAY7-03",
  "nonce": "8f3a91bc02d7e4c5a1b6f8093d2e7c1a",
  "firmware_hash": "sha256:3d4e...",
  "cert_chain": ["-----BEGIN CERTIFICATE-----..."],
  "signature": "MEUCIQD...",
  "timestamp": "2026-06-14T12:00:03Z"
}

The nonce must match exactly. The firmware hash must match the golden value registered during enrollment. The certificate chain must validate against the AuroraSOC internal CA. The signature must verify with the device's public key.

Verification and result interpretation

Statuses

Status	Colour	Meaning	Action
verified	Green	Firmware hash, certificate chain, and nonce all pass	No action. Device is trusted.
pending	Yellow	Challenge sent but response not yet reviewed, or device is in burn-in	Wait for next cycle. Escalate if > 24 hours.
failed	Red	Hash mismatch, nonce mismatch, or certificate chain validation error	Investigate immediately. Open case.
revoked	Black	Device certificate has been revoked	Device locked out. Re-enrollment required.

Attestation result payload

{
  "device_id": "PLC-BAY7-03",
  "status": "verified",
  "firmware_hash": "sha256:3d4e...",
  "cert_chain_valid": true,
  "nonce_match": true,
  "timestamp": "2026-06-14T12:00:03Z",
  "risk_score": 5.0
}

If cert_chain_valid is false, the device's certificate has expired, been revoked, or does not chain to the trusted CA. If nonce_match is false, the response nonce does not match the challenge nonce (possible replay attack or clock issue). If firmware_hash differs from the enrolled golden hash, the device may be running unauthorised firmware.

Interpreting risk score

The risk score (0--100) combines firmware drift, telemetry anomalies, and known IOC hits:

• 0--30: Normal operation. Routine monitoring.
• 31--70: Elevated. Review the device detail page for contributing factors. Consider a manual attestation challenge.
• 71--100: Critical. Open a case, dispatch the CPS Security agent, and consider segment isolation.

Troubleshooting

Attestation timeout

The device did not respond to the challenge within the configured timeout (default 10 seconds).

• Check the device's MQTT connectivity on the OT segment. Verify the broker is reachable on port 8883.
• Check the site controller liveness on the Sites page.
• If the device is a low-power sensor, increase the timeout via the API: PATCH /api/v1/settings/runtime with a higher attestation_timeout_s value.

Firmware hash mismatch

The reported firmware hash does not match the golden value from enrollment.

• Expected after an OTA firmware update. Re-enroll the device to register the new golden hash: run the enrollment workflow again from Key provisioning step 3.
• If no OTA was performed, the device may be compromised. Open a case and dispatch the CPS Security agent immediately.

Certificate chain invalid

The device's x.509 certificate does not validate against the AuroraSOC internal CA.

• Check the OTT service is running: GET /api/v1/mcp/health and verify the cps domain status.
• Regenerate the enrollment token and re-enroll the device.
• If the CA itself is expired, contact the platform team to rotate the AuroraSOC internal CA certificate.

Nonce mismatch

The response nonce does not match the challenge nonce.

• The most common cause is clock skew. Verify NTP is synchronised on both the device and the AuroraSOC server.
• Adjust allowed_clock_skew_s if the device operates in an environment with loose time synchronisation.
• If clock is correct, a nonce mismatch may indicate a replay attempt. Open a case and isolate the device.

Revoked device re-enrollment

If a device was revoked (status revoked), it cannot re-attest until re-enrolled.

• Obtain a fresh OTT from the OTT service. The old enrollment token is invalid after revocation.
• To generate a new OTT, the device must be re-registered in the site controller's device inventory: POST /api/v1/cps/devices with the device's updated metadata.
• After re-enrollment, the device moves to pending. Operator approval restores it to verified.