Skip to content

api.md

Latest commit

 

History

History
300 lines (241 loc) · 12.5 KB

api.md

File metadata and controls

300 lines (241 loc) · 12.5 KB
Raw

HTTP API Reference

All production services bind to loopback or a Unix socket. The Docker sandbox binds service ports inside the compose network and only publishes the UI to the host by default.

Production control-plane endpoints fail closed when their configured bearer credential is unavailable. Registry and incident-recorder authorities are action-scoped; containment credentials are independent. The Docker sandbox may use a shared compatibility credential only when explicitly started in SECURE_AI_DEPLOYMENT_MODE=sandbox.

Registry API (port 8470)

Method Path Auth Description
GET /health No Liveness and model count.
GET /v1/models Read or admin List registered model artifacts.
GET /v1/model?name=<name> Read or admin Retrieve one artifact by name.
GET /v1/model/path?name=<name> Read or admin Return the model file path for a registered artifact.
POST /v1/model/verify?name=<name> Verify or admin Recompute and compare one model's SHA-256 hash.
POST /v1/models/verify-all Verify or admin Verify every registered model.
GET /v1/integrity/status Verify or admin Return aggregate registry integrity state.
POST /v1/model/verify-manifest?name=<name> Verify or admin Verify the gguf-guard per-tensor manifest for one GGUF model.
POST /v1/model/promote Promote Promote a quarantined artifact into the registry.
DELETE /v1/model/delete?name=<name> Admin Remove an artifact from the registry manifest.
POST /api/v1/quarantine Containment Remove one exact enrolled artifact from service.

Promotion body:

{
  "name": "model-name",
  "filename": "model.gguf",
  "sha256": "sha256...",
  "size_bytes": 123456789,
  "source": "huggingface",
  "scan_results": {},
  "scanner_versions": {}
}

Tool Firewall API (port 8475)

Method Path Auth Description
GET /health No Liveness plus request counters.
POST /v1/evaluate No Evaluate one tool call against policy.
GET /v1/stats No Policy and request counters.
POST /v1/reload Token Reload policy from disk.

Evaluation body:

{
  "tool": "filesystem.read",
  "params": {
    "path": "/vault/user_docs/example.txt"
  }
}

args is still accepted as a legacy alias for params. Responses use allowed: true|false and include reason when denied.

Airlock API (port 8490)

The Airlock is a policy decision service, not a generic open proxy. The UI checks each model download URL and redirect with the Airlock before downloading the artifact into quarantine.

Method Path Auth Description
GET /health No Liveness and enabled state.
POST /v1/egress/check No Decide whether an outbound request is allowed.
GET /v1/stats No Request counters and allowlist summary.
POST /v1/reload Token Reload policy and source allowlist.

Decision body:

{
  "destination": "https://huggingface.co/org/repo/resolve/main/model.gguf",
  "method": "GET",
  "body": ""
}

Responses use allowed: true|false and include reason when blocked. Disabled Airlock policy returns service-unavailable semantics to callers.

Policy Engine API (port 8500)

Method Path Auth Description
GET /health No Liveness.
POST /api/v1/decide No Evaluate a unified policy decision.
GET /api/v1/stats No Decision counters.
GET /api/v1/digest No Current policy digest.
POST /api/v1/reload Token Reload main and agent policies.

MCP Firewall API (port 8496)

Method Path Auth Description
GET /health No Liveness.
POST /v1/evaluate No Evaluate one MCP tool call.
POST /v1/evaluate/batch No Evaluate a batch of MCP tool calls.
GET /v1/servers No Summarize configured MCP servers and tools.
GET /v1/policy No Summarize loaded policy.
GET /v1/taint/<session_id> No Return taint state for a session.
DELETE /v1/taint/<session_id> No Clear taint state for a session.
GET /v1/audit No Return recent audit entries.
GET /v1/audit/verify No Verify the hash-chained audit log.
GET /v1/metrics No Decision and HTTP metrics.
POST /v1/reload Token Reload MCP policy.

Verification Services

Runtime Attestor (port 8505)

Method Path Auth Description
GET /health No Liveness and attestation state.
GET /api/v1/attest Service token Current full HMAC-authenticated attestation bundle.
GET /api/v1/verify Service token verified hardware evidence and distinct policy_satisfied startup decision.
GET /api/security/status Service token Assurance mode, evidence status, and counters.
POST /api/v1/refresh Token Refresh attestation state.

Integrity Monitor (port 8510)

Method Path Auth Description
GET /health No Liveness and integrity state.
GET /api/v1/status No Current monitor status.
GET /api/v1/baseline No Current baseline metadata.
GET /api/v1/verify No Verify current integrity state.
POST /api/v1/scan Token Trigger an immediate scan.
POST /api/v1/rebaseline Token Capture a new trusted baseline.
POST /api/v1/reload Token Reload monitor policy.

Incident Recorder (port 8515)

Method Path Auth Description
GET /health No Liveness and incident counts.
GET /api/v1/incidents Read List incidents, filterable by class, state, and severity.
GET /api/v1/incidents/get?id=<id> Read Fetch one incident.
GET /api/v1/stats Read Incident statistics.
GET /api/v1/recovery/status Recovery admin Pending recovery ceremonies.
POST /api/v1/incidents/report Source-bound reporter Report a new incident.
POST /api/v1/incidents/resolve Operator Mark an incident resolved.
POST /api/v1/incidents/acknowledge Operator Acknowledge an incident.
POST /api/v1/recovery/ack Recovery admin Acknowledge recovery requirements.
POST /api/v1/recovery/reattest Recovery admin Submit recovery re-attestation.
GET /api/v1/forensic/export Forensic Export a signed forensic bundle.
POST /api/v1/reload Operator Reload containment policy.

