Průvodce nasazením agenta¶

Instalace, konfigurace a provoz agentů MazeVault

Verze dokumentu: 1.1.0
Poslední aktualizace: 2026-10-26

1. Přehled¶

MazeVault Agent je lehký Go binární soubor nasazený na infrastrukturních uzlech. Poskytuje:

Synchronizace tajemství — Automatické doručování tajemství do lokálních aplikací
Objevování certifikátů — Skenování infrastruktury pro certifikáty (souborový systém, JKS, Windows cert store)
Životní cyklus certifikátů — Automatizovaná obnova a nasazení spravovaných certifikátů
Real-time aktualizace — WebSocket připojení pro okamžitá push oznámení
Lokální proxy — Bezpečný proxy pro přístup aplikací k tajemstvím bez přímých API volání
Odolnost při výpadku — Lokální cache zajišťuje provoz během výpadků sítě

2. Podporované platformy¶

Platforma	Architektura	Poznámky
Linux	x86_64, ARM64	Ubuntu, RHEL, Rocky Linux, Debian, Alpine
Windows	x86_64	Windows Server 2019+
Kubernetes	—	Kontejnerový obraz agenta neexistuje; agenta spusťte na uzlech/VM (viz 3.3)

3. Instalace¶

3.1 Linux — Instalace binárního souboru¶

# Stažení agenta
curl -sL https://vault.example.com/api/v1/agents/download/linux-amd64 -o mazevault-agent
chmod +x mazevault-agent
sudo mv mazevault-agent /usr/local/bin/

# Vytvoření konfiguračního adresáře
sudo mkdir -p /etc/mazevault
sudo mkdir -p /var/lib/mazevault/certs

3.2 Linux — systemd služba¶

Vytvořte /etc/systemd/system/mazevault-agent.service:

[Unit]
Description=MazeVault Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/mazevault/agent.env
ExecStart=/usr/local/bin/mazevault-agent
Restart=always
RestartSec=10
User=mazevault
Group=mazevault

[Install]
WantedBy=multi-user.target

# Vytvoření servisního uživatele
sudo useradd -r -s /sbin/nologin mazevault

# Povolení a spuštění
sudo systemctl daemon-reload
sudo systemctl enable mazevault-agent
sudo systemctl start mazevault-agent

3.2.1 Linux — Rozložení instalované nasazovacím skriptem¶

Instalační skript generovaný v Nasazení → Nasadit (a balíček rpm/deb) používá toto rozložení. Je navržené pro hardened hostitele (CIS/STIG baseline), kde jsou /var a /tmp připojeny s noexec a SELinux je v režimu enforcing.

Cesta	Účel	Vlastník / práva
`/opt/mazevault-agent/bin/mazevault-agent`	Binárka agenta. Mimo `/var` (`noexec`), výchozí SELinux label `bin_t`. Adresář je zapisovatelný pro uživatele agenta, protože self-update připravuje novou binárku vedle běžící a runner vzdálené odinstalace spouští její kopii odtud	`mazevault-agent`, `0750` adresář / `0755` soubor
`/etc/mazevault/agent.yaml`	Konfigurace a stav (`agent.crt`, `agent.key`)	`mazevault-agent`, `0640`
`/etc/mazevault/certs`	Nasazené certifikáty (`cert_store_path`)	`mazevault-agent`, `0750`
`/var/log/mazevault`	Logy	`mazevault-agent`, `0750`
`/etc/systemd/system/mazevault-agent.service`	Unita: `ProtectSystem=strict`, `ReadWritePaths=/opt/mazevault-agent/bin /var/lib/mazevault /var/log/mazevault /etc/mazevault`	`root`, `0644`

Skript je idempotentní a lze jej bezpečně spustit opakovaně: před povolením služby ověří hostitele a migruje hostitele instalované s předchozím rozložením (binárka v /var/lib/mazevault/bin, drop-in přepisy ExecStart).

