Přeskočit obsah

API pro agenty

Registrace agentů, heartbeat, discovery a správa

Verze dokumentu: 1.1.0
Poslední aktualizace: 2026-04-04

Přehled

Agenti MazeVault jsou lehké procesy nasazené na uzlech infrastruktury, které zajišťují:

  • Automatické vkládání tajemství do aplikací
  • Objevování certifikátů napříč spravovanou infrastrukturou
  • Synchronizaci tajemství a certifikátů v reálném čase
  • Bezpečný proxy pro přístup lokálních aplikací k tajemstvím

Přehled endpointů

Metoda Endpoint Autentizace Popis
POST /api/v1/agents/register Bootstrap token Registrovat nového agenta
POST /api/v1/agents/bootstrap JWT + agent:admin Vygenerovat bootstrap token
GET /api/v1/agents JWT + agent:admin Zobrazit agenty
GET /api/v1/agents/:id/discovery JWT + agent:admin Získat výsledky discovery agenta
GET /api/v1/agents/update/latest Agent Cert Zkontrolovat aktualizace agenta
POST /api/v1/agents/me/refresh-token mTLS Obnovit token agenta
POST /api/v1/agents/me/health JWT Nahlásit stav agenta
GET /api/v1/agents/me/certificates JWT Získat přiřazené certifikáty
GET /api/v1/agents/me/connect JWT WebSocket připojení agenta
POST /api/v1/agents/me/discovery/certificates JWT Nahlásit objevené certifikáty
POST /api/v1/agents/me/password-requests JWT Vytvořit žádost o heslo
GET /api/v1/agents/me/password-requests JWT Získat čekající odpovědi na hesla
POST /api/v1/agents/me/ssh-discovery JWT Nahlásit objevené SSH klíče

Registrace agenta

Krok 1: Vygenerování bootstrap tokenu

Vytvořte bootstrap token ve webovém rozhraní MazeVault:

Nastavení → Agenti → Vygenerovat bootstrap token

Token je platný po konfigurovatelnou dobu (výchozí: 24 hodin) a může být použit pro stanovený počet registrací.

Krok 2: Registrace agenta

POST /api/v1/agents/register HTTP/1.1
Content-Type: application/json

{
  "token": "***REMOVED***",
  "name": "app-server-01",
  "hostname": "app-server-01.example.com",
  "os_type": "linux",
  "metadata": {
    "environment": "production",
    "datacenter": "eu-west-1",
    "role": "application-server"
  }
}

Pole požadavku

Pole Typ Povinné Popis
token string ✅ Bootstrap token
name string ✅ Zobrazovaný název agenta
hostname string — FQDN hostitele
os_type string — Typ operačního systému (např. linux, windows)
metadata object — Metadata klíč–hodnota (nahrazuje labels)

Odpověď 201 Created

{
  "id": "agt_xyz789",
  "token": "eyJ...",
  "mtls_template_id": "tmpl_agent_mtls"
}
Pole Popis
id ID agenta pro následné požadavky
token JWT token pro autentizované API volání
mtls_template_id ID šablony certifikátu pro mTLS registraci

Stav agenta (Health)

Agenti pravidelně hlásí svůj stav:

POST /api/v1/agents/me/health HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "healthy",
  "uptime_seconds": 86400,
  "metrics": {
    "cpu_percent": 15.2,
    "memory_percent": 42.8,
    "disk_percent": 67.1
  },
  "managed_secrets": 12,
  "managed_certificates": 5,
  "last_sync": "2026-02-10T16:55:00Z"
}

Odpověď 200 OK

{
  "acknowledged": true,
  "server_time": "2026-02-10T17:00:00Z",
  "commands": []
}

Pole commands může obsahovat čekající instrukce pro agenta (např. vynucení synchronizace, obnovení certifikátu).

Objevování certifikátů

Agenti mohou skenovat svou lokální infrastrukturu a hlásit objevené certifikáty:

POST /api/v1/agents/me/discovery/certificates HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "certificates": [
    {
      "subject": "CN=legacy-app.internal,O=Example Corp",
      "serial_number": "AB:CD:EF:01:23",
      "issuer": "CN=Internal CA",
      "not_before": "2025-06-15T00:00:00Z",
      "not_after": "2026-06-15T00:00:00Z",
      "location": "/etc/ssl/certs/legacy-app.pem",
      "fingerprint": "SHA256:abc123...",
      "dns_names": ["legacy-app.internal"],
      "ip_addresses": ["10.0.2.50"],
      "source": "filesystem",
      "is_managed": false
    }
  ]
}

Odpověď 200 OK

{
  "accepted": 1,
  "duplicates": 0,
  "errors": 0
}

Objevené certifikáty se zobrazí ve webovém rozhraní MazeVault v sekci Certifikáty → Objevené k přezkoumání a volitelnému importu.

Výpis agentů

GET /api/v1/agents?status=online&page=1 HTTP/1.1
Authorization: Bearer <token>

Pouze pro administrátory

Tento endpoint vyžaduje oprávnění agent:admin.

Parametry dotazu

Parametr Typ Popis
status string Filtrovat: online, offline, degraded
label string Filtrovat podle štítku (klíč=hodnota)
search string Vyhledávat podle hostname
page integer Číslo stránky
per_page integer Položek na stránku

Odpověď 200 OK

{
  "data": [
    {
      "id": "agt_xyz789",
      "hostname": "app-server-01.example.com",
      "status": "online",
      "platform": "linux/amd64",
      "agent_version": "1.8.0",
      "labels": {
        "environment": "production",
        "datacenter": "eu-west-1"
      },
      "last_heartbeat": "2026-02-10T17:00:00Z",
      "managed_secrets": 12,
      "managed_certificates": 5,
      "registered_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

Stavy agenta

Stav Popis Podmínka
online Agent je zdravý a hlásí se Poslední heartbeat < 2× interval
degraded Agent hlásí problémy Heartbeat přijat, ale metriky ukazují problémy
offline Agent neodpovídá Poslední heartbeat > 3× interval

Požadovaná oprávnění

Operace Požadované oprávnění
Registrovat agenta Bootstrap token (bez uživatelské autentizace)
Zobrazit agenty agent:admin
Vygenerovat bootstrap token agent:admin
Získat výsledky discovery agent:admin
Health / Discovery / Password-requests Agent JWT (self-service)
Obnovit token mTLS klientský certifikát

Žádosti o hesla agenta

Agenti mohou žádat o rotaci hesel jménem spravovaných služeb:

Vytvořit žádost o heslo

POST /api/v1/agents/me/password-requests HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Získat čekající odpovědi

GET /api/v1/agents/me/password-requests HTTP/1.1
Authorization: Bearer <token>

Administrace žádostí o hesla

Metoda Endpoint Oprávnění Popis
GET /api/v1/admin/password-requests agent:admin Seznam všech žádostí
POST /api/v1/admin/password-requests/:id/approve agent:admin Schválit žádost
POST /api/v1/admin/password-requests/:id/reject agent:admin Zamítnout žádost

Objevování SSH klíčů

Agenti mohou hlásit objevené SSH klíče ze spravovaných hostitelů:

POST /api/v1/agents/me/ssh-discovery HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Správa SSH klíčů je dostupná na /api/v1/ssh/discovery (vyžaduje oprávnění ssh:discover).

Kontrola aktualizací agenta

GET /api/v1/agents/update/latest HTTP/1.1

Vrátí nejnovější dostupnou verzi agenta pro automatické aktualizace.

Související