API pro správu konfigurací¶

Spravované konfigurační soubory, výsledky discovery agentů, konfigurační šablony a politika pojmenování tajemství

Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-10-22

Dostupnost funkce

Správa konfigurací je Enterprise funkce gatovaná licenční funkcí config_management (licence PoC a Enterprise). Endpointy konfiguračních souborů, výsledků discovery a politiky pojmenování tajemství bez ní vracejí 403 Forbidden. Viz Licencování a Průvodce správou konfigurací.

Přehled endpointů¶

Konfigurační soubory¶

Metoda	Endpoint	Oprávnění	Popis
GET	`/api/v1/config-files`	`config:read`	Seznam spravovaných konfiguračních souborů
GET	`/api/v1/config-files/:id`	`config:read`	Detail konfiguračního souboru s verzemi a referencemi na tajemství
GET	`/api/v1/config-files/overview`	`config:read`	Přehledové statistiky

Výsledky discovery¶

Metoda	Endpoint	Oprávnění	Popis
GET	`/api/v1/discovery-results`	`config:read`	Seznam výsledků discovery nahlášených agenty
POST	`/api/v1/discovery-results/:id/adopt`	`config:write`	Adopce výsledku do spravovaného konfiguračního souboru
POST	`/api/v1/discovery-results/:id/ignore`	`config:write`	Ignorování výsledku s uvedením důvodu

Konfigurační šablony¶

Metoda	Endpoint	Oprávnění	Popis
GET	`/api/v1/organizations/:id/config-templates`	`config:read`	Seznam šablon organizace
POST	`/api/v1/organizations/:id/config-templates`	`config:write`	Vytvoření šablony
PUT	`/api/v1/organizations/:id/config-templates/:templateId`	`config:write`	Aktualizace šablony
DELETE	`/api/v1/organizations/:id/config-templates/:templateId`	`config:write`	Smazání šablony
POST	`/api/v1/organizations/:id/config-templates/validate`	`config:write`	Validace definice šablony bez uložení
POST	`/api/v1/organizations/:id/config-templates/preview`	`config:write`	Náhled účinku resource visibility policy

Politika pojmenování tajemství¶

Metoda	Endpoint	Oprávnění	Popis
POST	`/api/v1/organizations/:id/secret-naming-policy/check`	`config:read`	Kontrola klíče tajemství vůči aktivní politice
GET	`/api/v1/organizations/:id/secret-naming-policy/compliance`	`config:read`	Report souladu napříč existujícími tajemstvími
GET	`/api/v1/organizations/:id/secret-naming-policy/suggest`	`config:read`	Návrh pravidel pojmenování z existujících klíčů
POST	`/api/v1/secret-naming-policy/validate`	`config:write`	Validace definice politiky

Šablony typu naming convention navíc vystavují endpointy render, parse, provision, export do Terraformu a cross-validate pod /api/v1/naming-conventions (config:read / config:write); nejsou součástí licenčně gatované skupiny.

Seznam konfiguračních souborů¶

GET /api/v1/config-files?project_id=550e8400-e29b-41d4-a716-446655440001 HTTP/1.1
Authorization: ******

Parametry dotazu¶

Parametr	Typ	Popis
`agent_id`	UUID	Filtr podle hlásícího agenta
`project_id`	UUID	Filtr podle vlastnícího projektu

Odpověď `200 OK`¶

[
  {
    "id": "c1d2e3f4-0000-0000-0000-000000000010",
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "project_id": "550e8400-e29b-41d4-a716-446655440001",
    "file_path": "/opt/billing/config/app.yaml",
    "file_name": "app.yaml",
    "file_type": "yaml",
    "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "file_size_bytes": 2048,
    "status": "managed",
    "rotation_status": "compliant",
    "integration_status": "pending",
    "compliance_score": 0.92,
    "discovery_method": "filesystem",
    "confidence_score": 0.85,
    "classification": "application",
    "policy_version": "2026-10-01T12:00:00Z-7",
    "discovered_at": "2026-10-20T06:00:00Z",
    "adopted_at": "2026-10-21T09:15:00Z",
    "current_version": 1,
    "secret_count": 3,
    "tags": ["billing", "prod"]
  }
]

Pole konfiguračního souboru¶

Pole	Popis
`status`	`discovered` (čeká na zpracování) nebo `managed` (přijato)
`rotation_status`	`unknown`, `compliant` nebo `overdue` — odvozeno ze stavu rotace odkazovaných tajemství
`classification`	`system`, `application` nebo `unknown`
`confidence_score`	Míra spolehlivosti discovery 0–1
`policy_version`	Verze discovery policy bundle, který výsledek vytvořil
`rewrite_plan`	Navržené kroky extrakce tajemství (viz průvodce)
`secret_count` / `secret_refs`	Tajemství odkazovaná souborem a jejich umístění
`versions`	Historie verzí (pouze endpoint detailu)

