Lockdown API

Use these endpoints on the same device API base URL as POST /api/lockdown-mode, for example http://<device-ip>:5000.

These endpoints are implemented in the device API:

Purpose	Method	Endpoint
Read lockdown state	GET	/api/lockdown-mode
Enable or disable lockdown mode	POST	/api/lockdown-mode
Run lockdown system scan	POST	/api/lockdown-diagnostics/audit
Preview log cleanup	POST	/api/lockdown-diagnostics/clear-preview
Clear plaintext logs and reboot	POST	/api/lockdown-diagnostics/clear
Encrypt existing plaintext logs	POST	/api/lockdown-diagnostics/encrypt
Poll diagnostics job status	GET	/api/lockdown-diagnostics/job-status

Recommended Flow

After enabling lockdown mode, the usual flow is:

1. Confirm lockdown mode is enabled.

2. Run the audit scan to see whether plaintext logs or other sensitive artifacts still exist.

3. If the scan reports artifacts that should be removed, run a clear preview.

4. Run the actual clear operation.

5. Poll job status until complete.

6. Confirm the clear result includes reboot_scheduled: true.

The diagnostics operations are asynchronous. A POST starts a job; GET /api/lockdown-diagnostics/job-status returns progress and final results. Only one diagnostics job can run at a time.

1. Confirm Lockdown Mode

Why: make sure the device is in lockdown mode before scanning or clearing old plaintext artifacts.

GET /api/lockdown-mode

Response:

{
  "code": "SUCCESS",
  "data": true,
  "message": "..."
}

data: true means lockdown mode is enabled.

2. Enable Lockdown Mode

Why: enables encrypted logging behavior and schedules a device reboot when changing from disabled to enabled.

POST /api/lockdown-mode
Content-Type: application/json

{ "enabled": true }

Expected response when the value changes from disabled to enabled:

{
  "code": "SUCCESS",
  "message": "Lockdown mode enabled. Device is rebooting.",
  "data": true,
  "service_restarted": true,
  "reboot_scheduled": true
}

reboot_scheduled: true means the device API successfully scheduled the edge device reboot.

3. Run The Audit Scan

Why: scan the device after lockdown mode is enabled to check for remaining plaintext logs or other lockdown-related findings.

POST /api/lockdown-diagnostics/audit
Content-Type: application/json

No body is required.

Response:

{
  "code": "SUCCESS",
  "message": "Started lockdown diagnostics audit",
  "data": {
    "action": "audit",
    "in_progress": true,
    "phase": "running",
    "error": null,
    "started_at": "2026-05-30T00:00:00Z",
    "finished_at": null,
    "output_lines": [],
    "result": null
  }
}

Then poll job status.

GET /api/lockdown-diagnostics/job-status

The audit is finished when data.in_progress is false. A completed audit result can include summary, findings, and a human-readable message.

Example:

{
  "code": "SUCCESS",
  "data": {
    "action": "audit",
    "in_progress": false,
    "phase": "complete",
    "error": null,
    "started_at": "2026-05-30T00:00:00Z",
    "finished_at": "2026-05-30T00:00:05Z",
    "output_lines": [],
    "result": {
      "message": "Lockdown audit completed",
      "summary": {
        "pass": 10,
        "warn": 1,
        "fail": 0
      },
      "findings": []
    }
  }
}

4. Preview The Clear Operation

Why: see what the cleanup operation would delete before deleting anything.

POST /api/lockdown-diagnostics/clear-preview
Content-Type: application/json

No body is required. This is a dry run.

Poll job status until data.in_progress is false.

Example completed preview result:

{
  "code": "SUCCESS",
  "data": {
    "action": "clear-preview",
    "in_progress": false,
    "phase": "complete",
    "error": null,
    "started_at": "2026-05-30T00:00:00Z",
    "finished_at": "2026-05-30T00:00:05Z",
    "output_lines": [],
    "result": {
      "message": "Preview found 3 log artifacts",
      "dry_run": true,
      "deleted_count": 3,
      "inspected_count": 25,
      "paths": [
        "/path/to/log-1",
        "/path/to/log-2",
        "/path/to/log-3"
      ],
      "truncated_paths": 0,
      "preview_token": "example-token",
      "preview_expires_at": 1760000000
    }
  }
}

deleted_count is the number of artifacts that would be removed by the real clear operation.

5. Clear Logs After Lockdown

Why: remove old plaintext log artifacts and purge the journal after lockdown is enabled, then reboot the device so it comes back in a clean lockdown state.

POST /api/lockdown-diagnostics/clear
Content-Type: application/json

No body is required.

If you want to enforce that the clear matches a recent preview, pass the preview token from clear-preview:

{
  "preview_token": "example-token"
}

The preview token expires after 5 minutes. If no token is provided, the clear operation still runs.

Starting the clear job returns:

{
  "code": "SUCCESS",
  "message": "Started lockdown diagnostics clear; ecal-rec stopped and device will reboot after cleanup",
  "data": {
    "action": "clear",
    "in_progress": true,
    "phase": "running",
    "error": null,
    "started_at": "2026-05-30T00:00:00Z",
    "finished_at": null,
    "output_lines": [],
    "result": null
  }
}

Poll job status until data.in_progress is false.

Example completed clear result:

{
  "code": "SUCCESS",
  "data": {
    "action": "clear",
    "in_progress": false,
    "phase": "complete",
    "error": null,
    "started_at": "2026-05-30T00:00:00Z",
    "finished_at": "2026-05-30T00:00:05Z",
    "output_lines": [],
    "result": {
      "message": "Deleted 3 log artifacts. Device is rebooting.",
      "deleted_count": 3,
      "inspected_count": 25,
      "reboot_scheduled": true
    }
  }
}

reboot_scheduled: true means the device API scheduled the reboot after cleanup.

Encrypt Existing Plaintext Logs

Why: preserve existing plaintext logs by encrypting them instead of deleting them.

POST /api/lockdown-diagnostics/encrypt
Content-Type: application/json

No body is required.

Poll job status until complete.

Example completed encrypt result:

{
  "code": "SUCCESS",
  "data": {
    "action": "encrypt",
    "in_progress": false,
    "phase": "complete",
    "error": null,
    "started_at": "2026-05-30T00:00:00Z",
    "finished_at": "2026-05-30T00:00:05Z",
    "output_lines": [],
    "result": {
      "message": "Encrypted 3 plaintext files",
      "files_encrypted": 3
    }
  }
}

Use either clear or encrypt depending on whether the goal is to delete old plaintext artifacts or preserve them in encrypted form.