Krok	Chování
Preflight	Přítomnost potřebných nástrojů; `/opt/mazevault-agent/bin` není na `noexec` připojení; detekce režimu SELinux
Stažení	Ověření certifikátu se nikdy nevypíná. S CA MazeVault (`MAZEVAULT_CA_FILE` na serveru) ji stažení použije a při neúspěchu přejde na systémové úložiště důvěryhodných certifikátů; bez ní se použije systémové úložiště a žádný `ca.crt` se nezapisuje (`server_ca_file` zůstane prázdné)
Ověření	Kontrola ELF a velikosti; cosign podpis zaslaný serverem (`X-Signature`, `X-Signature-Key-Id`) se ověří proti podpisovým klíčům vloženým ve skriptu a `X-SHA256` se porovná se staženým souborem, takže nepodepsaný, pozměněný nebo useknutý přenos je odmítnut. Při neúspěšném stažení (včetně přenosu přerušeného po HTTP 200) se vypíše HTTP stav a tělo odpovědi serveru
Zkušební spuštění	Nová binárka se připraví jako `mazevault-agent.new` vedle cílové cesty a spustí se jako `mazevault-agent` (`mazevault-agent version`) před tím, než nahradí nainstalovanou binárku a než se zapíše unita — `noexec` připojení, zamítnutí SELinuxem nebo binárka sestavená pro novější glibc instalátor zastaví, dříve nainstalovaného agenta nechá nedotčeného a systemd nikdy neskončí v restartovací smyčce
SELinux	V režimu enforcing a s dostupným `semanage` se `/opt/mazevault-agent/bin` explicitně označí jako `bin_t`
Start	`systemctl enable` + `restart`; vypíše se výsledný stav a poslední řádky journalu s redigovanými tokeny a UUID

Návratové kódy: 2 selhal preflight, 3 selhalo stažení nebo ověření binárky, 4 služba se nespustila.

Hardened hostitelé

Nepřesouvejte binárku do adresáře vlastněného rootem, např. /usr/local/bin: self-update potřebuje adresář zapisovatelný uživatelem agenta a uvedený v ReadWritePaths.
Agenti před verzí 1.0.61 byli dynamicky linkovaní a vyžadovali glibc ≥ 2.34; na RHEL/Rocky/AlmaLinux 8 neběží (GLIBC_2.34 not found). Od 1.0.61 je agent linkován staticky.
Vzdálená odinstalace (Nasazení → Agenti) vyžaduje běh agenta jako root; agenti instalovaní skriptem běží jako mazevault-agent, použijte proto ruční kroky v kapitole 9, Životní cyklus agenta.

3.3 Kubernetes¶

MazeVault nepublikuje kontejnerový obraz agenta a režim agenta sidecar není podporovaný. Pro správu certifikátů, které používají workloady v Kubernetes, spusťte agenta na uzlech nebo VM, kde certifikáty leží (sekce 3.1–3.2), nebo použijte integrace MazeVault pro Kubernetes secrety. Binárka agenta se vždy stahuje z vašeho MazeVault backendu (/api/v1/agents/download/...), který servíruje podepsané binárky z MazeVault Harboru.

4. Konfigurace¶

4.1 Proměnné prostředí¶

Vytvořte /etc/mazevault/agent.env:

# Povinné
MAZEVAULT_SERVER_URL=https://vault.example.com
MAZEVAULT_BOOTSTRAP_TOKEN=mvbt_xxxxxxxxxxxxx

# Volitelné — Identita agenta
MAZEVAULT_AGENT_NAME=app-server-01
MAZEVAULT_PROJECT_ID=proj_xxxxxxxxxxxxx

# Volitelné — Úložiště
MAZEVAULT_CERT_STORE_PATH=/var/lib/mazevault/certs
MAZEVAULT_STATE_DIR=/etc/mazevault

# Volitelné — Logování
MAZEVAULT_LOG_LEVEL=info        # debug, info, warn, error
MAZEVAULT_LOG_FORMAT=text       # text, json