GPU Integrity Watch (port 8495)

Method Path Auth Description
GET /health No Liveness.
POST /v1/check No Run a probe cycle.
GET /v1/status No Latest verdict and probe results.
GET /v1/history No Score history.
GET /v1/metrics No Probe and action counters.
GET /v1/attest-state No GPU state for runtime attestation.
POST /v1/baseline Token Recapture GPU/model baseline.
POST /v1/reload Token Reload profile and baseline.

Agent API

Production UI-to-agent traffic uses /run/secure-ai/agent.sock. Development TCP fallback is 127.0.0.1:8476.

Method Path Description
GET /health Liveness.
POST /v1/task Submit a task.
GET /v1/task/<id> Get task status.
POST /v1/task/<id>/approve Approve pending steps.
POST /v1/task/<id>/deny Deny pending steps.
POST /v1/task/<id>/cancel Cancel a task.
GET /v1/tasks List recent tasks.
GET /v1/modes List operating modes.

The UI exposes authenticated proxy routes under /api/agent/* with the same task semantics.

UI API (port 8480)

Auth, Setup, And Pages

Method Path Description
GET /health UI liveness.
GET /api/auth/status Setup/login/session state.
POST /api/auth/setup Create the local passphrase.
POST /api/auth/login Start a session.
POST /api/auth/logout End a session.
POST /api/auth/change Change passphrase.
POST /api/setup/complete Mark setup complete.

Models And Catalog

Method Path Description
GET /api/catalog Curated model catalog.
POST /api/catalog/download Start a curated model download through Airlock checks.
GET /api/catalog/downloads Active/recent download status.
GET /api/catalog/auth/status Credential/auth guidance for model sources.
GET /api/models Registry and quarantine model summary.
GET /api/models/quarantine Quarantine status.
POST /api/models/import Upload/import a local model into quarantine.
POST /api/models/verify Verify one registered model.
POST /api/models/verify-manifest Verify gguf-guard manifest for one model.
POST /api/models/delete Delete a registered model.
GET /api/models/fsverity Model fs-verity/provenance summary.
GET /api/integrity/status Registry integrity status.
POST /api/integrity/verify-all Verify all registered models.

Chat, Search, And Generation

Method Path Description
GET /api/inference/status Inference service status and selected model readiness.
POST /api/chat Send one chat request.
POST /api/chat/stream Streaming chat.
POST /api/search Search mediator request.
GET /api/search/status Search availability/profile state.
POST /api/chat/search Chat with search context.
POST /api/generate/image Generate an image.
POST /api/generate/video Generate video frames/clip.
POST /api/generate/img2img Image-to-image generation.
GET /api/diffusion/models Diffusion model inventory.

Profiles And Sandbox Automation

Method Path Description
GET /api/profile Current privacy profile.
POST /api/profile/preview Preview a profile change.
POST /api/profile/select Select a privacy profile.
GET /api/profile/status Profile application status.
GET /api/sandbox/control/status Sandbox host-controller state.
POST /api/sandbox/control/apply Ask the host controller to restart/apply profile services.

Diffusion Runtime Installer

Method Path Description
GET /api/diffusion/runtime/status Runtime installed/failed/installable state.
POST /api/diffusion/runtime/enable Request privileged runtime installation via marker file.
GET /api/diffusion/runtime/progress Installer progress after enable is requested.

Security, Vault, Updates, And Observability

Method Path Description
GET /api/status Aggregate service health and SLO input.
GET /api/security/stats Security statistics.
GET /api/observability/appliance-state Appliance trust/degraded/recovery state.
GET /api/observability/slos Live SLO compliance metrics.
GET /api/forensic/export Returns local-console instructions; the UI does not hold forensic authority.
GET /api/audit/status Audit-chain status.
POST /api/audit/verify Verify audit-chain integrity.
GET /api/boot/status Boot security summary.
GET /api/boot/tpm2/status TPM2 status.
GET /api/boot/secureboot/status Secure Boot status.
GET /api/vault/status Vault state.
POST /api/vault/lock Always returns 501 with local-console lock instructions; the UI has no root service-control authority.
POST /api/vault/unlock Always returns 501; web passphrases are rejected and unlock requires the local console.
POST /api/vault/keepalive Reset vault idle timer.
GET /api/vm/status VM/hypervisor status.
POST /api/vm/gpu GPU status.
GET /api/emergency/status Emergency panic state.
POST /api/emergency/panic Trigger panic action.
GET /api/update/status Update state.
POST /api/update/check Check for updates.
POST /api/update/stage Stage an update.
POST /api/update/apply Apply staged update.
GET /api/update/health Update subsystem health.

Rollback is deliberately not exposed through the web API. Run sudo /usr/libexec/secure-ai/update-verify.sh rollback from a local root console.

Search Mediator API (port 8485)

Method Path Description
GET /health Liveness and enabled state.
POST /search Sanitize, route, and return a Tor-routed web search.