Získání konfiguračního souboru¶

GET /api/v1/config-files/c1d2e3f4-0000-0000-0000-000000000010 HTTP/1.1
Authorization: ******

Odpověď `200 OK`¶

Vrací objekt konfiguračního souboru včetně versions[] (číslo verze, hash obsahu, typ změny, shrnutí změny, důvod změny, autor změny, stav schválení, statistiky diffu) a secret_refs[] (ID tajemství, cesta umístění, řádek umístění). Obsah souboru se nikdy nevrací; vystaveny jsou pouze hashe a metadata.

Přehled konfigurací¶

GET /api/v1/config-files/overview HTTP/1.1
Authorization: ******

Odpověď `200 OK`¶

{
  "total_files": 42,
  "compliant_files": 35,
  "pending_files": 4,
  "critical_files": 3
}

Pole	Význam
`total_files`	Všechny spravované konfigurační soubory
`compliant_files`	Soubory s `rotation_status = compliant`
`pending_files`	Soubory se `status = discovered`
`critical_files`	Soubory s `rotation_status = overdue`

Seznam výsledků discovery¶

GET /api/v1/discovery-results?status=pending&agent_id=3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1
Authorization: ******

Parametry dotazu¶

Parametr	Typ	Popis
`agent_id`	UUID	Filtr podle hlásícího agenta
`status`	string	`pending` (výchozí pohled), `adopted` nebo `ignored`

Odpověď `200 OK`¶

[
  {
    "id": "d4e5f6a7-0000-0000-0000-000000000020",
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "file_path": "/opt/billing/config/app.yaml",
    "file_name": "app.yaml",
    "file_type": "yaml",
    "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "file_size_bytes": 2048,
    "discovery_source": "filesystem",
    "confidence_score": 0.85,
    "policy_version": "2026-10-01T12:00:00Z-7",
    "classification": "application",
    "detected_patterns": [
      { "key": "database.password", "line": 14, "severity": "high", "pattern": "generic-password" }
    ],
    "rewrite_plan": [
      {
        "key": "database.password",
        "action": "replace_plaintext",
        "secret_path": "application/app.yaml/database.password",
        "placeholder": "${MAZEVAULT:application/app.yaml/database.password}",
        "change_reason": "Move database password to vault",
        "location_path": "database.password",
        "location_line": 14
      }
    ],
    "potential_secrets": 1,
    "status": "pending"
  }
]

Hodnoty stavu výsledku discovery¶

Stav	Popis
`pending`	Čeká na revizi
`adopted`	Převeden na spravovaný soubor; je nastaveno `config_file_id`
`ignored`	Zamítnut; důvod je v `suppressed_reason`

Adopce výsledku discovery¶

Vytvoří spravovaný konfigurační soubor z výsledku discovery, volitelně extrahuje detekovaná tajemství do cílového projektu a vytvoří první verzi.

POST /api/v1/discovery-results/d4e5f6a7-0000-0000-0000-000000000020/adopt HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "content": "database:\n  host: db.internal\n  password: s3cr3t\n",
  "extract_secrets": true,
  "initial_comment": "Adopted from billing-01 discovery"
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`project_id`	string (UUID)	✅	Projekt, který bude konfigurační soubor vlastnit
`content`	string	—	Obsah souboru v otevřené podobě. Je-li uveden, vytvoří se verze 1 a může proběhnout extrakce tajemství
`extract_secrets`	boolean	—	Uložit detekované hodnoty tajemství jako projektová tajemství a zaznamenat `secret_refs`
`initial_comment`	string	—	Shrnutí změny uložené u verze 1

Odpověď `200 OK`¶

Vrací vytvořený objekt konfiguračního souboru (status: managed, current_version: 1). Operace je auditována jako ADOPT_CONFIG_DISCOVERY_RESULT.

Ignorování výsledku discovery¶

POST /api/v1/discovery-results/d4e5f6a7-0000-0000-0000-000000000020/ignore HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "reason": "Sample configuration shipped with the package; no live credentials"
}

Odpověď `200 OK`¶

{ "status": "ignored" }

Operace je auditována jako IGNORE_CONFIG_DISCOVERY_RESULT.

Seznam konfiguračních šablon¶

GET /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates HTTP/1.1
Authorization: ******

Odpověď `200 OK`¶