# Volitelné — Synchronizace
SYNC_INTERVAL_SECONDS=300       # Výchozí: 300 (5 minut)

4.2 Reference proměnných¶

Proměnná	Povinná	Výchozí	Popis
`MAZEVAULT_SERVER_URL`	Ano	—	URL backendu MazeVault
`MAZEVAULT_BOOTSTRAP_TOKEN`	Ano ¹	—	Jednorázový registrační token
`MAZEVAULT_AGENT_NAME`	Ne	hostname	Zobrazovaný název v UI
`MAZEVAULT_PROJECT_ID`	Ne	—	Project scope pro tajemství
`MAZEVAULT_CERT_STORE_PATH`	Ne	`/var/lib/mazevault/certs`	Adresář pro úložiště certifikátů
`MAZEVAULT_STATE_DIR`	Ne	`/etc/mazevault`	Adresář konfigurace a stavu
`MAZEVAULT_LOG_LEVEL`	Ne	`info`	Úroveň detailu logů
`MAZEVAULT_LOG_FORMAT`	Ne	`text`	Formát logů (`text` nebo `json`)
`SYNC_INTERVAL_SECONDS`	Ne	`300`	Interval synchronizace tajemství v sekundách

¹ Povinné pouze při prvotní registraci. Po bootstrapu agent používá mTLS certifikáty.

5. Bootstrap a registrace¶

Agent používá dvoufázový autentizační model:

Fáze 1: Bootstrap (jednorázový)¶

Vygenerujte bootstrap token ve webovém UI MazeVault: Nastavení → Nasazení → Agenti → Vygenerovat Bootstrap token
Nakonfigurujte agenta s MAZEVAULT_SERVER_URL a MAZEVAULT_BOOTSTRAP_TOKEN
Spusťte agenta — automaticky se zaregistruje přes POST /api/v1/agents/register

Fáze 2: mTLS (průběžná)¶

Po úspěšné registraci agent obdrží:

Klientský certifikát — Pro mutual TLS autentizaci
CA certifikát — Pro ověření serveru
Heartbeat interval — Doporučená frekvence hlášení stavu
Sync interval — Frekvence synchronizace tajemství

Veškerá další komunikace probíhá přes mTLS. Bootstrap token již není potřeba a může být odvolán.

┌──────────┐          ┌───────────────┐
│  Agent   │──────────│  MazeVault    │
│          │ Bootstrap│  Backend      │
│          │  Token   │               │
│          │◀─────────│               │
│          │ mTLS Cert│               │
│          │          │               │
│          │──────────│               │
│          │ mTLS     │               │
│          │ (průběžně)│               │
└──────────┘          └───────────────┘

6. Pravidelné operace¶

Agent automaticky spouští několik úloh na pozadí:

Operace	Interval	Popis
Synchronizace tajemství	Konfigurovatelný (výchozí 5m)	Synchronizuje tajemství z backendu do lokálního úložiště
Heartbeat	60 sekund	Hlásí stav, metriky (CPU, paměť, disk) a verzi backendu
Objevování certifikátů	1 hodina	Skenuje nakonfigurované cesty pro certifikáty (filesystem, JKS, Windows cert store)
Objevování konfigurací	Se skenem souborového systému	Skenuje cesty definované politikou pro konfigurační soubory (`.env`, YAML, JSON, INI, properties, TOML, XML), detekuje vložená tajemství a hlásí kandidáty — vyžaduje licenční funkci `config_management`; viz Správa konfigurací
Kontrola aktualizací	24 hodin	Kontroluje dostupnost novější verze agenta
Licenční heartbeat	5 minut	Odesílá telemetrii na licenční server (pokud je nakonfigurován)
K8s reconciliace	5 minut	Reconcilace Kubernetes Secret certifikátů (pouze K8s)
WebSocket reconnect	Exponenciální backoff	Udržuje real-time push připojení (1s → 2s → 4s → ...)

Všechny intervaly jsou fixní kromě synchronizace tajemství (SYNC_INTERVAL_SECONDS).

