Procedura

Sekrety i uprawnienia narzędzi

Narzędzia są tym, co odróżnia demonstrację od systemu produkcyjnego. W produkcji liczą się granice zaufania: model nie widzi sekretów, a decyzje o wykonaniu podejmuje warstwa polityk i bramek.

W skrócie
  • sekrety poza LLM (Vault/Broker), tokeny krótkotrwałe i zakresowe
  • bramki przed wykonaniem: Schema, RBAC, DLP, idempotency, rate limits
  • tryby wykonania: AUTO‑EXECUTE / REQUIRE APPROVAL / BLOCK
  • rotacja, revocation i kill‑switch jako element procesu, nie „opcjonalny dodatek”
Jeśli to ma wejść do procesu, proszę traktować ten rozdział jako standard operacyjny.
Zasada nadrzędna: model językowy nie jest miejscem na sekrety. Sekrety żyją w warstwie narzędziowej (Tool Gateway / Vault), a model dostaje wyłącznie to, co musi — w postaci danych wejściowych i wyniku działania narzędzia.

1. Cel i model zagrożeń

„Narzędzia” w chatbotach (API, bazy, systemy CRM, wyszukiwarki, płatności, wewnętrzne workflow) są siłą — i jednocześnie ryzykiem. Ten rozdział opisuje minimalny, produkcyjny standard: jak wydawać dostęp i sekrety tak, aby:

  • model nie miał bezpośredniego dostępu do kluczy,
  • uprawnienia były najmniejsze konieczne (least privilege),
  • każde wykonanie było audytowalne (trace_id + policy_version),
  • incydent dało się zatrzymać jednym ruchem (revocation / kill‑switch).

2. Zasady, które się nie starzeją

Zasada Co to znaczy w praktyce Najczęstszy błąd
Brak sekretów w promptach Model nie widzi kluczy API, tokenów, haseł ani connection stringów. „Tylko na chwilę” wklejony token do kontekstu debug.
Tokeny krótkotrwałe (TTL) Broker wydaje tokeny czasowe i zakresowe (scope), najlepiej per‑request. Długowieczne tokeny w konfiguracji aplikacji.
Uprawnienia per‑użytkownik / per‑rola Tożsamość użytkownika jest propagowana do warstwy narzędziowej (impersonation / delegated auth). „Service account” z uprawnieniami admin dla wszystkiego.
Bramki przed wykonaniem Schema, RBAC, DLP, rate‑limit, idempotency — zanim pójdzie request do narzędzia. Walidacja po fakcie, już po stronie narzędzia.
Audyt i ślad decyzji Logujesz nie tylko wynik, ale decyzje: polityka, wersja, odmowa, wyjątek. Log „success/fail” bez kontekstu.

3. Architektura: Tool Gateway + Broker sekretów

W dojrzałym wdrożeniu model nie „dzwoni” bezpośrednio do API. On prosi o wywołanie narzędzia, a decyzję podejmuje warstwa pośrednia.

Sekrety i uprawnienia narzędzi — przepływ i bramki
Praktyczny wzorzec: Tool Gateway to miejsce na polityki, a Vault/Broker to miejsce na sekrety. Model dostaje wynik narzędzia, nigdy sekret.

4. Polityki: scope, RBAC i tryby akceptacji

Najszybciej psuje się system, w którym „jakoś to będzie”. Dlatego warto mieć trzy tryby wykonania:

  • AUTO‑EXECUTE — tylko dla operacji bezpiecznych i odwracalnych (read‑only, niskie ryzyko),
  • REQUIRE APPROVAL — człowiek zatwierdza (np. akcje w systemie, wysyłka, modyfikacje),
  • BLOCK — operacja nie jest dostępna przez chat w ogóle.

Minimalny kontrakt polityki (czytelny i audytowalny):

{
  "tool": "crm.update_contact",
  "allowed_scopes": ["contact:write"],
  "requires_approval": true,
  "pii_allowed": false,
  "rate_limit_per_user": "10/min",
  "idempotency_required": true
}

5. Rotacja, wycofanie, incydent

Sekret, którego nie da się bezpiecznie wycofać, to nie sekret — to dług techniczny. W praktyce:

  • rotacja cykliczna (np. co 30–90 dni),
  • rotacja po incydencie (natychmiast),
  • centralny rejestr: kto, kiedy i dlaczego dostał scope,
  • kill‑switch na narzędzie i na klasę operacji (np. „write”).

6. Checklista wdrożeniowa

Kontrola Wymóg minimalny Artefakt
Vault/Broker sekrety tylko w vault, wydawanie tokenów TTL polityka vault + log dostępu
RBAC mapowanie ról → scope, bez „admin dla wszystkiego” macierz uprawnień
Bramki schema + DLP + idempotency + rate limits raport bramki (trace)
Audyt trace_id, policy_version, decyzja, wynik, błędy dashboard / logi
Incident revocation + kill‑switch + runbook runbook + test incydentu

7. Powiązane rozdziały

Na tej stronie
Spis
Następny krok

Jeśli wdrażasz narzędzia, kolejnym krokiem są testy kontraktowe i bramka CI.

Przejdź do testów kontraktowych