[
  {
    "id": "e5f6a7b8-0000-0000-0000-000000000030",
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Default discovery policy",
    "description": "Scan application directories for configuration files",
    "template_type": "discovery_policy",
    "definition": {
      "scan_paths": ["/opt", "/etc/app"],
      "scan_depth": 4,
      "file_types": ["env", "yaml", "json", "properties"],
      "confidence_threshold": 0.6,
      "auto_adopt": false,
      "classification": {
        "system_paths": ["/etc"],
        "application_paths": ["/opt"]
      },
      "rewrite_plan_rules": [
        {
          "name": "passwords",
          "key_pattern": "(?i)password|passwd|secret",
          "secret_path_template": "{{classification}}/{{file_name}}/{{key}}",
          "placeholder_template": "${MAZEVAULT:{{secret_path}}}",
          "change_reason": "Move credential to vault"
        }
      ]
    },
    "is_active": true,
    "is_default": true,
    "priority": 100
  }
]

Šablony typu resource visibility policy se vracejí pouze volajícím s administrátorskými právy.

Vytvoření konfigurační šablony¶

POST /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "name": "Generic secret patterns",
  "description": "Passwords, API keys and tokens",
  "template_type": "secret_pattern",
  "definition": {
    "patterns": [
      { "name": "generic-password", "type": "regex", "regex": "(?i)(password|passwd)\\s*[:=]\\s*\\S+", "severity": "high" },
      { "name": "bearer-token", "type": "regex", "regex": "(?i)bearer\\s+[a-z0-9._-]{20,}", "severity": "critical" }
    ],
    "entropy_threshold": 3.5,
    "min_length": 8,
    "max_length": 512
  },
  "is_active": true,
  "priority": 50
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`name`	string	✅	Název šablony
`description`	string	—	Popis
`template_type`	string	✅	`discovery_policy`, `parser`, `secret_pattern`, `exclusion_rule`, `naming_convention`, `secret_naming_policy`, `resource_visibility_policy`
`definition`	object	✅	JSON definice specifická pro typ (validována při zápisu)
`is_active`	boolean	—	Do policy bundle agenta se kompilují pouze aktivní šablony (výchozí `true`)
`is_default`	boolean	—	Označuje výchozí šablonu organizace pro daný typ
`priority`	integer	—	Nižší hodnoty se aplikují dříve (výchozí `100`)

Odpověď `201 Created`¶

Vrací vytvořenou šablonu. Je-li definice neplatná, API odpoví 400 Bad Request s details obsahujícím výsledek validace (viz níže).

Aktualizace konfigurační šablony¶

PUT /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates/e5f6a7b8-0000-0000-0000-000000000030 HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "is_active": false,
  "priority": 200
}

Částečné aktualizace jsou podporovány; změněná definition nebo template_type je znovu validována.

Odpověď `200 OK`¶

Vrací aktualizovanou šablonu.

Smazání konfigurační šablony¶

DELETE /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates/e5f6a7b8-0000-0000-0000-000000000030 HTTP/1.1
Authorization: ******

Odpověď `204 No Content`¶

Validace definice šablony¶

Validuje definici bez jejího uložení. Použijte z CI nebo před uložením šablony v UI.

POST /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates/validate HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "template_type": "exclusion_rule",
  "definition": {
    "excluded_paths": ["/proc", "/sys"],
    "excluded_extensions": [".log", ".bak"],
    "rules": [
      { "name": "node-modules", "type": "path", "pattern": "node_modules", "is_regex": false, "reason": "Third-party code" }
    ]
  }
}

Odpověď `200 OK`¶

{
  "valid": true,
  "warnings": [
    { "field": "rules[0].pattern", "message": "Pattern is a plain substring; consider anchoring it to a path segment" }
  ]
}

Pole	Popis
`valid`	`false`, pokud existuje alespoň jedna chyba
`errors[]` / `warnings[]`	Nálezy s `field` a `message`

Náhled definice šablony¶

Dostupné pro šablony typu resource_visibility_policy. Vyhodnotí definici vůči zdrojům projektu a ohlásí, které položky by odpovídaly.

POST /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/config-templates/preview HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "template_type": "resource_visibility_policy",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "environment": "prod",
  "resource_type": "secret",
  "definition": {
    "resource_rules": [
      { "id": "pci-secrets", "resource_type": "secret", "action": "admin_only", "match_mode": "tag", "field": "tags", "exact_values": ["pci"], "description": "Restrict PCI secrets to administrators" }
    ]
  }
}

Odpověď `200 OK`¶

{
  "total_count": 120,
  "matched_count": 18,
  "matched_items": [
    { "resource_type": "secret", "name": "PCI_DB_PASSWORD", "visible_to_non_admin": false, "matched_rule_ids": ["pci-secrets"], "match_reasons": ["tag pci"] }
  ],
  "unmatched_sample": [
    { "resource_type": "secret", "name": "APP_LOG_LEVEL", "visible_to_non_admin": true }
  ],
  "rule_breakdown": [
    { "rule_id": "pci-secrets", "resource_type": "secret", "field": "tags", "match_mode": "tag", "action": "admin_only", "match_count": 18 }
  ],
  "available_facets": [
    { "field": "tags", "values": ["pci", "billing", "internal"] }
  ]
}