Aktualizace a spodní hranice pro rollback¶

Při startu a při každé kontrole aktualizací se agent zeptá backendu, jakou verzi mu nabízí politika verzí agenta (viz Proměnné prostředí § Binárky agenta). Novější verzi nainstaluje, nižší jen tehdy, když ji backend označí jako downgrade a není pod spodní hranicí pro rollback agenta. Každá binárka se před výměnou ověří (hash, podpis, hlášená verze). Hranice je nejvyšší z:

hranice zabudované v binárce agenta (zvyšují ji releasy MazeVault),
nejvyšší min_rollback_version, kterou agent přijal od backendu, uložené v <state_dir>/min-rollback-version (backend ji může jen zvýšit),
min_rollback_version v agent.yaml.

# /etc/mazevault/agent.yaml
min_rollback_version: v1.2.0   # nikdy neinstalovat verzi nižší než v1.2.0

Odmítnutou verzi agent zaloguje spolu s běžící verzí, nabízenou verzí a hranicí. Snížit hranici lze jen lokálně: snížení v agent.yaml pod uloženou hodnotu nic nezmění; hodnotu uloženou od backendu smaže

mazevault-agent -config /etc/mazevault/agent.yaml reset-min-rollback-version

Požadavky na nasazení certifikátů¶

Kromě pravidelných úloh posílá backend agentovi přes WebSocket požadavky na nasazení certifikátu, když běží rotace. Agent zpracovává tyto typy:

