Skip to content

registry.md

Latest commit

 

History

History
141 lines (94 loc) · 3.86 KB

registry.md

File metadata and controls

141 lines (94 loc) · 3.86 KB

Registry Service

Overview

  • Purpose: Trusted artifact manifest and read-only model store
  • Port: 8470
  • Language: Go
  • Systemd unit: secure-ai-registry.service

The Registry is the single source of truth for which models are available for inference. Only models that have passed the full quarantine pipeline can be promoted into the registry. Once promoted, models are served read-only to the inference worker.

API Endpoints

GET /v1/models

List all registered artifacts.

Response: 200 OK

[
  {
    "name": "mistral-7b-instruct-v0.3.Q4_K_M",
    "path": "/var/lib/secure-ai/registry/mistral-7b-instruct-v0.3.Q4_K_M.gguf",
    "sha256": "abc123...",
    "format": "gguf",
    "source": "huggingface",
    "status": "promoted",
    "promoted_at": "2026-03-06T12:00:00Z",
    "gguf_guard_fingerprint": "def456...",
    "gguf_guard_manifest": { ... }
  }
]

GET /v1/model?name=

Get a single artifact by name.

Response: 200 OK with artifact JSON, or 404 Not Found.

GET /v1/model/path?name=

Return the resolved filesystem path for a registered model.

POST /v1/model/promote

Promote a quarantined artifact to the registry. Called by the quarantine pipeline after all stages pass.

Request body:

{
  "name": "mistral-7b-instruct-v0.3.Q4_K_M",
  "filename": "mistral-7b-instruct-v0.3.Q4_K_M.gguf",
  "sha256": "abc123...",
  "size_bytes": 4567890123,
  "source": "huggingface",
  "scanner_versions": {
    "modelscan": "0.8.8"
  }
}

Auth: service bearer token. Response: 201 Created on success, 400 Bad Request if validation fails.

DELETE /v1/model/delete?name=

Remove an artifact from the registry.

Auth: service bearer token. Response: 200 OK on success, 404 Not Found if not registered.

POST /v1/model/verify?name=

Recompute one model's SHA-256 hash and compare it with the manifest.

POST /v1/models/verify-all

Verify SHA-256 integrity for all registered artifacts.

POST /v1/model/verify-manifest?name=

Verify the gguf-guard per-tensor manifest for one GGUF artifact.

Response: 200 OK with verification results.

Data Model

The Artifact struct represents a registered model:

Field Type Description
name string Human-readable model name
path string Absolute filesystem path to the model file
sha256 string SHA-256 hash of the model file at promotion time
format string File format (gguf, safetensors, etc.)
source string Origin (huggingface, local, etc.)
status string Current status (promoted, quarantined)
promoted_at timestamp When the model was promoted
gguf_guard_fingerprint string Structural fingerprint from gguf-guard (GGUF only)
gguf_guard_manifest object Per-tensor manifest from gguf-guard (GGUF only)

Manifest Storage

The registry persists its state to a JSON manifest file:

/var/lib/secure-ai/registry/manifest.json

This file is read on startup and written on every promote/delete operation. It is the authoritative record of all trusted models.

Integrity Monitoring

A systemd timer runs every 15 minutes to verify the SHA-256 hash of every registered model file against the value stored in the manifest. If a mismatch is detected:

  1. The affected model is moved to quarantine status.
  2. An alert is logged to the audit log.
  3. The model becomes unavailable for inference until re-verified.

This detects both accidental corruption and tampering.

Systemd Sandboxing

The registry service runs with hardened systemd settings:

  • ProtectSystem=strict -- read-only root filesystem
  • ProtectHome=yes -- no access to home directories
  • PrivateTmp=yes -- isolated /tmp
  • NoNewPrivileges=yes -- cannot gain new privileges
  • ReadWritePaths=/var/lib/secure-ai/registry -- only writable path