Kontrola názvu tajemství¶

POST /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/secret-naming-policy/check HTTP/1.1
Authorization: ******
Content-Type: application/json

{ "key": "PROD_DATABASE_URL", "environment": "prod" }

Odpověď `200 OK`¶

{
  "allowed": true,
  "results": [
    { "rule_name": "SCREAMING_SNAKE_CASE", "pattern": "^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$", "enforcement": "block", "passed": true, "message": "" }
  ]
}

allowed je false, pokud selže pravidlo s enforcement: block; pravidla s enforcement: warn pouze přidávají položky do warnings.

Soulad pojmenování tajemství¶

GET /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/secret-naming-policy/compliance HTTP/1.1
Authorization: ******

Odpověď `200 OK`¶

{
  "total_secrets": 142,
  "compliant_count": 130,
  "violation_count": 12,
  "compliance_rate": 91.55,
  "rule_stats": [
    { "rule_name": "SCREAMING_SNAKE_CASE", "enforcement": "block", "pass_count": 130, "fail_count": 12 }
  ],
  "violations": [
    { "secret_id": "…", "secret_key": "dbPassword", "project_id": "…", "project_name": "Payment Gateway", "environment": "prod", "rule_name": "SCREAMING_SNAKE_CASE", "enforcement": "block" }
  ]
}

Návrh pravidel pojmenování¶

Analyzuje existující klíče tajemství a navrhne pravidla, kterým většina z nich vyhovuje.

GET /api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/secret-naming-policy/suggest HTTP/1.1
Authorization: ******

Odpověď `200 OK`¶

{
  "suggestions": [
    { "name": "SCREAMING_SNAKE_CASE", "pattern": "^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$", "description": "Enforce SCREAMING_SNAKE_CASE convention", "confidence": 0.87, "match_count": 87, "total_keys": 100 }
  ]
}

Validace definice politiky pojmenování tajemství¶

Validuje definici secret_naming_policy bez kontextu organizace.

POST /api/v1/secret-naming-policy/validate HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "definition": {
    "rules": [
      { "name": "SCREAMING_SNAKE_CASE", "pattern": "^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$", "enforcement": "block" }
    ]
  }
}

Odpověď `200 OK`¶

{ "valid": true }

Chybové odpovědi¶

Všechny endpointy používají standardní chybové odpovědi MazeVaultu:

HTTP status	Význam
`400 Bad Request`	Neplatné UUID, neplatné tělo, nebo definice šablony neprošla validací (`details` obsahuje výsledek validace)
`401 Unauthorized`	Chybějící nebo neplatný bearer token
`403 Forbidden`	Nedostatečné oprávnění, pro resource visibility policy jsou vyžadována administrátorská práva, nebo licenční funkce `config_management` není dostupná
`404 Not Found`	Konfigurační soubor, výsledek discovery nebo šablona neexistuje
`500 Internal Server Error`	Neočekávané selhání při adopci výsledku nebo extrakci tajemství

API pro správu konfigurací¶

Přehled endpointů¶

Konfigurační soubory¶

Výsledky discovery¶

Konfigurační šablony¶

Politika pojmenování tajemství¶

Seznam konfiguračních souborů¶

Parametry dotazu¶

Odpověď 200 OK¶

Pole konfiguračního souboru¶

Získání konfiguračního souboru¶

Odpověď 200 OK¶

Přehled konfigurací¶

Odpověď 200 OK¶

Seznam výsledků discovery¶

Parametry dotazu¶

Odpověď 200 OK¶

Hodnoty stavu výsledku discovery¶

Adopce výsledku discovery¶

Pole požadavku¶

Odpověď 200 OK¶

Ignorování výsledku discovery¶

Odpověď 200 OK¶

Seznam konfiguračních šablon¶

Odpověď 200 OK¶

Vytvoření konfigurační šablony¶

Pole požadavku¶

Odpověď 201 Created¶

Aktualizace konfigurační šablony¶

Odpověď 200 OK¶

Smazání konfigurační šablony¶

Odpověď 204 No Content¶

Validace definice šablony¶

Odpověď 200 OK¶

Náhled definice šablony¶

Odpověď 200 OK¶

Kontrola názvu tajemství¶

Odpověď 200 OK¶

Soulad pojmenování tajemství¶

Odpověď 200 OK¶

Návrh pravidel pojmenování¶

Odpověď 200 OK¶

Validace definice politiky pojmenování tajemství¶

Odpověď 200 OK¶

Chybové odpovědi¶

Související¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `201 Created`¶

Odpověď `200 OK`¶

Odpověď `204 No Content`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