Požadavek	Co agent udělá
`certificate_sync`	Nainstaluje certifikát s klíčem do keystore (`jks`, `pkcs12`, `windows_my`) a řetězec vydavatelů do trust store platformy. Cíle `windows_root` / `windows_ca` dostávají pouze veřejné certifikáty — privátní klíč se do trust store nikdy nedostane.
`certificate_file_sync`	Zapíše soubory certifikátu podle content mode cíle (`public_only`, `public_chain`, `full_chain_with_key`, `key_only`): leaf, řetězec, klíč a volitelný sloučený bundle (PEM nebo PKCS#12). Privátní materiál má práva `0600`; původní soubory zůstávají jako `.BAK`.
`agent_command`	Spustí příkaz pro krok nasazení (restart služby, WLST restart skript, import do Oracle wallet přes `orapki`, import do trust store přes `keytool`). Spustí se pouze příkazy z allowlistu. Argumenty, které backend označí jako citlivé (hesla store a walletu), agent v auditním logu, odpovědi i chybových zprávách rediguje.

Allowlist příkazů¶

Agent má vestavěný allowlist (systemctl restart|reload, nginx -s reload, apachectl graceful, iisreset, recyklace IIS app poolu, orapki wallet import_pkcs12 nad PKCS#12 připraveným MazeVaultem a jeho úklid, keytool -importcert PEM vydavatele připraveného MazeVaultem do JKS/PKCS12 trust store a jeho úklid). Cokoliv dalšího — včetně WLST restart skriptu WebLogic cíle — je nutné výslovně povolit regulárním výrazem v konfiguraci agenta:

allowed_commands:
  - '^/opt/weblogic/scripts/restart-managed-server\.sh\s+[\w\-\./:= ]+$'

Vzory se porovnávají s celým příkazovým řádkem. Držte je úzké (absolutní cesty, žádné shellové metaznaky) — odmítnutý příkaz ukončí krok nasazení srozumitelnou chybou, místo aby se spustil.

Požadavky na verzi agenta

certificate_file_sync, agent_command a sémantika „pouze veřejné“ u windows_root/windows_ca vyžadují tuto nebo novější verzi agenta. Starší agent na takový požadavek odpoví explicitní chybou unsupported message type a krok nasazení selže rychle, místo aby materiál skončil na špatném místě.

7. Objevování certifikátů¶

Agent objevuje certifikáty napříč infrastrukturou a hlásí je backendu:

Zdroje objevování¶

Zdroj	Platforma	Popis
Souborový systém	Linux/Windows	Skenuje nakonfigurované adresáře pro PEM, DER, PFX soubory
Java KeyStore (JKS)	Všechny	Parsuje `.jks` a `.p12` soubory
Windows Certificate Store	Windows	Enumeruje systémové a uživatelské certifikátové úložiště
Kubernetes Secrets	K8s	Sleduje `kubernetes.io/tls` secrets

Konfigurace objevování¶

Cesty pro objevování se konfigurují ve webovém UI MazeVault:

Projekt → Nastavení → Objevování agenta → Cesty

Výsledky se zobrazí v pohledu Objevené certifikáty na dashboardu.

Discovery konfiguračních souborů se řídí šablonami discovery politik na úrovni organizace, nikoli výše uvedenými cestami; výsledky se zobrazují pod Enterprise Functions → Configuration Management → Discovered Configurations. Viz Správa konfigurací. Agenti také mohou doručovat externě vydané API tokeny do konfiguračních souborů jako cíle nasazení typu agent_file; viz Správa tokenů.

8. Monitoring¶

Endpoint stavu¶

Agent hlásí stav prostřednictvím heartbeatu. Monitorujte stav agentů ve webovém UI:

Nasazení → Agenti

Klíčové hlášené metriky¶

cpu_percent — Vytížení CPU agenta
memory_percent — Využití paměti agenta
secrets_synced — Počet synchronizovaných tajemství
certificates_managed — Počet spravovaných certifikátů
last_sync_time — Časové razítko poslední úspěšné synchronizace
uptime_seconds — Doba běhu agenta

Prometheus metriky¶

Backend vystavuje metriky agentů na /metrics:

mazevault_agents_online{environment="production"} 12
mazevault_agent_sync_operations_total{agent_id="agt_xyz"} 1842
mazevault_agent_discovery_findings_total{agent_id="agt_xyz"} 37

9. Řešení problémů¶

Agent se nespustí¶

# Kontrola logů
journalctl -u mazevault-agent -f

# Ověření konektivity
curl -sk https://vault.example.com/api/v1/health

Problém	Příčina	Řešení
`connection refused`	Backend nedostupný	Ověřte `MAZEVAULT_SERVER_URL` a pravidla firewallu
`certificate expired`	Certifikát agenta vypršel	Znovu zaregistrujte s novým bootstrap tokenem
`bootstrap token invalid`	Token vypršel nebo byl použit	Vygenerujte nový bootstrap token ve webovém UI
`TLS handshake error`	Neshoda CA certifikátu	Ověřte řetězec CA certifikátů
`status=203/EXEC` v `systemctl status`	systemd nemůže binárku spustit: `noexec` připojení (typicky `/var`), SELinux label nebo chybějící právo spuštění	Spusťte znovu instalační skript (instaluje do `/opt/mazevault-agent/bin`, viz 3.2.1); zkontrolujte `findmnt -T <adresář binárky>` a `ls -Z`
`GLIBC_2.34' not found`	Agent starší než 1.0.61 na hostiteli s glibc < 2.34 (RHEL/Rocky/Alma 8)	Nainstalujte agenta 1.0.61 nebo novějšího (staticky linkovaný)
Instalátor skončí kódem `2`, `3` nebo `4`	Selhal preflight, stažení/ověření, nebo start služby	Přečtěte vypsaný důvod; `3` s `HTTP 503` znamená, že server nemá nakonfigurované binárky agenta

Životní cyklus agenta (Nasazení → Agenti)¶

Registrovaní agenti se spravují v sekci Nasazení → Agenti přes nabídku akcí u každého řádku. Tyto operace pracují s identitou nainstalovaného agenta v řídicí rovině MazeVault a jsou odlišné od smazání vygenerovaného instalačního záznamu v sekci Nasazení → Nasadit.

Akce	Co dělá	Kdy použít
Odregistrovat	Vyřadí agenta, zneplatní jeho mTLS identitu a recovery tokeny, deaktivuje vazby na projekty a zablokuje veškeré budoucí runtime použití. Historie zůstává zachována. Zvolením bezpečnostní kategorie důvodu (kompromitace / ztracený credential / odcizený host) se akce zaznamená jako revokace.	Vyřazené, ztracené, offline nebo ručně odstraněné hosty.
Odinstalovat vzdáleně	Požádá připojeného agenta, aby se sám odinstaloval z hosta, a před dokončením nahlásí skutečný výsledek zpět. Podporováno na Linuxu (balíčková systemd instalace, agent běžící jako root) a na Windows (MSI service instalace; služba `MazeVaultAgent` je odebrána přes `msiexec`). Agent musí být aktuálně připojen. Agent je vyřazen až po potvrzení úspěšného odstranění; pokud odstranění selže, agent zůstane aktivní a konzole zobrazí Odinstalace selhala pro opakování nebo zásah.	Čisté odstranění agenta z dostupného Linux nebo Windows hosta.
Přeregistrovat / obnovit identitu	Vyřadí starou identitu a vydá jednorázový náhradní bootstrap token (platnost 24 h) pro opětovné zaregistrování hosta.	Vypršený nebo kompromitovaný mTLS certifikát; výměna hosta.

Před odregistrací se zobrazí náhled dopadu (spravované certifikáty, vazby na projekty, rotační cíle, SSH klíče, čekající keytab práce). Nevyřešená práce, jako čekající keytab nasazení nebo aktivně spravované certifikáty, vyžaduje pro pokračování volbu Force.

Odregistrace neodinstaluje binárku na hostu. Pro offline hosty nebo tam, kde vzdálená odinstalace není podporována (nebalíčkové/ruční instalace, macOS), agenta odregistrujte a odstraňte lokálně.

Linux:
sudo systemctl stop mazevault-agent && sudo systemctl disable mazevault-agent
sudo apt remove mazevault-agent   # nebo: sudo rpm -e mazevault-agent
sudo rm -rf /etc/mazevault /var/lib/mazevault /var/log/mazevault /opt/mazevault-agent
Windows (PowerShell, s oprávněním administrátora):
sc.exe stop MazeVaultAgent
$p = Get-WmiObject Win32_Product -Filter "Name='MazeVault Agent'"
if ($p) { $p.Uninstall() } else { sc.exe delete MazeVaultAgent }
Remove-Item -Recurse -Force "$env:ProgramData\MazeVault" -ErrorAction SilentlyContinue

Opětovná registrace¶

Pokud mTLS certifikát agenta vyprší nebo je kompromitován:

V sekci Nasazení → Agenti otevřete nabídku akcí agenta a zvolte Přeregistrovat / obnovit identitu (nebo Odregistrovat s bezpečnostním důvodem u kompromitovaného hosta).
Zkopírujte jednorázový náhradní bootstrap token z dialogu.
Odstraňte lokální stav na hostu: rm -rf /etc/mazevault/agent-state.json
Restartujte agenta s novým MAZEVAULT_BOOTSTRAP_TOKEN.

Ladící logování¶

Povolte podrobné logování pro diagnostiku:

MAZEVAULT_LOG_LEVEL=debug mazevault-agent

10. Bezpečnostní aspekty¶

Bootstrap tokeny jsou jednorázové a časově omezené (výchozí: 24 hodin)
mTLS certifikáty jsou vázány na konkrétního agenta a projekt
Data tajemství jsou šifrována při přenosu (TLS 1.2+) a lokálně uložena šifrovaně
Minimální oprávnění — agenti mají přístup pouze k tajemstvím přiřazeným jejich projektu
Žádné příchozí porty — agent iniciuje veškerá spojení (pouze odchozí)

Související¶

Agents API — REST API reference pro endpointy agentů
FAQ — Často kladené otázky
Škálování — Doporučení pro škálování agentů
Autentizace — Detaily autentizace agentů
Monitoring — Prometheus metriky pro agenty